Logging and Reporting

The primary internal logging is performed with a logger named serpentTools, that can be obtained using:

>>> import logging
>>> logging.getLogger("serpentTools")

If you want to see the messages produced by this logger, you have a few options. First, the Python logging system must be configured. This can be done simply with:

>>> import logging
>>> logging.basicConfig(format="%(levelname)-s: %(message)-s")
# Display a basic warning
>>> logging.warning("This is a warning")
WARNING: This is a warning

To show the internal messages, one can modify the verbosity through the Settings interface with:

>>> serpentTools.settings.rc["verbosity"] = "debug"

where "debug" can be one of "debug", "info", "warning", "error" or "critical".

Alternatively, the level can be adjusting using the python logging module:

>>> logging.getLogger("serpentTools").setLevel(logging.DEBUG)

Developer Reference

Note

The use of built-in python warning support through the warnings module should be preferred. These functions will be phased out in future versions

This chapter describes the various functions used to convey progress updates or issues to the user. Functions in this module should be used over a general print statement, as this module can be be extended to log messages to a file in the future. In order of increasing severity:

debug

Log a debug message.

info

Log an info message

warning

Log a warning that something could go wrong or should be avoided.

error

Log that something caused an exception but was suppressed.

critical

Log that something has gone horribly wrong.

Decorators

Two decorators are provided in the messages module that are used to indicate functions or methods who’s behavior will be changing or removed in the future.

deprecated

Decorator that warns that different function should be used instead.

willChange

Decorator that warns that some functionality may change.

Custom Handlers

class serpentTools.messages.DictHandler(level=0)

Bases: logging.Handler

Handler that stores log messages in a dictionary

logMessages

Dictionary of lists where each key is a log level such as 'DEBUG' or 'WARNING'. The list associated with each key contains all messages called under that logging level

Type

dict

close()

Tidy up before removing from list of handlers

emit(record)

Store the message in the log messages by level.

Does no formatting to the record, simply stores the message in logMessages dictionary according to the records levelname

Anticipates a logging.LogRecord object

flush()

Clear the log messages dictionary