logutils.logutils module

Contains the functions/classes that are exposed by logutils’ API.

Examples

The logger can be initialized before logging is configured:

>>> logger = Logger("test")

But should be configured before logging any messages. The call to init_logging below configures our application to log all INFO messages (or higher) to stderr using colorful output and all DEBUG messages (or higher) to the “test.log” file in JSON:

>>> init_logging(
...     logs=[
...         Log(file="stderr", format="color", level="INFO"),
...         Log(file="test.log", format="json", level="DEBUG"),
...     ]
... )

Note that we can use both string format arguments and keyword arguments:

>>> logger.info("This logger is %s!", "awesome", reasons_not_to_use=None)

This logger can also be bound for context-specific logging:

>>> log = logger.bind(x=1, y=2)
>>> log.info("This log record will contain x, y, and z.", z=3)

As a best practice, when a function contains log messages, you should bind a logger to the current function’s arguments at the start of the function. We have written a special logger method just for this purpose:

>>> log = logger.bind_fargs(arg1="a", arg2="b", arg3="c")
>>> log.trace("This is TRACE level message!")

For less typing and to prevent duplicating the function’s argument names, you can also pass in a dictionary as the first argument to the bind_fargs method:

>>> log = logger.bind_fargs(locals())
class BetterBoundLogger(logger, processors, context)[source]

Bases: structlog.stdlib.BoundLogger

A better version of structlog’s standard BoundLogger.

Used to add additonal methods to the default BoundLogger.

Parameters

  • logger (Any) –

  • processors (Iterable[Callable[[Any, str, MutableMapping[str, Any]], Union[Mapping[str, Any], str, bytes, Tuple[Any, …]]]]) –

  • context (Union[Dict[str, Any], Dict[Any, Any]]) –

bind(**new_values)[source]

Return a new logger with new_values added to the existing ones.

Parameters

new_values (Any) –

Return type

BetterBoundLogger

bind_fargs(fargs_map=None, **kwargs)[source]

Helper function for binding function arguments to logger.

These arguments are passed in as a mapping and then jsonified into a string.

Parameters

  • fargs_map (Optional[Mapping[str, Any]]) – A mapping of function arguments. We typically pass in locals() for this argument at the start of a function that contains log messages.

  • kwargs (Any) – Additional function arguments can be passed in as keyword arguments.

Return type

BetterBoundLogger

new(**new_values)[source]

We override this function’s type signature _only_.

Parameters

new_values (Any) –

Return type

BetterBoundLogger

trace(event=None, *args, **kwargs)[source]

Log a new TRACE level message.

Parameters

  • event (Union[str, Dict[str, Any], None]) –

  • args (Any) –

  • kwargs (Any) –

Return type

None

try_unbind(*keys)[source]

We override this function’s type signature _only_.

Parameters

keys (str) –

Return type

BetterBoundLogger

unbind(*keys)[source]

We override this function’s type signature _only_.

Parameters

keys (str) –

Return type

BetterBoundLogger

class Log(file, format='json', level=None)[source]

Bases: object

Log specification for a file or stream.

Parameters

  • file (str) – The file to add log messages to (special values: stderr, stdout).

  • format (Literal[‘json’, ‘color’, ‘nocolor’]) – The logging format (e.g. color or json).

  • level (Optional[Literal[‘TRACE’, ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’]]) – The logging level. If this is not set, a reasonable default level is used depending on whether we are logging to a file or the console (e.g. stderr).

file
format = 'json'
level = None
Logger(name=None, **kwargs)[source]

Returns a structured logger.

This logger is capable of handling positional format arguments as well as keyword arguments and can be bound for context-specific logging.

Parameters

  • name (Optional[str]) – The name of the logger.

  • kwargs (Any) – These parameters will be bound to the returned logger.

Return type

BetterBoundLogger

Returns

A structlog logger with a few extra custom methods (e.g. logger.trace() and logger.bind_fargs()). See structlog’s documentation for more information:

https://www.structlog.org/en/stable/loggers.html

Warning

This logger should only be used for applications, NOT libraries.

get_default_logfile(stem)[source]

Returns full path to logfile using default directory locations.

Parameters

stem (str) – The logfile’s final path component, without its suffix.

Return type

Path

init_logging(*, logs=(Log(file='stderr', format='color', level=None),), verbose=0)[source]

Configure standard logging (for libraries) and structlog (for apps).

This function can be called multiple times but will do nothing if called with the same arguments and structlog is still configured (this latter check is mostly just needed for testing).

Parameters

  • logs (Iterable[Log]) – This list of Log objects determines which logging handlers we configure and enable, what logging level we use for each handler, and what log message format we use for each handler.

  • verbose (int) –

    A non-negative integer. If greater than zero, this option affects the default logging level used when a Log object in logs does not have its level attribute set and causes additional values (e.g. PID, thread name) to be added to each log record. More precisely, the following rules apply to the verbose argument:

    if verbose >= 1…

    • The default log level is set to DEBUG instead of INFO.

    • We show microseconds in each log record’s timestamp instead of milliseconds.

    • The current PID and thread name are added to each log record.

    if verbose >= 2…

    • The line number, function name, module name, and function parameters [if the logger bound them by calling logger.bind_fargs()] are added to each log record.

    if verbose >= 3…

    • The default log level is set to TRACE instead of INFO.

Note

If no ‘stderr’ or ‘stdout’ Log is found in logs, we add a default ‘stderr’ Log object to the list.

Return type

None