LogHelper#

class caf.toolkit.LogHelper(root_logger, tool_details, *, console=True, log_file=None, warning_capture=True, allowed_packages=None, redirect=True)[source]#

Class for managing Python loggers.

Parameters:

root_logger (str) – Name of the root logger to add handlers to, should be the name of the Python package.
tool_details (ToolDetails) – Details of the tool being ran.
console (bool) – If True (default) output log messages to the console with default settings.
log_file (os.PathLike | None) – If given output log messages to a file with default settings.
warning_capture (bool) – If True (default) capture, and log, Python warnings.
redirect (bool) – If False disable redirecting console handler to tqdm, redirects when entering context manager.
attention:: (..) – tqdm redirection happens upon entering context manager. If using add_console_handler() or capture_warnings(), and tqdm then the redirect should be done manually using tqdm.contrib.logging.logging_redirect_tqdm().
allowed_packages (Sequence[str] | None)

Examples

When using Python’s built-in logging functionality a module level logger constant should be used.

>>> import logging
>>>
>>> LOG = logging.getLogger(__name__)

This module constant should be used for logging any messages, in one of 5 levels.

>>> LOG.debug("Log a debug message")
>>> LOG.info("Log an info message")
>>> LOG.warning("Log a warning message")
>>> LOG.error("Log an error message")
>>> LOG.critical("Log a critical message")

To determine where log messages are written to (console / log file) the log handlers need to be setup, the LogHelper class can do this and will automatically clean-up upon exiting using a with statement.

The example below shows how to setup logging with a log file using the LogHelper class, which will create a log file and write system and tool information to it automatically.

>>> # Temp directory for testing purposes
>>> tmp_path = getfixture("tmp_path")
>>> path = tmp_path / "test.log"
>>> details = ToolDetails("test", "1.2.3")
>>>
>>> with LogHelper(__package__, details, log_file=path):
...     # Add main function for running your tool here
...
...     # Any log messages within the with statement will be written to
...     # the log file, even if running in other functions / modules
...     LOG.info("Log messages using module logger")

The following example shows how to setup logging with a custom console or file output, this also allows log files to be added after initial setup of LogHelper e.g. in another function after the output directory is known.

>>> with LogHelper(__package__, details, console=False) as log_helper:
...     # Console handler with custom message format
...     log_helper.add_console_handler(ch_format="[%(levelname)-8.8s] %(message)s")
...     # File handler with custom message format
...     log_helper.add_file_handler(path, fh_format="[%(levelname)-8.8s] %(message)s")
...
...     # Write initialisation log message with system and tool information
...     log_helper.write_instantiate_message()

Tqdm

tqdm is a third-party package used in caf.toolkit for handling console progress bars, LogHelper will redirect to tqdm during initialisation. If additional handlers are added after initialisation, through add_console_handler() or capture_warnings() then the redirecting will need to be done using tqdm.contrib.logging.logging_redirect_tqdm() after initialisation.

>>> import tqdm.contrib.logging

>>> with LogHelper(__package__, details, console=False) as log_helper:
...     # Console handler with custom message format
...     log_helper.add_console_handler(ch_format="[%(levelname)-8.8s] %(message)s")
...
...     # Setup tqdm redirect
...     with tqdm.contrib.logging.logging_redirect_tqdm(log_helper.loggers):
...         # Write initialisation log message with system and tool information
...         log_helper.write_instantiate_message()

Attributes

loggers

Loggers managed by LogHelper.

Methods

`__init__`(root_logger, tool_details, *[, ...])
`add_console_handler`([ch_format, ...])	Add custom console handler to the logger.
`add_file_handler`(log_file[, fh_format, ...])	Add custom file handler to the logger.
`add_handler`(handler)	Add custom handler to the logger.
`capture_warnings`()	Capture warnings using logging.
`cleanup_handlers`()	Flush and close all handlers before removing from the logger.
`write_instantiate_message`()	Log instatiation message with tool and system information.

Attributes Documentation

loggers#: Loggers managed by LogHelper.