Compatibility

This documents compatibility support with existing systems such as logging and warnings.

Logging Compatibility

logbook.compat.redirect_logging(set_root_logger_level=True)

Permanently redirects logging to the stdlib. This also removes all otherwise registered handlers on root logger of the logging system but leaves the other loggers untouched.

Parameters

set_root_logger_level – controls of the default level of the legacy root logger is changed so that all legacy log messages get redirected to Logbook

logbook.compat.redirected_logging(set_root_logger_level=True)

Temporarily redirects logging for all threads and reverts it later to the old handlers. Mainly used by the internal unittests:

from logbook.compat import redirected_logging
with redirected_logging():
    ...

class logbook.compat.RedirectLoggingHandler

A handler for the stdlib’s logging system that redirects transparently to logbook. This is used by the redirect_logging() and redirected_logging() functions.

If you want to customize the redirecting you can subclass it.

convert_level(level)

Converts a logging level into a logbook level.

convert_record(old_record)

Converts an old logging record into a logbook log record.

convert_time(timestamp)

Converts the UNIX timestamp of the old record into a datetime object as used by logbook.

emit(record)

Do whatever it takes to actually log the specified logging record.

This version is intended to be implemented by subclasses and so raises a NotImplementedError.

find_caller(old_record)

Tries to find the caller that issued the call.

find_extra(old_record)

Tries to find custom data from the old logging record. The return value is a dictionary that is merged with the log record extra dictionaries.

class logbook.compat.LoggingHandler(logger=None, level=0, filter=None, bubble=False)

Does the opposite of the RedirectLoggingHandler, it sends messages from logbook to logging. Because of that, it’s a very bad idea to configure both.

This handler is for logbook and will pass stuff over to a logger from the standard library.

Example usage:

from logbook.compat import LoggingHandler, warn
with LoggingHandler():
    warn('This goes to logging')

convert_level(level)

Converts a logbook level into a logging level.

convert_record(old_record)

Converts a record from logbook to logging.

convert_time(dt)

Converts a datetime object into a timestamp.

emit(record)

Emit the specified logging record. This should take the record and deliver it to whereever the handler sends formatted log records.

get_logger(record)

Returns the logger to use for this record. This implementation always return logger.

Warnings Compatibility

logbook.compat.redirect_warnings()

Like redirected_warnings() but will redirect all warnings to the shutdown of the interpreter:

from logbook.compat import redirect_warnings
redirect_warnings()

logbook.compat.redirected_warnings()

A context manager that copies and restores the warnings filter upon exiting the context, and logs warnings using the logbook system.

The channel attribute of the log record will be the import name of the warning.

Example usage:

from logbook.compat import redirected_warnings
from warnings import warn

with redirected_warnings():
    warn(DeprecationWarning('logging should be deprecated'))