cs-logutils 20190220

Logging convenience routines.

Logging convenience routines.

The logging package is very useful, but a little painful to use. This package provides low impact logging setup and some extremely useful if unconventional context hooks for logging.

The default logging verbosity output format has different defaults based on whether an output log file is a tty and whether the environment variable $DEBUG is set, and to what.

On terminals warnings and errors get ANSI colouring.

A mode is available that uses cs.upd.

Some examples:

Program initialisation::

from cs.logutils import setup_logging

def main(argv):
  cmd = os.path.basename(argv.pop(0))
  setup_logging(cmd)

Basic logging from anywhere::

from cs.logutils import info, warning, error
[...]
def some_function(...):
    [...]
    error("nastiness found! bad value=%r", bad_value)

Function add_logfile(filename, logger=None, mode='a', encoding=None, delay=False, format=None, no_prefix=False)

Add a FileHandler logging to the specified filename; return the chosen logger and the new handler.

Parameters:

• logger: if supplied and not None, add the FileHandler to that Logger, otherwise to the root Logger. If logger is a string, call logging.getLogger(logger) to obtain the logger.
• mode, encoding and delay: passed to the logging.FileHandler initialiser.
• format: used to override the handler's default format.
• no_prefix: if true, do not put the Pfx context onto the front of the message.

Function critical(msg, *args, **kwargs)

Emit a log at logging.CRITICAL level with the current Pfx prefix.

Function D(msg, *args)

Print formatted debug string straight to sys.stderr if D_mode is true, bypassing the logging modules entirely. A quick'n'dirty debug tool.

Function debug(msg, *args, **kwargs)

Emit a log at logging.DEBUG level with the current Pfx prefix.

Function error(msg, *args, **kwargs)

Emit a log at logging.ERROR level with the current Pfx prefix.

Function exception(msg, *args)

Emit an exception log with the current Pfx prefix.

Function ftrace(func)

Decorator to trace a function if module.DEBUG is true.

Function ifdebug()

Test the logging_level against logging.DEBUG.

Function infer_logging_level(env_debug=None, environ=None, verbose=None)

Infer a logging level from the env_debug, which by default comes from the environment variable $DEBUG.

Usually default to logging.WARNING, but if sys.stderr is a terminal, default to logging.INFO.

Parse the environment variable $DEBUG as a comma separated list of flags.

Examine the in sequence flags to affect the logging level:

• numeric < 1: logging.WARNING
• numeric >= 1 and < 2: logging.INFO
• numeric >= 2: logging.DEBUG
• "DEBUG": logging.DEBUG
• "INFO": logging.INFO
• "WARNING": logging.WARNING
• "ERROR": logging.ERROR

Return an object with the following attributes:

• .level: A logging level.
• .flags: All the words from $DEBUG as separated by commas and uppercased.
• .module_names: Module names to be debugged.
• .function_names: Functions to be traced in the for "module_name.func_name()".

Function info(msg, *args, **kwargs)

Emit a log at logging.INFO level with the current Pfx prefix.

Function log(level, msg, *args, **kwargs)

Emit a log at the specified level with the current Pfx prefix.

Function logException(exc_type, exc_value, exc_tb)

Replacement for sys.excepthook that reports via the cs.logutils logging wrappers.

Class LogTime

LogTime is a content manager that logs the elapsed time of the enclosed code. After the run, the field .elapsed contains the elapsed time in seconds.

Function logTo(filename, logger=None, mode='a', encoding=None, delay=False, format=None, no_prefix=False)

Add a FileHandler logging to the specified filename; return the chosen logger and the new handler.

Parameters:

• logger: if supplied and not None, add the FileHandler to that Logger, otherwise to the root Logger. If logger is a string, call logging.getLogger(logger) to obtain the logger.
• mode, encoding and delay: passed to the logging.FileHandler initialiser.
• format: used to override the handler's default format.
• no_prefix: if true, do not put the Pfx context onto the front of the message.

Class NullHandler

MRO: logging.Handler, logging.Filterer
A Handler which discards its requests.

Function OBSOLETE(func)

Decorator for obsolete functions.

Use:

@OBSOLETE
def f(...):

This emits a warning log message before calling the decorated function.

Class PfxFormatter

MRO: logging.Formatter
A Formatter subclass that has access to the program's cmd and Pfx state.

Function setup_logging(cmd_name=None, main_log=None, format=None, level=None, flags=None, upd_mode=None, ansi_mode=None, trace_mode=None, module_names=None, function_names=None, verbose=None)

Arrange basic logging setup for conventional UNIX command line error messaging; return an object with informative attributes.

Parameters:

• cmd_name: program name, default from basename(sys.argv[0]). Side-effect: sets cs.pfx.cmd to this value.
• main_log: default logging system. If None, the main log will go to sys.stderr; if main_log is a string, is it used as a filename to open in append mode; otherwise main_log should be a stream suitable for use with logging.StreamHandler(). The resulting log handler is added to the logging root logger.
• format: the message format for main_log. If None, use DEFAULT_PFX_FORMAT_TTY when main_log is a tty or FIFO, otherwise DEFAULT_PFX_FORMAT.
• level: main_log logging level. If None, infer a level from the environment using infer_logging_level().
• flags: a string containing debugging flags separated by commas. If None, infer the flags from the environment using infer_logging_level(). The following flags have meaning: D: set cs.logutils.D_mode to True; TDUMP: attach a signal handler to SIGHUP to do a thread stack dump; TRACE: enable various noisy tracing facilities; UPD, NOUPD: set the default for upd_mode to True or False respectively.
• upd_mode: a Boolean to activate cs.upd as the main_log method; if None, set it to True if flags contains 'UPD', otherwise to False if flags contains 'NOUPD', otherwise set it to False (was from main_log.isatty()). A true value causes the root logger to use cs.upd for logging.
• ansi_mode: if None, set it from main_log.isatty(). A true value causes the root logger to colour certain logging levels using ANSI terminal sequences (currently only if cs.upd is used).
• trace_mode: if None, set it according to the presence of 'TRACE' in flags. Otherwise if trace_mode is true, set the global trace_level to logging_level; otherwise it defaults to logging.DEBUG.
• verbose: if None, then if stderr is a tty then the log level is INFO otherwise WARNING. Otherwise, if verbose is true then the log level is INFO otherwise WARNING.

Function status(msg, *args, **kwargs)

Write a message to the terminal's status line.

Parameters:

• msg: message string
• args: if not empty, the message is %-formatted with args
• file: optional keyword argument specifying the output file. Default: sys.stderr.

Hack: if there is no status line use the xterm title bar sequence :-(

Function trace(msg, *args, **kwargs)

Emit a log message at trace_level with the current Pfx prefix.

Function upd(msg, *args)

If we're using an UpdHandler, update the status line otherwise write an info message.

Class UpdHandler

MRO: logging.StreamHandler, logging.Handler, logging.Filterer
A StreamHandler subclass whose .emit method uses a cs.upd.Upd for transcription.

Function warning(msg, *args, **kwargs)

Emit a log at logging.WARNING level with the current Pfx prefix.

Function with_log(filename, **kw)

Context manager to add a Logger to the output logs temporarily.