Utilities

Misc. Utilities

This documents general purpose utility functions available in Logbook.

logbook.debug(*args, **kwargs)

Logs a LogRecord with the level set to DEBUG.

logbook.info(*args, **kwargs)

Logs a LogRecord with the level set to INFO.

logbook.warn(*args, **kwargs)

Logs a LogRecord with the level set to WARNING. This function has an alias named warning().

logbook.warning(*args, **kwargs)

Alias for warn().

logbook.notice(*args, **kwargs)

Logs a LogRecord with the level set to NOTICE.

logbook.error(*args, **kwargs)

Logs a LogRecord with the level set to ERROR.

logbook.exception(*args, **kwargs)

Works exactly like error() just that the message is optional and exception information is recorded.

logbook.catch_exceptions(*args, **kwargs)

A context manager that catches exceptions and calls exception() for exceptions caught that way. Example:

with logger.catch_exceptions():
    execute_code_that_might_fail()

logbook.critical(*args, **kwargs)

Logs a LogRecord with the level set to CRITICAL.

logbook.log(level, *args, **kwargs)

Logs a LogRecord with the level set to the level parameter. Because custom levels are not supported by logbook, this method is mainly used to avoid the use of reflection (e.g.: getattr()) for programmatic logging.

logbook.set_datetime_format(datetime_format)

Set the format for the datetime objects created, which are then made available as the LogRecord.time attribute of LogRecord instances.

Parameters

datetime_format – Indicates how to generate datetime objects.

Possible values are:

“utc”

LogRecord.time will be a datetime in UTC time zone (but not time zone aware)

“local”

LogRecord.time will be a datetime in local time zone (but not time zone aware)

A callable returning datetime instances

LogRecord.time will be a datetime created by datetime_format (possibly time zone aware)

This function defaults to creating datetime objects in UTC time, using datetime.utcnow(), so that logbook logs all times in UTC time by default. This is recommended in case you have multiple software modules or instances running in different servers in different time zones, as it makes it simple and less error prone to correlate logging across the different servers.

On the other hand if all your software modules are running in the same time zone and you have to correlate logging with third party modules already logging in local time, it can be more convenient to have logbook logging to local time instead of UTC. Local time logging can be enabled like this:

import logbook
from datetime import datetime
logbook.set_datetime_format("local")

Other uses rely on your supplied datetime_format. Using pytz for example:

from datetime import datetime
import logbook
import pytz

def utc_tz():
    return datetime.now(tz=pytz.utc)

logbook.set_datetime_format(utc_tz)

Slow Operations Logging

logbook.utils.logged_if_slow(*args, **kwargs)

Context manager that logs if operations within take longer than threshold seconds.

Parameters

• threshold – Number of seconds (or fractions thereof) allwoed before logging occurs. The default is 1 second.

• logger – Logger to use. The default is a ‘slow’ logger.

• level – Log level. The default is DEBUG.

• func – (Deprecated). Function to call to perform logging.

The remaining parameters are passed to the log() method.

Deprecations

logbook.utils.deprecated(func=None, message=None)

Marks the specified function as deprecated, and emits a warning when it’s called.

>>> @deprecated(message='No longer supported')
... def deprecated_func():
...     pass

This will cause a warning log to be emitted when the function gets called, with the correct filename/lineno.

New in version 0.12.

logbook.utils.suppressed_deprecations()

Disables deprecation messages temporarily

>>> with suppressed_deprecations():
...    call_some_deprecated_logic()

New in version 0.12.