Log - Logger — Logga 0 documentation

# 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

- Index
- Module Index
- Search Page