Autologging - easier logging and tracing for Python classes

http://ninthtest.info/python-autologging/

Introduction

Autologging eliminates boilerplate logging setup code and tracing code,and provides a means to separate application logging from program flowand data tracing.

Python modules that make use of Autologging are cleaner, leaner, andmore resilient to changes that would otherwise require updating tracingstatements.

Autologging allows for tracing to be configured (and controlled)independently from application logging. Toggle tracing on/off, writetrace log records to a separate log, and use different formatting fortrace log entries - all via standard Python logging facilities, andwithout affecting your application logging.

What's in the autologging namespace?

Autologging exposes two decorators and a custom log level:

loggedDecorate a class to create a __log member. The logger is named bydefault to match the dotted-name of the containing class. A functionmay also be decorated, creating a _log attribute on the functionobject whose default name matches the containing module.A specifically-named logger may also be passed to the decorator (i.e.logged(my_logger)).

tracedDecorate a class to provide automatic method call/return tracing. Bydefault, all class, static, and instance methods are traced (excluding"special" methods, with the exception of __init__ and __call__).As with the logged decorator, the default name of the tracing loggermatches the dotted-name of the containing class and may be overridden bypassing a specifically-named logger to the decorator.Additionally, this decorator accepts multiple string arguments thatexplicitly name the methods to be traced (and may even name"special" methods).

Module-level functions may also be traced using this decorator.

New in version 1.2.0: automatic yield/stop tracing of Pythongenerator iterators(if the generatorfunction is traced).

TRACEThe autologging.TRACE (level 1) log level is registered with thePython logging module when Autologging is imported so that tracingcan be configured and controlled independently of application logging.

Tracing may be disabled entirely by setting theAUTOLOGGING_TRACED_NOOP environment variable or by calling theautologging.install_traced_noop() function.

A brief example

A simple logged and traced class:

 1 import logging 2 import sys 3 4 from autologging import logged, TRACE, traced 5 6 @traced 7 @logged 8 class Example: 910     def __init__(self):11         self.__log.info("initialized")1213     def backwards(self, *words):14         for word in words:15             yield "".join(reversed(word))161718 if __name__ == "__main__":19     logging.basicConfig(20             level=TRACE, stream=sys.stderr,21             format="%(levelname)s:%(filename)s,%(lineno)d:%(name)s.%(funcName)s:%(message)s")22     example = Example()23     for result in example.backwards("spam", "eggs"):24         print(result)

Logging and tracing output:

$ python example.pyTRACE:example.py,10:__main__.Example.__init__:CALL *() **{}INFO:example.py,11:__main__.Example.__init__:initializedTRACE:example.py,11:__main__.Example.__init__:RETURN NoneTRACE:example.py,13:__main__.Example.backwards:CALL *('spam', 'eggs') **{}TRACE:example.py,15:__main__.Example.backwards:RETURN <generator object backwards at 0x7fa534d61eb0>TRACE:example.py,15:__main__.Example.backwards:YIELD 'maps'mapsTRACE:example.py,15:__main__.Example.backwards:YIELD 'sgge'sggeTRACE:example.py,15:__main__.Example.backwards:STOP

Installation

The easiest way to install Autologging is to usepip:

$ pip install Autologging

Source installation

Clone or fork the repository:

$ git clone https://github.com/mzipay/Autologging.git

Alternatively, download and extract a source .zip or .tar.gz archivefrom https://github.com/mzipay/Autologging/releases,https://pypi.python.org/pypi/Autologging orhttps://sourceforge.net/projects/autologging/files/.

Run the test suite and install the autologging module: (make sure youhave setuptools installed!)

$ cd Autologging$ python setup.py test$ python setup.py install

Binary installation

Download the Python wheel (.whl) or a Windows installer fromhttps://pypi.python.org/pypi/Autologging orhttps://sourceforge.net/projects/autologging/files/.

(Use pip orwheel to install the .whl.)