logwood 3.1.0

Simple, but fast logging library for Python 3.5+

This is a simple, but fast logging library. We traded features for speed.

Logwood is only tested with Python 3.5. There are no plans to support older versions.

import logwood
from logwood.handlers.stderr import ColoredStderrHandler

logwood.basic_config(
        level = logwood.INFO,
        handlers = [ColoredStderrHandler()]
)

logger = logwood.get_logger('LoggerName')
logger.info('Just FYI')
logger.warning('Six times seven is {:d}.', 42)

Features

While logwood is very lightweight (see the Compatibility section below) it still gives you a few nice features out of the box:

• Chunked syslog handler. Splits long messages and writes them to syslog piece by piece. Useful e.g. to work around maximum UDP packet size (logwood.handlers.chunked.ChunkedSysLogHandler).

• Alternative syslog handler that uses the standard syslog module to emit logs to local syslog. Benchmarks show this to be faster than connecting and writing to a socket directly (logwood.handlers.syslog.SysLogLibHandler).

• Threaded handler: executes any underlying handler in a separate thread to avoid blocking the main thread (logwood.handlers.threaded.ThreadedHandler).

• Colored logs on stderr (logwood.handlers.stderr.ColoredStderrHandler).

Compatibility with logging

Logwood API is somewhat similar to the standard logging, but we’ve made a few opinionated design decisions that do not make this a drop-in replacement:

• Loggers do not form a tree hierarchy. There are no child loggers and no handler or configuration inheritance. We found that such features make the logging module very slow.

• Logging config cannot be changed after loggers are created, and conversely no loggers may be created until logging is configured. Again, this is to make loggers as simple as possible.

• While %-style formatting is supported for historical reasons, logwood prefers the more powerful str.format. It tries to guess which formatting style you’re using but defaults to str.format (curly braces). This feature will be removed in a future major release and only str.format will be supported going forward.

logging -> logwood bridge

Call logwood.compat.redirect_standard_logging() to configure the standard logging module to send all messages to logwood for handling. You can use this to run a logwood-based application that nevertheless works with any 3rd-party libraries using logging.

py.test fixtures

For testing convenience there are two fixtures prepared: configure_and_reset_logwood and logwood_handler_mock. configure_and_reset_logwood is an autouse fixture, i.e. it is run before every test in projects that use logwood. It calls logwood.basic_config to set a stderr handler so you don’t have to care about logwood configuration in tests, and you can see logs when your test fails. The logwood_handler_mock fixture is a mock handler. This is useful for testing how your code uses logwood. It stores all messages in a dict of lists so you can easily find your messages. To identify the level you can use either strings (upper/lowercase) or constants from logging or logwood:

import logwood

def some_func():
        logger = logwood.get_logger('test_logger')
        logger.warning('Something is wrong with id {}', 42)


def test_logwood(logwood_handler_mock):
        some_func()
        assert 'Something is wrong with id 42' in logwood_handler_mock['WARNING']
        assert not logwood_handler_mock['error']
        assert any(m.startswith('Something') for m in logwood_handler_mock[logwood.WARNING])