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, …)	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

Other helpers¶

`get_ipython_logger`([logging_level, format_str])	Get a logger for use in jupyter notebooks
`set_logging_values`(**kwargs)	Set the logging options for the default logger as given

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: argparse.ArgumentParser, default_log_file: str = '', default_logging_level: str = 'WARNING', default_specific_logging_level: str = 'NOTSET') → None[source]¶

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 default_logging_level (str) – The default for the –logging-level flag default_specific_logging_level (str) – The default for the –{file,stdout,stderr}-logging-level flags
Returns:	None – The parser has the additional options added
Return type:	None

pyllars.logging_utils.add_logging_values_to_args(args: argparse.Namespace, log_file: str = '', log_stdout: bool = False, no_log_stderr: bool = False, logging_level: str = 'WARNING', file_logging_level: str = 'NOTSET', stdout_logging_level: str = 'NOTSET', stderr_logging_level: str = 'NOTSET') → None[source]¶

Add the options from add_logging_options to args

This is intended for use in notebooks or other settings where the logging option functionality is required, but a command line interface is not used.

Parameters:	args (argparse.Namespace) – The namespace to which the options will be added log_file (str) – The path to a log file. If this is the empty string, then a log file will not be used. log_stdout (bool) – Whether to log to stdout no_log_stderr (bool) – Whether to _not_ log to stderr. So, if this is True, then logging statements _will_ be written to stderr. (The negative is used because that is more natural for the command line arguments.) logging_level (str) – The logging level for all loggers {file,stdout,stderr}_logging_level (str) – The logging level for the specific loggers. This overrides logging_level for the respective logger when given.
Returns:	None – The respective options will be set on the namespace
Return type:	None

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

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: argparse.Namespace) → str[source]¶

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: argparse.Namespace) → str[source]¶

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.set_logging_values(**kwargs) → None[source]¶

Set the logging options for the default logger as given

This is intended for use in tests or other cases where a CLI is not easily available.

Parameters:	kwargs (key=value pairs) – These are passed unaltered to add_logging_values_to_args. Please see that documentation for details on valid options and their effect.
Returns:	None – The respective options will be set for the default logger
Return type:	None

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

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