1verboselogs: Verbose logging level for Python's logging module
2==============================================================
3
4.. image:: https://travis-ci.org/xolox/python-verboselogs.svg?branch=master
5   :target: https://travis-ci.org/xolox/python-verboselogs
6
7.. image:: https://coveralls.io/repos/xolox/python-verboselogs/badge.png?branch=master
8   :target: https://coveralls.io/r/xolox/python-verboselogs?branch=master
9
10The verboselogs_ package extends Python's logging_ module to add the log levels
11NOTICE_, SPAM_, SUCCESS_ and VERBOSE_:
12
13- The NOTICE level sits between the predefined WARNING and INFO levels.
14- The SPAM level sits between the predefined DEBUG and NOTSET levels.
15- The SUCCESS level sits between the predefined WARNING and ERROR levels.
16- The VERBOSE level sits between the predefined INFO and DEBUG levels.
17
18The code to do this is simple and short, but I still don't want to copy/paste
19it to every project I'm working on, hence this package. It's currently tested
20on Python 2.6, 2.7, 3.4, 3.5, 3.6 and PyPy.
21
22.. contents::
23   :local:
24   :depth: 2
25
26Installation
27------------
28
29The verboselogs package is available on PyPI_ which means installation should
30be as simple as:
31
32.. code-block:: sh
33
34   $ pip install verboselogs
35
36There's actually a multitude of ways to install Python packages (e.g. the `per
37user site-packages directory`_, `virtual environments`_ or just installing
38system wide) and I have no intention of getting into that discussion here, so
39if this intimidates you then read up on your options before returning to these
40instructions ;-).
41
42Usage
43-----
44
45It's very simple to start using the verboselogs package:
46
47>>> import logging, verboselogs
48>>> logger = verboselogs.VerboseLogger('verbose-demo')
49>>> logger.addHandler(logging.StreamHandler())
50>>> logger.setLevel(logging.VERBOSE)
51>>> logger.verbose("Can we have verbose logging? %s", "Yes we can!")
52
53Here's a skeleton of a very simple Python program with a command line interface
54and configurable logging:
55
56.. code-block:: python
57
58   """
59   Usage: demo.py [OPTIONS]
60
61   This is the usage message of demo.py. Usually
62   this text explains how to use the program.
63
64   Supported options:
65     -v, --verbose  make more noise
66     -h, --help     show this message and exit
67   """
68
69   import getopt
70   import logging
71   import sys
72   import verboselogs
73
74   logger = verboselogs.VerboseLogger('demo')
75   logger.addHandler(logging.StreamHandler())
76   logger.setLevel(logging.INFO)
77
78   # Command line option defaults.
79   verbosity = 0
80
81   # Parse command line options.
82   opts, args = getopt.getopt(sys.argv[1:], 'vqh', ['verbose', 'quiet', 'help'])
83
84   # Map command line options to variables.
85   for option, argument in opts:
86       if option in ('-v', '--verbose'):
87           verbosity += 1
88       elif option in ('-q', '--quiet'):
89           verbosity -= 1
90       elif option in ('-h', '--help'):
91           print __doc__.strip()
92           sys.exit(0)
93       else:
94           assert False, "Unhandled option!"
95
96   # Configure logger for requested verbosity.
97   if verbosity >= 4:
98       logger.setLevel(logging.SPAM)
99   elif verbosity >= 3:
100       logger.setLevel(logging.DEBUG)
101   elif verbosity >= 2:
102       logger.setLevel(logging.VERBOSE)
103   elif verbosity >= 1:
104       logger.setLevel(logging.NOTICE)
105   elif verbosity < 0:
106       logger.setLevel(logging.WARNING)
107
108   # Your code goes here.
109   ...
110
111If you want to set VerboseLogger_ as the default logging class for all
112subsequent logger instances, you can do so using `verboselogs.install()`_:
113
114.. code-block:: python
115
116   import logging
117   import verboselogs
118
119   verboselogs.install()
120   logger = logging.getLogger(__name__) # will be a VerboseLogger instance
121
122Pylint plugin
123-------------
124
125If using the above `verboselogs.install()`_ approach, Pylint_ is not smart
126enough to recognize that logging_ is using verboselogs, resulting in errors
127like::
128
129   E:285,24: Module 'logging' has no 'VERBOSE' member (no-member)
130   E:375,12: Instance of 'RootLogger' has no 'verbose' member (no-member)
131
132To fix this, verboselogs provides a Pylint plugin verboselogs.pylint_ which,
133when loaded with ``pylint --load-plugins verboselogs.pylint``, adds the
134verboselogs methods and constants to Pylint's understanding of the logging_
135module.
136
137Overview of logging levels
138--------------------------
139
140The table below shows the names, `numeric values`_ and descriptions_ of the
141predefined log levels and the VERBOSE, NOTICE, and SPAM levels defined by this
142package, plus some notes that I added.
143
144========  =====  =============================  =============================
145Level     Value  Description                    Notes
146========  =====  =============================  =============================
147NOTSET    0      When a logger is created, the  This level isn't intended to
148                 level is set to NOTSET (note   be used explicitly, however
149                 that the root logger is        when a logger has its level
150                 created with level WARNING).   set to NOTSET its effective
151                                                level will be inherited from
152                                                the parent logger.
153SPAM      5      Way too verbose for regular
154                 debugging, but nice to have
155                 when someone is getting
156                 desperate in a late night
157                 debugging session and decides
158                 that they want as much
159                 instrumentation as possible!
160                 :-)
161DEBUG     10     Detailed information,          Usually at this level the
162                 typically of interest only     logging output is so low
163                 when diagnosing problems.      level that it's not useful
164                                                to users who are not
165                                                familiar with the software's
166                                                internals.
167VERBOSE   15     Detailed information that
168                 should be understandable to
169                 experienced users to provide
170                 insight in the software's
171                 behavior; a sort of high
172                 level debugging information.
173INFO      20     Confirmation that things
174                 are working as expected.
175NOTICE    25     Auditing information about
176                 things that have multiple
177                 success paths or may need to
178                 be reverted.
179WARNING   30     An indication that something
180                 unexpected happened, or
181                 indicative of some problem
182                 in the near future (e.g.
183                 ‘disk space low’). The
184                 software is still working
185                 as expected.
186SUCCESS   35     A very explicit confirmation
187                 of success.
188ERROR     40     Due to a more serious
189                 problem, the software has not
190                 been able to perform some
191                 function.
192CRITICAL  50     A serious error, indicating
193                 that the program itself may
194                 be unable to continue
195                 running.
196========  =====  =============================  =============================
197
198Contact
199-------
200
201The latest version of verboselogs is available on PyPI_ and GitHub_. The
202documentation is hosted on `Read the Docs`_. For bug reports please create an
203issue on GitHub_. If you have questions, suggestions, etc. feel free to send me
204an e-mail at `peter@peterodding.com`_.
205
206License
207-------
208
209This software is licensed under the `MIT license`_.
210
211© 2017 Peter Odding.
212
213.. External references:
214.. _descriptions: http://docs.python.org/howto/logging.html#when-to-use-logging
215.. _GitHub: https://github.com/xolox/python-verboselogs
216.. _logging: http://docs.python.org/library/logging.html
217.. _MIT license: http://en.wikipedia.org/wiki/MIT_License
218.. _NOTICE: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.NOTICE
219.. _numeric values: http://docs.python.org/howto/logging.html#logging-levels
220.. _per user site-packages directory: https://www.python.org/dev/peps/pep-0370/
221.. _peter@peterodding.com: peter@peterodding.com
222.. _Pylint: https://pypi.python.org/pypi/pylint
223.. _PyPI: https://pypi.python.org/pypi/verboselogs
224.. _Read the Docs: https://verboselogs.readthedocs.io
225.. _SPAM: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.SPAM
226.. _SUCCESS: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.SUCCESS
227.. _VERBOSE: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.VERBOSE
228.. _VerboseLogger: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.VerboseLogger
229.. _verboselogs.install(): http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.install
230.. _verboselogs.pylint: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.pylint
231.. _verboselogs: https://pypi.python.org/pypi/verboselogs/
232.. _virtual environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/
233