Log - Logger

The logga module wraps the standard Python logging module and abstract some of the messy parts. logging itself is is similar to (possibly even motivated by) the log4j facility. Most importantly, logging guarantees a singleton object that can be used throughout your project.

One of the handiest features with logga is that it automatically detects the output stream and is able to direct the logging ouput to STDOUT or to a file stream (if configured).

Simplest Usage (Console)

Simply import the logga log handler object into your project.

Note

Behind the scenes, the logga log handler object is instantiated through the module-level function logging.getLogger(name). Multiple calls to getLogger() with the same name will always return a reference to the same Logger object.

name is defined as the highest level Python calling module. For example, in the Module Usage (File-based Configuration) sample below, name will be you_beaut.py. For normal console-based output, name would be <stdin>.

The following example demonstrates usage directly under the Python interpreter:

$ python
>>> from logga import log
>>> log.debug('This is a DEBUG level logging')
2014-06-26 10:07:59,297 DEBUG:: This is a DEBUG level logging
>>> log.info('This is a INFO level logging')
2014-06-26 10:08:12,481 INFO:: This is a INFO level logging

Note

This example demonstrates console-based usage that writes to STDOUT

Module Usage (File-based Configuration)

Logging from your *.py is probably a more useful proposition. Similarly, import the logga to your python module. To demonstrate, add the following code into a file called you_beaut.py:

from logga import log

log.debug('Log from inside my Python module')

To execute:

$ python you_beaut.py
2014-06-26 10:41:15,036 DEBUG:: Log from inside my Python module

But what if you want to log to a file? In this case you will have to provide a configuration file. The structure of the config is standard logging. In this case, place the following into a the file called log.conf in the same directory as you_beaut.py:

[loggers]
keys=root,you_beaut.py,console

[handlers]
keys=youBeautFileHandler,consoleHandler

[formatters]
keys=simpleFormatter

[logger_root]
level=DEBUG
handlers=consoleHandler

[logger_console]
level=DEBUG
handlers=consoleHandler
qualname=console
propagate=0

[logger_you_beaut.py]
level=DEBUG
qualname=you_beaut.py
handlers=youBeautFileHandler

[handler_youBeautFileHandler]
class=handlers.TimedRotatingFileHandler
level=DEBUG
formatter=simpleFormatter
args=(os.path.join(os.sep, 'var', 'tmp', 'you_beaut.log'), 'midnight')

[handler_consoleHandler]
class=StreamHandler
level=DEBUG
formatter=simpleFormatter
args=(sys.stdout, )

[formatter_simpleFormatter]
format=%(asctime)s (%(levelname)s): %(message)s
datefmt=

Now when you $ python you_beaut.py you will notice that output to the console is suppressed. Instead, the output is directed to a file stream defined by handler_youBeautFileHandler section from the log.conf file. To verify:

$ cat /var/tmp/you_beaut.log
2014-06-26 11:39:34,903 (DEBUG): Log from inside my Python module

Functions

logga.set_console()

Drop back to the root logger handler. This is typically the console.

This can be used to override the logging file output stream and send log messages to the console. For example, consider the following code that has a log.conf that writes to the log file my.log:

from logga import log, set_console
set_console()
log.debug('Log from inside my Python module')

The set_console() call will force the log message to write Log from inside my Python module to the console.

logga.set_log_level(level='INFO')

Set the lower threshold of logged message level. Level defaults to INFO. All default log levels are supported NOTSET, DEBUG, INFO, WARNING, ERROR and CRITICAL in order of severity.

For example:

>>> from logga import log, set_log_level
>>> log.debug('This DEBUG message should display')
2014-06-30 12:50:48,407 DEBUG:: This DEBUG message should display
>>> set_log_level(level='INFO')
>>> log.debug('This DEBUG message should now not display')
>>> log.debug('This DEBUG message should now not display')
>>> log.info('This INFO message should display')
2014-06-30 12:51:44,782 INFO:: This INFO message should display
Kwargs:
level: the lower log level threshold. All log levels including and above this level in serverity will be logged
logga.suppress_logging()

Provides an overriding (to level CRITICAL) suppression mechanism for all loggers which takes precedence over the logger`s own level.

When the need arises to temporarily throttle logging output down across the whole application, this function can be useful. Its effect is to disable all logging calls below severity level CRITICAL. For example:

>>> from logga import log, suppress_logging
>>> log.debug('This DEBUG message should display')
2014-06-30 13:00:39,882 DEBUG:: This DEBUG message should display
>>> suppress_logging()
>>> log.debug('This DEBUG message should now not display')
>>> log.critical('But CRITICAL messages will get through')
2014-06-30 13:02:59,159 CRITICAL:: But CRITICAL messages will get through
logga.enable_logging()

Opposite of the logga.suppress_logging() function.

Re-enables logging to DEBUG level and above:

>>> from logga import log, suppress_logging, enable_logging
>>> suppress_logging()
>>> log.debug('This DEBUG message should now not display')
>>> enable_logging()
>>> log.debug('This DEBUG message should now display')
2014-06-30 13:08:22,173 DEBUG:: This DEBUG message should now display
logga.autolog(message)

Automatically log the current function details.

Used interchangeably with the log handler object. Handy for for verbose messaging during development by adding more verbose detail to the logging message, such as the calling function/method name and line number that raised the log call:

>>> from logga import autolog
>>> autolog('Verbose')
2014-06-30 13:13:08,063 DEBUG:: Verbose: <module> in <stdin>:1
>>> log.debug('DEBUG message')
2014-06-30 13:15:35,319 DEBUG:: DEBUG message
>>> autolog('DEBUG message')
2014-06-30 13:15:41,760 DEBUG:: DEBUG message: <module> in <stdin>:1
Args:
message: the log message to display

Indices and tables