logquacious 0.3.0

Quick start

To get started, first make sure logquacious is installed:

$ pip install logquacious

You’ll also need to set up logging for your application. For this example, we’ll use a really simple configuration:

import logging

logging.basicConfig(format='%(levelname)s: %(message)s', level=logging.DEBUG)

The main interface to logquacious is the LogManager, which can be used for normal logging:

import logquacious

log = logquacious.LogManager(__name__)

log.debug('Nothing to see here.')

Due to our simplified logging format defined earlier, that would output:

DEBUG: Nothing to see here.

That isn’t a very interesting example. In addition to basic logging, LogManager has a context attribute for use as a context manager:

>>> with log.context.debug('greetings'):
...    print('Hello!')
DEBUG: Enter greetings
Hello!
DEBUG: Exit greetings

The same attribute can be used as a decorator, as well:

@log.context.info
def divide(numerator, denominator):
    if denominator == 0:
        log.warning('Attempted division by zero. Returning None')
        return None
    return numerator / denominator

>>> divide(1, 0)
INFO: Call `divide()`
WARNING: Attempted division by zero. Returning None
INFO: Return from `divide`

Even better, you can log input arguments as well:

@log.context.info(show_args=True, show_kwargs=True)
def greet(name, char='-'):
    msg = 'Hello, {name}!'.format(name=name)
    print(msg)
    print(char * len(msg))

>>> greet('Tony', char='*')
INFO: Call `greet('Tony', char='*')`
Hello, Tony!
************
INFO: Return from `greet`

There’s also a special context manager for suppressing errors and logging:

with log.and_suppress(ValueError, msg="It's ok, mistakes happen"):
    raise ValueError('Test error')

[ERROR] It's ok, mistakes happen
Traceback (most recent call last):
  File "/Users/tyu/code/logquacious/logquacious/log_manager.py", line 103, in and_suppress
    yield
  File "scripts/example.py", line 26, in <module>
    raise ValueError('Test error')
ValueError: Test error

Configuration

The message templates used by LogManager.context can be configured to your liking by passing a context_templates argument to LogManager:

log = logquacious.LogManager(__name__, context_templates={
    'context.start': '=============== Enter {label} ===============',
    'context.finish': '=============== Exit {label} ===============',
})

with log.context.debug('greetings'):
    print('Hello!')

[DEBUG] =============== Enter greetings ===============
Hello!
[DEBUG] =============== Exit greetings ===============

The general format for context_templates keys is:

[CONTEXT_TYPE.]('start'|'finish')[.LOG_LEVEL_NAME]

where square-brackes marks optional fields.

CONTEXT_TYPE can be any of the following:

• function: Template used when called as a decorator.

• context: Template used when called as a context manager.

LOG_LEVEL_NAME can be any of the following logging levels:

• DEBUG

• INFO

• WARNING

• ERROR

• CRITICAL

For example, consider the cascade graph for function.start.DEBUG, which looks like:

     function.start.DEBUG
          /       \
start.DEBUG       function.start
          \       /
            start

The cascade is performed using a breadth-first search. If function.start.DEBUG is not defined, check start.DEBUG then check function.start BEFORE checking start.

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

0.3.0 (2018-10-05)

• Add decorator support for log.and_suppress and log.and_reraise context managers

• Suppress logging for null/empty log message templates

0.2.0 (2018-10-03)

Changed default templates. In 0.1.0, the templates were:

DEFAULT_TEMPLATES = {
    'start': 'Start {label}',
    'finish': 'Finish {label}',
}

These defaults have been changed to:

DEFAULT_TEMPLATES = {
    'start': 'Enter {label}',
    'finish': 'Exit {label}',
    'function.start': 'Call `{label}({arguments})`',
    'function.finish': 'Return from `{label}`',
}

0.1.0 (2018-10-03)

• First release on PyPI.