Alpha Griffin Python Logging

Shawn Wilson f0b3f2acb2 saw_061117_1 - Use underscore in function parameters to avoid collision with user-supplied kwargs. 1 year ago
ag f0b3f2acb2 saw_061117_1 - Use underscore in function parameters to avoid collision with user-supplied kwargs. 1 year ago
api 0f8dc6e526 saw_031417_2 - Rebuild apidoc. 2 years ago
doc b2573bee22 saw_031417_1 - Building up a Makefile; utilizing Sphinx for documentation. 2 years ago
etc 8ebeda39f1 saw_031517_3 - Add logo. 2 years ago
.gitignore adf0d9bd52 saw_040917_2 - Fix for Python 2.7: skipping the enum, using simple names instead. 1 year ago
CHANGELOG f0b3f2acb2 saw_061117_1 - Use underscore in function parameters to avoid collision with user-supplied kwargs. 1 year ago
LICENSE b2573bee22 saw_031417_1 - Building up a Makefile; utilizing Sphinx for documentation. 2 years ago
Makefile 6027d85b09 formatting fix 2 years ago
README.rst adf0d9bd52 saw_040917_2 - Fix for Python 2.7: skipping the enum, using simple names instead. 1 year ago
setup.cfg fc4a34a371 saw_021817_1 - Initial commit. 2 years ago
setup.py d4d6625e5e saw_031517_3 - Merge pyproject for new doc theme. 2 years ago

README.rst


===========================
Alpha Griffin Python Logger
===========================

Logging system for Python.

.. contents:: Table of Contents
.. toctree::
API Documentation

These common log levels are defined:

1. **FATAL** - logic violation, major flaw, or potentially halting error
2. **ERROR** - these generally indicate a problem
3. **WARN** - warnings but not necessarily a problem
4. **INFO** - informational messages
5. **DEBUG** - verbose and often extraneous, but useful for debugging purposes


Build Overview
--------------

Both a Makefile and setup.py are provided and used. The setup.py uses Python's standard setuptools package and you can call this script directly to do the basic Python tasks such as creating a wheel, etc.

The most common project build tasks are all provided in the Makefile. To see the full list of project targets::

make help

Sphinx is used to generate html documentation and man pages. All documentation (html as well as man pages) may be regenerated at any time with::

make docs

Every so often, when new source class files are created or moved, you will want to regenerate the API documentation templates. These templates may be modified by hand so this task does not overwrite existing files; you'll need to remove any existing files from ``api/`` that you want recreated. Then generate the API templates and re-build all documentation as follows::

make apidoc
make docs

There's not much to do for a simple Python project but your build may want to do more. In any case you can call ``make python`` if you need to (in pyproject this target simply delegates to ``./setup.py build``).

Build all the common tasks (including documentation) as follows::

make all

To clean up all the common generated files from your project folder::

make clean

To install this project to the local system::

make install

Note that you may need superuser permissions to perform the above step.


Distributing
------------

To make a *binary* distribution::

make bdist

(in pyproject, the above step simply delegates to ``./setup.py bdist_wheel``)

The distributions will collect in the ``dist/`` directory.


Using
-----

You can control the logging level with one of the 5 numerical levels defined above. A value of ``None`` or ``0`` will disable logging. Use one of the 5 log print functions (``debug()``, ``info()``, ``warn()``, ``error()``, ``fatal()``) in places where you might otherwise have used ``print()``.

Example usage of the logging system in a Python script::

import ag.logging as log

# set global logging level
log.set(log.WARN) # see all WARN and higher (WARN, ERROR, FATAL)

# some log printing examples
log.warn('this warning message is shown at level 3')
log.debug('this debug message is NOT shown at level 3')

If you have not installed the project system-wide or you have some changes to try, you must add the project folder to Python's search path first::

import sys, os
sys.path.insert(0, os.path.abspath('/path/to/logpy'))
import ag.logging