10.9.2. Logging Utilities¶

PyTan logging module.

pytan3.utils.logs.LOG = <Logger pytan3 (DEBUG)>¶

logging.Logger – Package logger.

pytan3.utils.logs.LOG_FILE = 'pytan3.log'¶

str – Log filename for add_file() and remove_file().

pytan3.utils.logs.LOG_CON_FMT = '%(levelname)-8s [%(name)s:%(funcName)s()] %(message)s'¶

str – Logging format for add_stderr() and add_stdout().

pytan3.utils.logs.LOG_PATH_FMT = '[%(asctime)s] PID:%(process)s %(levelname)-8s [%(name)s:%(funcName)s()] %(message)s'¶

str – Logging format for add_file().

pytan3.utils.logs.LVL_DICT = {'CRITICAL': 50, 'DEBUG': 10, 'ERROR': 40, 'FATAL': 50, 'INFO': 20, 'NOTSET': 0, 'WARN': 30, 'WARNING': 30}¶

dict – Logging level names to ints, python version dependent.

pytan3.utils.logs.LVL_STR = 'CRITICAL, FATAL, ERROR, WARN, WARNING, INFO, DEBUG, NOTSET, OFF'¶

str – CSV str of logging level names.

pytan3.utils.logs.is_enabled(lvl='debug', obj=<Logger pytan3 (DEBUG)>)[source]¶

Determine if a logger or handler is enabled for a log level.

Parameters:	lvl (str or int, optional) – Level to check if obj is enabled for. Defaults to: “debug”. obj (logging.Logger or logging.Handler, optional) – Object to check if enabled for lvl. Defaults to: LOG.
Returns:	bool

pytan3.utils.logs.is_disabled(obj=<Logger pytan3 (DEBUG)>)[source]¶

Determine if a logger or handler is disabled.

Parameters:	obj (logging.Logger or logging.Handler, optional) – Object to check if disabled. Defaults to: LOG.

Notes

Will traverse up the logger tree to see if any parents are disabled.

Returns:	bool

pytan3.utils.logs.enable_capture_exc()[source]¶

Enable the exception hook to capture exceptions to the logging system.

pytan3.utils.logs.disable_capture_exc()[source]¶

Disable the exception hook to capture exceptions to the logging system.

pytan3.utils.logs.enable_capture_warn()[source]¶

Enable the warning hook to capture warnings to the logging system.

pytan3.utils.logs.disable_capture_warn()[source]¶

Disable the warning hook to capture warnings to the logging system.

pytan3.utils.logs.enable_format_warning()[source]¶

Replace warnings.formatwarning() with customformatwarning().

pytan3.utils.logs.disable_format_warning()[source]¶

Restore warnings.formatwarning() to the default.

pytan3.utils.logs.use_gmt()[source]¶

Set the logging system to use GMT for time strings.

pytan3.utils.logs.use_localtime()[source]¶

Set the logging system to use local time for time strings.

pytan3.utils.logs.exception_hook(type, value, tb)[source]¶

Exception hook to send exceptions to the logging system.

Notes

If the package logger has no logging output at “error” level, the default excepthook will be used to print the exception to STDERR.

pytan3.utils.logs.warning_hook(message, category, filename, lineno, file=None, line=None)[source]¶

Warning hook to send warnings to the logging system.

Notes

If the package logger has no logging output at “warning” level, the default warning will be used to print the warning to STDERR.

pytan3.utils.logs.customformatwarning(message, category, filename, lineno, file=None, line=None)[source]¶

Return a custom warning format.

pytan3.utils.logs.set_level(lvl='info', obj=<Logger pytan3 (DEBUG)>)[source]¶

Set a logger or handler to a log level.

Parameters:	lvl (str or int, optional) – Level to set obj to. Defaults to: “info”. obj (logging.Logger or logging.Handler, optional) – Object to set lvl on. Defaults to: LOG.

Notes

If lvl is “OFF” the disabled attr on obj will be set to True.

Returns:	bool

pytan3.utils.logs.get_obj_log(obj, lvl='debug')[source]¶

Get a logger object for an object.

Parameters:	obj (object) – Object to get a logger for using the objects class module and name. lvl (str or int, optional) – Level to set logger created for obj to initially. Defaults to: “debug”.
Returns:	logging.Logger

pytan3.utils.logs.get_log(name, lvl='debug')[source]¶

Get a logger object.

Parameters:	name (str) – Path of logger to get/create. lvl (str or int, optional) – Level to set logger created using name initially. Defaults to: “debug”.
Returns:	logging.Logger

pytan3.utils.logs.level_name(lvl)[source]¶

Get a logging level in str format.

Parameters:	lvl (str or int) – Level to get str format of.
Raises:	pytan3.utils.exceptions.ModuleError – If int is not in values of LVL_DICT or if str is not in keys of LVL_DICT.
Returns:	str

pytan3.utils.logs.level_int(lvl)[source]¶

Get a logging level in int format.

Parameters:	lvl (str or int) – Level to get int format of.
Raises:	pytan3.utils.exceptions.ModuleError – If int is not in values of LVL_DICT or if str is not in keys of LVL_DICT.
Returns:	int

pytan3.utils.logs.log_str(obj)[source]¶

Get a str format of a logger object showing level and attached handlers.

Parameters:	obj (logging.Logger) – Logger object to get str format of.
Returns:	str

pytan3.utils.logs.handler_str(obj)[source]¶

Get a str format of a handler object showing level.

Parameters:	obj (logging.Handler) – Handler object to get str format of.
Returns:	str

pytan3.utils.logs.add_stdout(lvl='info', fmt='%(levelname)-8s [%(name)s:%(funcName)s()] %(message)s', obj=<Logger pytan3 (DEBUG)>)[source]¶

Add a STDOUT handler to a logger object.

Parameters:	lvl (str or int, optional) – Level to set on handler. Defaults to: “info”. fmt (str, optional) – Formatting string to use for logging. Defaults to: LOG_CON_FMT. obj (logging.Logger, optional) – Logger object to add handler to. Defaults to: LOG.

Notes

Will remove handler from obj if exists before adding.

Returns:	logging.StreamHandler

pytan3.utils.logs.add_stderr(lvl='info', fmt='%(levelname)-8s [%(name)s:%(funcName)s()] %(message)s', obj=<Logger pytan3 (DEBUG)>)[source]¶

Add a STDERR handler to a logger object.

Parameters:	lvl (str or int, optional) – Level to set on handler. Defaults to: “info”. fmt (str, optional) – Formatting string to use for logging. Defaults to: LOG_CON_FMT. obj (logging.Logger, optional) – Logger object to add handler to. Defaults to: LOG.

Notes

Will remove handler from obj if exists before adding.

Returns:	logging.StreamHandler

pytan3.utils.logs.add_file(lvl='debug', path=None, path_sub='logs', path_file='pytan3.log', max_mb=10, max_num=5, fmt='[%(asctime)s] PID:%(process)s %(levelname)-8s [%(name)s:%(funcName)s()] %(message)s', obj=<Logger pytan3 (DEBUG)>)[source]¶

Add a rotating log file handler to a logger object.

Parameters:

lvl (str or int, optional) – Level to set on handler. Defaults to: “debug”. path (str or pathlib.Path, optional) – Storage directory to use. If empty, resolve path via pytan3.utils.tools.get_storage_dir(). Defaults to: None. path_sub (str, optional) – Sub directory under path that should contain path_file. Defaults to: “logs” path_file (str, optional) – Filename to write logs to under path / path_sub. Defaults to: LOG_FILE max_mb (int, optional) – Rotate log file when it reaches this many MB. Defaults to: 10. max_num (int, optional) – Only keep up to this number of rotated logs. Defaults to: 5. fmt (str, optional) – Formatting string to use for logging. Defaults to: LOG_PATH_FMT. obj (logging.Logger, optional) – Logger object to add handler to. Defaults to: LOG.

Notes

Will remove handler from obj if exists before adding.

Returns:	logging.handlers.RotatingFileHandler

pytan3.utils.logs.remove_stdout(obj=<Logger pytan3 (DEBUG)>)[source]¶

Remove a STDOUT handler from a logger object.

Parameters:	obj (logging.Logger, optional) – Logger object to remove handler from. Defaults to: LOG.
Returns:	logging.Handler

pytan3.utils.logs.remove_stderr(obj=<Logger pytan3 (DEBUG)>)[source]¶

Remove a STDERR handler from a logger object.

Parameters:	obj (logging.Logger, optional) – Logger object to remove handler from. Defaults to: LOG.
Returns:	logging.Handler

pytan3.utils.logs.remove_file(path=None, path_sub='logs', path_file='pytan3.log', obj=<Logger pytan3 (DEBUG)>)[source]¶

Remove a STDERR handler from a logger object.

Parameters:

path (str or pathlib.Path, optional) – Storage directory to use. If empty, resolve path via pytan3.utils.tools.get_storage_dir(). Defaults to: None. path_sub (str, optional) – Sub directory under path that should contain path_file. Defaults to: “logs” path_file (str, optional) – Filename to write logs to under path / path_sub. Defaults to: LOG_FILE obj (logging.Logger, optional) – Logger object to remove handler from. Defaults to: LOG.

Returns:

logging.handlers.RotatingFileHandler

pytan3.utils.logs.add_null(obj=<Logger pytan3 (DEBUG)>)[source]¶

Add a Null handler to a logger object.

Parameters:	obj (logging.Logger, optional) – Logger object to add handler to. Defaults to: LOG.
Returns:	logging.NullHandler

pytan3.utils.logs.remove_null(obj=<Logger pytan3 (DEBUG)>)[source]¶

Remove a Null handler from a logger object.

Parameters:	obj (logging.Logger, optional) – Logger object to remove handler from. Defaults to: LOG.
Returns:	logging.NullHandler

pytan3.utils.logs.remove_handler(handler, obj=<Logger pytan3 (DEBUG)>)[source]¶

Remove a handler from a logger.

Parameters:	handler (logging.Handler) – Handler object to add to logger object. obj (logging.Logger, optional) – Logger object to remove handler from. Defaults to: LOG.
Returns:	logging.Handler

pytan3.utils.logs.find_handler_by_name(name, obj=<Logger pytan3 (DEBUG)>)[source]¶

Find handler object that is attached to a logger.

Parameters:	name (str) – Name of handler object to find. obj (logging.Logger, optional) – Logger object to find handler in. Defaults to: LOG.
Returns:	logging.Handler or None

pytan3.utils.logs.get_output_handlers(lvl=None, obj=<Logger pytan3 (DEBUG)>)[source]¶

Find handlers attached to a logger that show output at a given level.

Parameters:	lvl (str or int, optional) – Level to check if handler outputs at. Defaults to: None. obj (logging.Logger, optional) – Logger object to find output handlers in. Defaults to: LOG.

Notes

If lvl is None logging levels of handlers will not be checked and the return will be handlers that are not logging.NullHandler.

Returns:	list of logging.Handler

pytan3.utils.logs.will_print_at(lvl='debug', obj=<Logger pytan3 (DEBUG)>)[source]¶

Check if a logger will show output at a given level.

Parameters:	lvl (str or int, optional) – Level to check if obj has any handlers that will output logs at. Defaults to: “debug”. obj (logging.Logger, optional) – Logger to check if disabled and for handlers that output at lvl. Defaults to: LOG.
Returns:	bool