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


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:


Log a debug message.


Log an info message


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


Log that something caused an exception but was suppressed.


Log that something has gone horribly wrong.


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.


Decorator that warns that different function should be used instead.


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


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




Tidy up before removing from list of handlers


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


Clear the log messages dictionary