Logging utilities

Utilities for interacting with the python logging module. Mostly, this module provides functions for easily adding command line options to an argparse.ArgumentParser and then setting logging parameters accordingly.

More details and examples for logging are given in the python documentation:

• Introduction: https://docs.python.org/3/howto/logging.html
• Format string options: https://docs.python.org/3/library/logging.html#logrecord-attributes

Command line helpers

add_logging_options(parser[, default_log_file])	Add options for controlling logging to an argument parser.
get_logging_cmd_options(args)	Extract the flags and options specified for logging from the parsed arguments.
get_logging_options_string(args)	Extract the flags and options specified for logging from the parsed arguments and join them as a string.
update_logging(args[, logger, format_str])	Update logger to use the settings in args

Jupyter notebook helpers

get_ipython_logger([logging_level, format_str])

Get a logger for use in jupyter notebooks

Definitions

Utilities for interacting with the python logging module. Mostly, this module provides functions for easily adding command line options to an argparse.ArgumentParser and then setting logging parameters accordingly.

More details and examples for logging are given in the python documentation:

• Introduction: https://docs.python.org/3/howto/logging.html
• Format string options: https://docs.python.org/3/library/logging.html#logrecord-attributes

pyllars.logging_utils.add_logging_options(parser, default_log_file='')

Add options for controlling logging to an argument parser.

In particular, it adds options for logging to a file, stdout and stderr. In addition, it adds options for controlling the logging level of each of the loggers, and a general option for controlling all of the loggers.

Parameters:

• parser (argparse.ArgumentParser) – An argument parser
• default_log_file (str) – The default for the –log-file flag

Returns:

Return type:

None, but the parser has the additional options added

pyllars.logging_utils.get_ipython_logger(logging_level='DEBUG', format_str='%(levelname)-8s : %(message)s')

Get a logger for use in jupyter notebooks

This function is useful because the default logger in notebooks has a number of handlers by default. This function removes those, so the logger behaves as expected.

Parameters:

• logging_level (str) – The logging level for the logger. This can be updated later.
• format_str (str) – The logging format string. Please see the python logging documentation for examples and more description.

Returns:

logger – A logger suitable for use in a notebook

Return type:

logging.Logger

pyllars.logging_utils.get_logging_cmd_options(args)

Extract the flags and options specified for logging from the parsed arguments.

Presumably, these were added with add_logging_options. Compared to get_logging_options_string, this function returns the arguments as an array. Thus, they are suitable for use with subprocess.run and similar functions.

Parameters:args (argparse.Namespace) – The parsed arguments Returns:logging_options – The list of logging options and their values. Return type:typing.List[str]

pyllars.logging_utils.get_logging_options_string(args)

Extract the flags and options specified for logging from the parsed arguments and join them as a string.

Presumably, these were added with add_logging_options. Compared to get_logging_cmd_options, this function returns the arguments as a single long string. Thus, they are suitable for use when building single strings to pass to the command line (such as with subprocess.run when shell is True).

Parameters:args (argparse.Namespace) – The parsed arguments Returns:logging_options_str – A string containing all logging flags and options Return type:str

pyllars.logging_utils.update_logging(args, logger=None, format_str='%(levelname)-8s %(name)-8s %(asctime)s : %(message)s')

Update logger to use the settings in args

Presumably, the logging options were added with add_logging_options.

Parameters:

• args (argparse.Namespace) – A namespace with the arguments added by add_logging_options
• logger (typing.Optional[logging.Logger]) – The logger which will be updated. If None is given, then the default logger will be updated.
• format_str (str) – The logging format string. Please see the python logging documentation for examples and more description.

Returns:

the specified logging options

Return type:

None, but the default (or given) logger is updated to take into account