clogging 0.3
Configurable Logging Boilerplate for the Autologging Module
License: MIT
Keywords: logging

#############
clogging
#############

clogging - Configurable Logging Boilerplate for the Autologging Module. 

About
************

Autologging (https://github.com/mzipay/Autologging) is an awesome module for
automatic logging in Python; however, it's not completely boilerplate free.

This module, clogging, addresses tasks that I would otherwise need to address
per application I build.

It features:

* Complete setup of a complex root Logger instance with a single call
* Configurable logging through YAML configuration or through keyword args
* Detailed output columns for lower logging levels
* Suppressed output columns for higher logging levels
* Optional rotating file handler

A demo "Hello World" application using clogging/autologging is available here,
    https://github.com/RyanMillerC/DemoCloggingApp

*Technically clogging could be used to configure the standard Python
logging module, since this doesn't directly interact with autologging,
but it was specifically created to fill in gaps and save me time
building applications that use autologging.*

Installation
************
 
::

  pip install clogging


Documentation
*************

Import this module with:
::

  import clogging

These are the two functions which will start logging.

start_from_yaml
~~~~~~~~~~~~~~~

Usage:
::

  log = clogging.start_from_yaml('path/to/file.yaml')

Start logging based on entries in a YAML configuration file. This is
designed to work with an existing application settings.yaml file, but
does not have to have anything additional for your application inside
it. All clogging entries should be nested under 'clogging' at the root
of the YAML file. If this is unclear, look at the example in the demo
application mentioned previous in this document.

This function returns a root Logger instance.

Your YAML file, at it's root level, should be structured like,
::


    clogging:
      file: log/app.log
      format: '%(asctime)22s - %(levelname)8s - %(name)20s - %(message)s'
      format_ext: '%(asctime)22s - %(levelname)8s - %(name)20s - \
                   %(funcName)20s - %(message)s'
      level: INFO
      max_file_size: 5 MB
      max_retention: 5
      verbose_levels: ['TRACE', 'DEBUG']
    app:  // Application or other configurations not necessary, shown
      ... // here for example only
    ...

All YAML settings are optional. If any setting is not supplied in the
configuration, it's default value will be used. For a list of available
options and defaults, see the Options section below.

To use clogging without a YAML file, see below.

start_from_args
~~~~~~~~~~~~~~~

Usage:
::

    log = clogging.start_from_args(
            file='log/app.log',
            format='%(asctime)22s - %(levelname)8s - %(name)20s - %(message)s',
            format_ext='%(asctime)22s - %(levelname)8s - %(name)20s - ' \
                    '%(funcName)20s - %(message)s',
            level='INFO',
            max_file_size='5 MB',
            max_retention=5,
            verbose_levels=['TRACE', 'DEBUG']
    )


Start logging based on keyword arguments. This function will accept the
same options names and values as start_from_yaml.

This function returns a root Logger instance.

All arguments are optional. If any argument is not supplied, it's default
value be used. It is even possible to run with 0 arguments, in which case
the default values would be used for everything.

For a list of available arguments and default values, see the Options
section below.

This example is the easiest way to add clogging into a project and start
INFO level logging to the console,
::

  log = clogging.start_from_args(level='INFO')

Or, another example to start DEBUG level logging with a rotating file handler,
::

  log = clogging.start_from_args(
          file='logs/app.log',
          level='DEBUG'
  )


Options
~~~~~~~

The following are available options and their descriptions. If any of
these options are not supplied, the default value will be used. These
option names can be set in either YAML format or as keyword arguments
for start_from_args.

:file:
  Path to log file. By default, file logging is disabled. If 'file' is set to a
  file path, for example, 'log/app.log', it will enable rotating file logging. 

  Note: In the example 'log/app.log', the log file itself, 'app.log', does not
  need to exist; however, the base directory 'log' MUST exist. 
  
  By default the log file will rotate when it reaches 5 MB, with up to 5
  rotations being kept before overwriting the oldest. These values can be
  configured using 'max_file_size' and 'max_retention'.

  Default: None

:format:
  Logging format for all non-verbose levels. By default non-verbose is
  considered to be INFO and higher.

  Default: '%(asctime)22s - %(levelname)8s - %(name)20s - %(message)s'

:format_ext:
  Logging format for all verbose levels. By default this is considered
  to be DEBUG and TRACE levels. Additional levels can be added to use this
  format in 'verbose_levels'.
  
  Default: '%(asctime)22s - %(levelname)8s - %(name)20s - %(funcName)20s - %(message)s'

:level:
  Logging level.

  Default: 'INFO'

:max_file_size:
  Maximum log file size before rollover. This value can either be an integer
  byte size or a proper string like: "5 MB", "50 kB", etc. Setting to 0
  will cause the log file to grow infinitely with no rollover. This option has
  no impact if 'file' is set to None.

  Default: '5 MB'

:max_retention:
  Maximum number of rollover logs to keep. Logs will be saved as log.1, log.2,
  ...etc., until max_retention is reached. At that point the oldest of
  the rollover logs will be purged. This option has no impact if 'file' is set
  to None, or if 'max_file_size' is set to 0.

  Default: 5

:verbose_levels:
  Logging levels in this list are considered verbose levels and will use
  format_ext for formatting. This is typically done to follow low
  level logs which show funcName alongside name.
  
  Default: ['TRACE', 'DEBUG']

Author
************
* Ryan Miller - ryan@devopsmachine.com