mmf.utils.logging

LoggerTraceback	Used for printing tracebacks in log messages.
MMFLogger(name)	Custom logger that also provides traceback information.
NullHandler([level])	Initializes the instance - basically setting the formatter to None
MMFTracebackType(frame, lineno)	We need to put the frame in a TracebackType object, but can’t
MMFFormatter([fmt, datefmt, stack, stack_limit])	logging.Formatter subclass that adds a stack trace of depth
setLoggerClass(klass)	Sets the default logger class and also monekypatches the root logger.
start_logging([tmp_dir, format, ...])	Start a logging handler and setup log files.
log_to_stream([stream])	Start logging to stream and return handler.
log_to_file(filename[, mode, level, stack, ...])	Start logging to the specified file and return handler.
captureWarnings(capture)	If capture is true, redirect all warnings to the logging package.

Inheritance diagram for mmf.utils.logging:

Logging Facilities

This module provides some simple default logging facilities including a rotating set of log files.

Usage

Components of the mmf package should always use the logging facilities to emit messages to the user. The name of the logger should be as local as possible to enable filtering (either the complete class name, or the module name for example). The levels should be interpreted as follows:

debug

Use for debugging information that should not be displayed during normal runs.

info

Use for information that should be logged to file, but not necessarily displayed on the console.

warning

Use for warnings that do not need full stack trace and that should be repeated.

error

Use for errors that need to be taken seriously.

critical

Use for mission critical problems that will terminate the program.

Note: also consider using real warnings by calling the warnings.warn() function in the warnings module. This has the following advantages:

1. The warnings.warn() can generate a stack trace to show exactly where the warning was issued. It also accepts a stacklevel=2 argument to allow you to report the trace in the calling function (or higher).
2. The warnings can be set to only display once per run (or once in each module etc.). (This is the default behaviour.)
3. Warnings can be turned into exceptions by using warnings.simplefilter('error', UserWarnings)().

Use warnings.warn() for warnings about coding problems (like a module not be able to be imported, or a function being deprecated) that should only be issued once, or for warnings that need to have a traceback.

class mmf.utils.logging.LoggerTraceback

Bases: exceptions.Exception

Used for printing tracebacks in log messages.

__init__()

x.__init__(...) initializes x; see help(type(x)) for signature

class mmf.utils.logging.MMFLogger(name)

Bases: logging.Logger

Custom logger that also provides traceback information.

Differs from the standard logger in the following ways:

1. Packs kwargs into extra argument for processing. (Uses stacklevel for example and warn() accepts category so that exceptions can be raised later.)
2. Adds a unique id to each record.
3. Adds a stack frame to each record if with_stack is True.

Note

The stacklevel argument is applied after the trace is backed out of the logging modules. This means that the value you would have to pass to warnings.warn() might be differ (in my experience, I need to add one more level when using warnings.)

Attributes

debug_level

int(x[, base]) -> integer

Methods

addFilter(filter)	Add the specified filter to this handler.
addHandler(hdlr)	Add the specified handler to this logger.
callHandlers(record)	Pass a record to all relevant handlers.
critical(msg, *args, **kwargs)	Log ‘msg % args’ with severity ‘CRITICAL’.
debug(msg, *args, **kwargs)	Log ‘msg % args’ with severity ‘DEBUG’.
error(msg, *args, **kwargs)	Log ‘msg % args’ with severity ‘ERROR’.
exception(msg, *args)	Convenience method for logging an ERROR with exception information.
fatal(msg, *args, **kwargs)	Log ‘msg % args’ with severity ‘CRITICAL’.
filter(record)	Determine if a record is loggable by consulting all the filters.
findCaller()	Find the stack frame of the caller so that we can note the source
getChild(suffix)	Get a logger which is a descendant to this one.
getEffectiveLevel()	Get the effective level for this logger.
handle(record)	Call the handlers for the specified record.
info(msg, *args, **kwargs)	Log ‘msg % args’ with severity ‘INFO’.
isEnabledFor(level)	Is this logger enabled for level ‘level’?
log(level, msg, *args, **kwargs)	Log ‘msg % args’ with the integer severity ‘level’.
makeRecord(name, level, fn, lno, msg, args, ...)	A factory method which can be overridden in subclasses to create
removeFilter(filter)	Remove the specified filter from this handler.
removeHandler(hdlr)	Remove the specified handler from this logger.
setLevel(level)	Set the logging level of this logger.
warn(msg, *arg, **kw)
warning(msg, *args, **kwargs)	Log ‘msg % args’ with severity ‘WARNING’.

__init__(name)

debug_level = 40

makeRecord(name, level, fn, lno, msg, args, exc_info, func=None, extra=None)

A factory method which can be overridden in subclasses to create specialized LogRecords. Here we also add a traceback.

warn(msg, *arg, **kw)

class mmf.utils.logging.NullHandler(level=0)

Bases: logging.Handler

Initializes the instance - basically setting the formatter to None and the filter list to empty.

Methods

acquire()	Acquire the I/O thread lock.
addFilter(filter)	Add the specified filter to this handler.
close()	Tidy up any resources used by the handler.
createLock()	Acquire a thread lock for serializing access to the underlying I/O.
emit(record)
filter(record)	Determine if a record is loggable by consulting all the filters.
flush()	Ensure all logging output has been flushed.
format(record)	Format the specified record.
get_name()
handle(record)	Conditionally emit the specified logging record.
handleError(record)	Handle errors which occur during an emit() call.
release()	Release the I/O thread lock.
removeFilter(filter)	Remove the specified filter from this handler.
setFormatter(fmt)	Set the formatter for this handler.
setLevel(level)	Set the logging level of this handler.
set_name(name)

__init__(level=0)

Initializes the instance - basically setting the formatter to None and the filter list to empty.

emit(record)

class mmf.utils.logging.MMFTracebackType(frame, lineno)

We need to put the frame in a TracebackType object, but can’t create one so we fake one.

class mmf.utils.logging.MMFFormatter(fmt=None, datefmt=None, stack=False, stack_limit=None, **kw)

Bases: logging.Formatter

logging.Formatter subclass that adds a stack trace of depth stack_limit: to each call if stack is True.

Adds ‘%(id)i’ as an option for the formatting message which is a unique message id. (Suggest using ‘%(id)06i’ or similar so they can be sorted).

Methods

converter(...)	Convert seconds since the Epoch to a time tuple expressing local time.
format(record)	Format the specified record as text.
formatException(ei)	Format and return the specified exception information as a string.
formatStack(frame)	Format the stack.
formatTime(record[, datefmt])	Return the creation time of the specified LogRecord as formatted text.
usesTime()	Check if the format uses the creation time of the record.

__init__(fmt=None, datefmt=None, stack=False, stack_limit=None, **kw)

format(record)

Format the specified record as text.

The record’s attribute dictionary is used as the operand to a string formatting operation which yields the returned string. Before formatting the dictionary, a couple of preparatory steps are carried out. The message attribute of the record is computed using LogRecord.getMessage(). If the formatting string contains “%(asctime)”, formatTime() is called to format the event time. If there is exception information, it is formatted using formatException() and appended to the message.

formatStack(frame)

Format the stack.

mmf.utils.logging.setLoggerClass(klass)

Sets the default logger class and also monekypatches the root logger.

mmf.utils.logging.start_logging(tmp_dir='/tmp', format='%(id)06i:%(levelname)s:%(name)s:%(message)s', interactive=None, log_warnings=True, level=20, files=None, debug_level=None)

Start a logging handler and setup log files. This is called when the mmf module is imported if the logging_options configuration values is True. It uses logging.basicConfig() to set up a default stream handler so that if a handler has already been defined, then it will not be changed. Depending on options, file handlers may also be setup.

Parameters :

files : list of str or (str, kwargs)

Names of files to use for logging. The dict kwargs can have any arguments supported by log_to_file().

tmp_dir : str

If specified, then this directory will be used for a rotating set of logfiles in tmp_dir/pymmf with names <pid>_<unique>.log. (Not yet supported.)

interactive : bool, ‘reset’

If True, then the log messages will also be directed to sys.stdout, even if filename is specified. This will use logging.basicConfig() unless passed the string ‘reset’ in which case the root logger will be completely reset (to be used if a root logger has already been setup because in this case logging.basicConfig() will do nothing.)

log_warnings : bool, None

If True, then capture warnings from the warnings module and redirect these to the logger. If None, then leave setting unchanged.

mmf.utils.logging.log_to_stream(stream=None)

Start logging to stream and return handler.

mmf.utils.logging.log_to_file(filename, mode='w', level=10, stack=False, stack_limit=None, **kwargs)

Start logging to the specified file and return handler.

mmf.utils.logging.captureWarnings(capture)

If capture is true, redirect all warnings to the logging package. If capture is False, ensure that warnings are not redirected to logging but to their original destinations.