verboselogs documentation

Welcome to the documentation of verboselogs version 1.7!

The first part of the documentation is the readme which gives you a general overview of the verboselogs package:

verboselogs: Verbose logging level for Python’s logging module

The verboselogs package extends Python’s logging module to add the log levels NOTICE, SPAM, SUCCESS and VERBOSE:

• The NOTICE level sits between the predefined WARNING and INFO levels.
• The SPAM level sits between the predefined DEBUG and NOTSET levels.
• The SUCCESS level sits between the predefined WARNING and ERROR levels.
• The VERBOSE level sits between the predefined INFO and DEBUG levels.

The code to do this is simple and short, but I still don’t want to copy/paste it to every project I’m working on, hence this package. It’s currently tested on Python 2.6, 2.7, 3.4, 3.5, 3.6 and PyPy.

Installation

The verboselogs package is available on PyPI which means installation should be as simple as:

$ pip install verboselogs

There’s actually a multitude of ways to install Python packages (e.g. the per user site-packages directory, virtual environments or just installing system wide) and I have no intention of getting into that discussion here, so if this intimidates you then read up on your options before returning to these instructions ;-).

Usage

It’s very simple to start using the verboselogs package:

>>> import logging, verboselogs
>>> logger = verboselogs.VerboseLogger('verbose-demo')
>>> logger.addHandler(logging.StreamHandler())
>>> logger.setLevel(logging.VERBOSE)
>>> logger.verbose("Can we have verbose logging? %s", "Yes we can!")

Here’s a skeleton of a very simple Python program with a command line interface and configurable logging:

"""
Usage: demo.py [OPTIONS]

This is the usage message of demo.py. Usually
this text explains how to use the program.

Supported options:
  -v, --verbose  make more noise
  -h, --help     show this message and exit
"""

import getopt
import logging
import sys
import verboselogs

logger = verboselogs.VerboseLogger('demo')
logger.addHandler(logging.StreamHandler())
logger.setLevel(logging.INFO)

# Command line option defaults.
verbosity = 0

# Parse command line options.
opts, args = getopt.getopt(sys.argv[1:], 'vqh', ['verbose', 'quiet', 'help'])

# Map command line options to variables.
for option, argument in opts:
    if option in ('-v', '--verbose'):
        verbosity += 1
    elif option in ('-q', '--quiet'):
        verbosity -= 1
    elif option in ('-h', '--help'):
        print __doc__.strip()
        sys.exit(0)
    else:
        assert False, "Unhandled option!"

# Configure logger for requested verbosity.
if verbosity >= 4:
    logger.setLevel(logging.SPAM)
elif verbosity >= 3:
    logger.setLevel(logging.DEBUG)
elif verbosity >= 2:
    logger.setLevel(logging.VERBOSE)
elif verbosity >= 1:
    logger.setLevel(logging.NOTICE)
elif verbosity < 0:
    logger.setLevel(logging.WARNING)

# Your code goes here.
...

If you want to set VerboseLogger as the default logging class for all subsequent logger instances, you can do so using verboselogs.install():

import logging
import verboselogs

verboselogs.install()
logger = logging.getLogger(__name__) # will be a VerboseLogger instance

Pylint plugin

If using the above verboselogs.install() approach, Pylint is not smart enough to recognize that logging is using verboselogs, resulting in errors like:

E:285,24: Module 'logging' has no 'VERBOSE' member (no-member)
E:375,12: Instance of 'RootLogger' has no 'verbose' member (no-member)

To fix this, verboselogs provides a Pylint plugin verboselogs.pylint which, when loaded with pylint --load-plugins verboselogs.pylint, adds the verboselogs methods and constants to Pylint’s understanding of the logging module.

Overview of logging levels

The table below shows the names, numeric values and descriptions of the predefined log levels and the VERBOSE, NOTICE, and SPAM levels defined by this package, plus some notes that I added.

Level	Value	Description	Notes
NOTSET	0	When a logger is created, the level is set to NOTSET (note that the root logger is created with level WARNING).	This level isn’t intended to be used explicitly, however when a logger has its level set to NOTSET its effective level will be inherited from the parent logger.
SPAM	5	Way too verbose for regular debugging, but nice to have when someone is getting desperate in a late night debugging session and decides that they want as much instrumentation as possible! :-)
DEBUG	10	Detailed information, typically of interest only when diagnosing problems.	Usually at this level the logging output is so low level that it’s not useful to users who are not familiar with the software’s internals.
VERBOSE	15	Detailed information that should be understandable to experienced users to provide insight in the software’s behavior; a sort of high level debugging information.
INFO	20	Confirmation that things are working as expected.
NOTICE	25	Auditing information about things that have multiple success paths or may need to be reverted.
WARNING	30	An indication that something unexpected happened, or indicative of some problem in the near future (e.g. ‘disk space low’). The software is still working as expected.
SUCCESS	35	A very explicit confirmation of success.
ERROR	40	Due to a more serious problem, the software has not been able to perform some function.
CRITICAL	50	A serious error, indicating that the program itself may be unable to continue running.

Contact

The latest version of verboselogs is available on PyPI and GitHub. The documentation is hosted on Read the Docs. For bug reports please create an issue on GitHub. If you have questions, suggestions, etc. feel free to send me an e-mail at peter@peterodding.com.

License

This software is licensed under the MIT license.

© 2017 Peter Odding.

The second part is the documentation of the available modules:

API documentation

The following documentation is based on the source code of version 1.7 of the verboselogs package.

verboselogs

Custom log levels for Python’s logging module.

The verboselogs module defines the NOTICE, SPAM, SUCCESS and VERBOSE constants, the VerboseLogger class and the add_log_level() and install() functions.

At import time add_log_level() is used to register the custom log levels NOTICE, SPAM, SUCCESS and VERBOSE with Python’s logging module.

verboselogs.NOTICE = 25

The numeric value of the ‘notice’ log level (a number).

The value of NOTICE positions the notice log level between the WARNING and INFO levels. Refer to pull request #3 for more details.

See also:The notice() method of the VerboseLogger class.

verboselogs.SPAM = 5

The numeric value of the ‘spam’ log level (a number).

The value of SPAM positions the spam log level between the DEBUG and NOTSET levels.

See also:The spam() method of the VerboseLogger class.

verboselogs.SUCCESS = 35

The numeric value of the ‘success’ log level (a number).

The value of SUCCESS positions the success log level between the WARNING and ERROR levels. Refer to issue #4 for more details.

See also:The success() method of the VerboseLogger class.

verboselogs.VERBOSE = 15

The numeric value of the ‘verbose’ log level (a number).

The value of VERBOSE positions the verbose log level between the INFO and DEBUG levels.

See also:The verbose() method of the VerboseLogger class.

verboselogs.install()

Make VerboseLogger the default logger class.

The install() function uses setLoggerClass() to configure VerboseLogger as the default class for all loggers created by logging.getLogger() after install() has been called. Here’s how it works:

import logging
import verboselogs

verboselogs.install()
logger = logging.getLogger(__name__) # will be a VerboseLogger instance

verboselogs.add_log_level(value, name)

Add a new log level to the logging module.

Parameters:

• value – The log level’s number (an integer).
• name – The name for the log level (a string).

class verboselogs.VerboseLogger(*args, **kw)

Custom logger class to support the additional logging levels.

This subclass of logging.Logger adds support for the additional logging methods notice(), spam(), success() and verbose().

You can use verboselogs.install() to make VerboseLogger the default logger class.

notice(msg, *args, **kw)

Log a message with level NOTICE. The arguments are interpreted as for logging.debug().

spam(msg, *args, **kw)

Log a message with level SPAM. The arguments are interpreted as for logging.debug().

success(msg, *args, **kw)

Log a message with level SUCCESS. The arguments are interpreted as for logging.debug().

verbose(msg, *args, **kw)

Log a message with level VERBOSE. The arguments are interpreted as for logging.debug().

verboselogs.pylint

Pylint plugin to fix invalid errors about the logging module.

verboselogs.pylint.register(linter)

No-op (required by Pylint).

verboselogs.pylint.verboselogs_class_transform(cls)

Make Pylint aware of our custom logger methods.

verboselogs.pylint.verboselogs_module_transform(mod)

Make Pylint aware of our custom log levels.