fab.logtools#

Logging tools for the fab framework.

Functions

make_logger(feature[, offset])

Create a hierarchical logger.

make_loggers()

Create a set of named loggers.

setup_file_logging(logfile[, name, create])

Direct log messages to a named file.

setup_logging(build_level, system_level[, ...])

Setup the fab logging framework.

Classes

FabLogFilter(build_level, system_level[, quiet])

Class to filter log messages from the console stream.
fab.logtools.make_logger(feature, offset=1)#

Create a hierarchical logger.

The name of the logger is based on the module name of the caller and the calling function, but with the addition of the feature name at the second level of the hierarchy.

If the logger is created in a module, no function name is appended. If the logger is created from the __init__ method of a class, the name of the class is used in place of a function.

Parameters:

  • feature (str) – the name of the logging feature. Typically either build or system.

  • offset (int) – the number of frames to skip. Defaults to 1. (default: 1)

Returns:

a logging.Logger instance.

fab.logtools.make_loggers()#

Create a set of named loggers.

A simple convenience function that creates a pair of named loggers with build and system at the second level of the logging hierarchy. This function is ignored when inspecting the calling tree to determine the name to use.

Returns:

tuple containing two logger instances, the first associated with the build hierarchy and the second with the system hierarchy.

class fab.logtools.FabLogFilter(build_level, system_level, quiet=False)#

Class to filter log messages from the console stream.

This filters out specific types of log message based on level criteria and the boolean quiet flag. This makes it possible to write all log events to a file whilst controlling the amount of output seen by the user.

Initialize a filter.

Initialize with the name of the logger which, together with its children, will have its events allowed through the filter. If no name is specified, allow every event.

filter(record)#

Decide whether to filter a specific log message.

fab.logtools.setup_logging(build_level, system_level, quiet=False, iostream=<_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)#

Setup the fab logging framework.

Set output levels for build log messages and system log messages.

Build messages are purely intended to be used to output information about the compile tasks. System messages should help to debug the fab library itself.

Parameters:

  • build_level (Optional[int]) – verbosity of output from the build logger hierarchy. Setting to 0 or None implies a low level of output.

  • system_level (Optional[int]) – verbosity of output from the system logger hierarchy. Setting to 0 or None implies a low level of output.

  • quiet – do not log anything lower than an error to the user output stream. (default: False)

  • iostream – output stream used to log messages. Defaults to sys.stderr if not specified. This is particularly useful when testing. (default: <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>)

fab.logtools.setup_file_logging(logfile, name='root', create=True)#

Direct log messages to a named file.

Parameters:

  • logfile (Path) – path to the output log

  • name – name of the logger hierarchy being added (default: 'root')

  • create – create the parent directory. Defaults to True. (default: True)