verboselogs 1.7

Description:

verboselogs 1.7

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
Usage
Pylint plugin
Overview of logging levels
Contact
License



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 [email protected].


License
This software is licensed under the MIT license.
© 2017 Peter Odding.