# `cement.ext.ext_colorlog`

The ColorLog Extension provides logging based on the standard `logging` module and is a drop-in replacement for the default log handler `cement.ext.ext_logging.LoggingLogHandler`.

## Requirements

> - ColorLog (`pip install colorlog`)

## Configuration

This handler honors all of the same configuration settings as the `LoggingLogHandler` including:

> - level
> - file
> - to_console
> - rotate
> - max_bytes
> - max_files

In addition, it also supports:

> - colorize_file_log
> - colorize_console_log

A sample config section (in any config file) might look like:

    [log.colorlog]
    file = /path/to/config/file
    level = info
    to_console = true
    rotate = true
    max_bytes = 512000
    max_files = 4
    colorize_file_log = false
    colorize_console_log = true

## Usage

    from cement.core.foundation import CementApp

    class MyApp(CementApp):
        class Meta:
            label = 'myapp'
            extensions = ['colorlog']
            log_handler = 'colorlog'

    with MyApp() as app:
        app.run()
        app.log.debug('This is my debug message')
        app.log.info('This is my info message')
        app.log.warning('This is my warning message')
        app.log.error('This is my error message')
        app.log.fatal('This is my critical message')

The colors can be customized by passing in a `colors` dictionary mapping overriding the `ColorLogHandler.Meta.colors` meta-data:

    from cement.core.foundation import CementApp
    from cement.ext.ext_colorlog import ColorLogHandler

    COLORS = {
        'DEBUG':    'cyan',
        'INFO':     'green',
        'WARNING':  'yellow',
        'ERROR':    'red',
        'CRITICAL': 'red,bg_white',
    }

    class MyApp(CementApp):
        class Meta:
            label = 'myapp'
            log_handler = ColorLogHandler(colors=COLORS)

Or by sub-classing and creating your own custom class:

    from cement.core.foundation import CementApp
    from cement.ext.ext_colorlog import ColorLogHandler

    class MyCustomLog(ColorLogHandler):
        class Meta:
            label = 'my_custom_log'
            colors = {
                'DEBUG':    'cyan',
                'INFO':     'green',
                'WARNING':  'yellow',
                'ERROR':    'red',
                'CRITICAL': 'red,bg_white',
            }

    class MyApp(CementApp):
        class Meta:
            label = 'myapp'
            log_handler = MyCustomLog

class `cement.ext.ext_colorlog.``ColorLogHandler`(*args, **kw)

  Bases: `cement.ext.ext_logging.LoggingLogHandler`

  This class implements the `cement.core.log.ILog` interface. It is a sub-class of `cement.ext.ext_logging.LoggingLogHandler` which is based on the standard `logging` library, and adds colorized console output using the ColorLog library.

  Note This extension has an external dependency on `colorlog`. You must include `colorlog` in your applications dependencies as Cement explicitly does not include external dependencies for optional extensions.

  class `Meta`

    Bases: `object`

    Handler meta-data.

    `colors` = {'CRITICAL': 'red,bg_white', 'DEBUG': 'cyan', 'ERROR': 'red', 'INFO': 'green', 'WARNING': 'yellow'}

      Color mapping for each log level

    `config_defaults` = {'colorize_console_log': True, 'colorize_file_log': False, 'file': None, 'level': 'INFO', 'max_bytes': 512000, 'max_files': 4, 'rotate': False, 'to_console': True}

      Default configuration settings. Will be overridden by the same settings in any application configuration file under a `[log.colorlog]` block.

    `formatter_class`

      alias of `builtins.ColoredFormatter`

    `formatter_class_without_color`

      alias of `logging.Formatter`

    `label` = 'colorlog'

      The string identifier of the handler.