loggers

Preconfigured loggers for various output targets and formats.

class StdLogger(name, level=10, fmt='{asctime:<23s} [{levelname:<8s}] {message} ({name})', stream='stdout')[source]

Bases: ArgRepr

Wrapped logger to stdout or stderr with a formatted StreamHandler.

Parameters:

name (str) – Name of the Logger. Typically set to __name__.
level (int, optional) – Minimum logging level. Defaults to 10 (= DEBUG).
fmt (str, optional) – Format string for the log messages in str.format() format. Defaults to “{asctime:<23s} [{levelname:<8s}] {message} ({name})”.
stream (str, optional) – Must be one of “stdout” or “stderr”. Defaults to “stdout”.

Raises:

TypeError – If stream is not a string.
ValueError – If stream is neither “stdout” nor “stderr”

Note

The instantiation of the actual, underlying Logger is delayed until it is first needed to facilitate usage in multiprocessing scenarios.

Warning

To avoid creating and adding a new Handler to the same stream every time the same Logger is requested, one of its existing StreamHandlers will be modified if there are any. A new one will be created and added only if there aren’t. By consequence, requesting the same Logger multiple times with a different level and/or a different fmt might change that Logger globally.

critical(message)[source]

Log a CRITICAL message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

debug(message)[source]

Log a DEBUG message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

error(message)[source]

Log an ERROR message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

info(message)[source]

Log an INFO message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

log(level, message)[source]

Log a message at the given level.

Parameters:

level (int) – The level to log at.
message (str) – The message to log.

Returns:

An empty tuple.

Return type:

tuple

property logger: The requested Logger with one StreamHandler configured to specs.

warning(message)[source]

Log a WARNING message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

class FileLogger(file, level=10, fmt='{asctime:<23s} [{levelname:<8s}] {message}', mode='a', encoding='utf-8', delay=True)[source]

Bases: ArgRepr

Wrapped logger to file with at least one formatted FileHandler.

Parameters:

file (str) – Full path to the file to log to, including file extension. If the parent directory does not exist, an attempt will be made to create it.
level (int, optional) – Minimum logging level. Defaults to 10 (= DEBUG).
fmt (str, optional) – Format string for the log messages in str.format() format. Defaults to “{asctime:<23s} [{levelname:<8s}] {message}”.
mode (str, optional) – Mode to open the file. Defaults to “a”.
encoding (str, optional) – Encoding to use when opening the file. Defaults to “utf-8”.
delay (bool, optional) – Whether to delay opening the file until it is first written to. Defaults to True.

Raises:

FileExistsError – If a different Logger already has a FileHandler to the very same file. Because the instantiation of the actual Logger is delayed until it is first needed (to facilitate usage in multiprocessing scenarios), raising the exception is also delayed.

Note

The mode and the encoding can not be changed on an existing log file.

critical(message)[source]

Log a CRITICAL message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

debug(message)[source]

Log a DEBUG message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

error(message)[source]

Log an ERROR message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

property handler_exists: Does a Logger with a Handler of the specified file already exist?

info(message)[source]

Log an INFO message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

log(level, message)[source]

Log a message at the given level.

Parameters:

level (int) – The level to log at.
message (str) – The message to log.

Returns:

An empty tuple.

Return type:

tuple

property logger: The requested Logger with one FileHandler configured to specs.

property name: The name given to the Logger based on the provided file name.

warning(message)[source]

Log a WARNING message.

Parameters:: message (str) – The message to log.
Returns:: An empty tuple.
Return type:: tuple

class JsonLogger(name, level=10, stream='stdout', field=('levelname', 'name'), *fields, **extras)[source]

Bases: ArgRepr

Wrapped logger to stdout or stderr with a JSON-formatted StreamHandler.

Parameters:

name (str) – Name of the Logger. Typically set to __name__.
level (int, optional) – Minimum logging level. Defaults to 10 (= DEBUG).
stream (str, optional) – Must be one of “stdout” or “stderr”. Defaults to “stdout”.
field (str or iterable, optional) – A single LogRecord attribute or an iterable thereof. All values that are not marked by “You shouldn’t need to format this yourself.” are allowed. Logged messages will be merged with a dictionary of these keys before being written to stream unless you explicitly refer to the LogRecord attribute “message”, in which case that field will contain the dictionary you want to log. Defaults to ("levelname", "name").
*fields (str) – Additional LogRecord attributes to merge with the log message.
**extras – Additional, static key-value pairs to merge into every log message.

Note

The instantiation of the actual, underlying Logger is delayed until it is first needed to facilitate usage in multiprocessing scenarios.

Warning

If the requested Logger already has a Handler to the requested stream, it will be deleted and replaced with a new one. By consequence, requesting the same Logger multiple times with different options might change that Logger globally.

critical(message)[source]

Log a CRITICAL message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

debug(message)[source]

Log a DEBUG message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

error(message)[source]

Log an ERROR message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

info(message)[source]

Log an INFO message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

log(level, message)[source]

Log a message at the given level.

Parameters:

level (int) – The level to log at.
message (Mapping) – The (dictionary) message to log.

Returns:

An empty tuple.

Return type:

tuple

property logger: The requested Logger with exactly one JsonStreamHandler.

warning(message)[source]

Log a WARNING message.

Parameters:: message (Mapping) – The (dictionary) message to log.
Returns:: An empty tuple.
Return type:: tuple

class JsonStreamHandler(stream='stdout', field=('levelname', 'name'), *fields, **extras)[source]

Bases: StreamHandler

StreamHandler for logging JSON-formatted messages.

Parameters:

stream (str, optional) – Must be one of “stdout” or “stderr”. Defaults to “stdout”.
field (str or iterable, optional) –
A single LogRecord attribute or an iterable thereof. All values that are not marked by “You shouldn’t need to format this yourself.” are allowed. Logged messages will be merged with a dictionary of these keys before being written to stream unless you explicitly refer to the LogRecord attribute “message”, in which case that field will contain the dictionary you want to log. Defaults to ("levelname", "name").
*fields (str) – Additional LogRecord attributes to merge with the log message.
**extras – Additional, static key-value pairs to merge into every log message.

Raises:

TypeError – If stream is not a string.
ValueError – If stream is neither “stdout” nor “stderr” or if any of the given fields are not a permissible LogRecord attribute.

static asctime(timestamp)[source]: Format a unix timestamp to string, including milliseconds.

property basics: LogRecord attributes to add to the log message.

format(record)[source]: Format the LogRecord as a JSON-serialized string.

formats

loggers.DEFAULT_FMT = '{asctime:<23s} [{levelname:<8s}] {message} ({name})'

loggers.SHORT_FMT = '{asctime:<23s} [{levelname:<8s}] {message}'

loggers.PID_FMT = '{asctime:<23s} [{levelname:<8s}] {message} ({name} | PID-{process})'

loggers.RAW_FMT = '{message}'

loggers.JSON_FMT = ('levelname', 'name')