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