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