verboselogs: Verbose logging level for Python's logging module
==============================================================
.. image:: https://travis-ci.org/xolox/python-verboselogs.svg?branch=master
:target: https://travis-ci.org/xolox/python-verboselogs
.. image:: https://coveralls.io/repos/xolox/python-verboselogs/badge.png?branch=master
:target: https://coveralls.io/r/xolox/python-verboselogs?branch=master
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.
.. contents::
:local:
:depth: 2
Installation
------------
The verboselogs package is available on PyPI_ which means installation should
be as simple as:
.. code-block:: sh
$ 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:
.. code-block:: python
"""
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()`_:
.. code-block:: python
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 This level isn't intended to
level is set to NOTSET (note be used explicitly, however
that the root logger is when a logger has its level
created with level WARNING). 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, Usually at this level the
typically of interest only logging output is so low
when diagnosing problems. 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.
.. External references:
.. _descriptions: http://docs.python.org/howto/logging.html#when-to-use-logging
.. _GitHub: https://github.com/xolox/python-verboselogs
.. _logging: http://docs.python.org/library/logging.html
.. _MIT license: http://en.wikipedia.org/wiki/MIT_License
.. _NOTICE: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.NOTICE
.. _numeric values: http://docs.python.org/howto/logging.html#logging-levels
.. _per user site-packages directory: https://www.python.org/dev/peps/pep-0370/
.. _peter@peterodding.com: peter@peterodding.com
.. _Pylint: https://pypi.python.org/pypi/pylint
.. _PyPI: https://pypi.python.org/pypi/verboselogs
.. _Read the Docs: https://verboselogs.readthedocs.io
.. _SPAM: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.SPAM
.. _SUCCESS: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.SUCCESS
.. _VERBOSE: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.VERBOSE
.. _VerboseLogger: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.VerboseLogger
.. _verboselogs.install(): http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.install
.. _verboselogs.pylint: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.pylint
.. _verboselogs: https://pypi.python.org/pypi/verboselogs/
.. _virtual environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/
Raw data
{
"_id": null,
"home_page": "https://verboselogs.readthedocs.io",
"name": "verboselogs",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Peter Odding",
"author_email": "peter@peterodding.com",
"download_url": "https://files.pythonhosted.org/packages/29/15/90ffe9bdfdd1e102bc6c21b1eea755d34e69772074b6e706cab741b9b698/verboselogs-1.7.tar.gz",
"platform": "",
"description": "verboselogs: Verbose logging level for Python's logging module\n==============================================================\n\n.. image:: https://travis-ci.org/xolox/python-verboselogs.svg?branch=master\n :target: https://travis-ci.org/xolox/python-verboselogs\n\n.. image:: https://coveralls.io/repos/xolox/python-verboselogs/badge.png?branch=master\n :target: https://coveralls.io/r/xolox/python-verboselogs?branch=master\n\nThe verboselogs_ package extends Python's logging_ module to add the log levels\nNOTICE_, SPAM_, SUCCESS_ and VERBOSE_:\n\n- The NOTICE level sits between the predefined WARNING and INFO levels.\n- The SPAM level sits between the predefined DEBUG and NOTSET levels.\n- The SUCCESS level sits between the predefined WARNING and ERROR levels.\n- The VERBOSE level sits between the predefined INFO and DEBUG levels.\n\nThe code to do this is simple and short, but I still don't want to copy/paste\nit to every project I'm working on, hence this package. It's currently tested\non Python 2.6, 2.7, 3.4, 3.5, 3.6 and PyPy.\n\n.. contents::\n :local:\n :depth: 2\n\nInstallation\n------------\n\nThe verboselogs package is available on PyPI_ which means installation should\nbe as simple as:\n\n.. code-block:: sh\n\n $ pip install verboselogs\n\nThere's actually a multitude of ways to install Python packages (e.g. the `per\nuser site-packages directory`_, `virtual environments`_ or just installing\nsystem wide) and I have no intention of getting into that discussion here, so\nif this intimidates you then read up on your options before returning to these\ninstructions ;-).\n\nUsage\n-----\n\nIt's very simple to start using the verboselogs package:\n\n>>> import logging, verboselogs\n>>> logger = verboselogs.VerboseLogger('verbose-demo')\n>>> logger.addHandler(logging.StreamHandler())\n>>> logger.setLevel(logging.VERBOSE)\n>>> logger.verbose(\"Can we have verbose logging? %s\", \"Yes we can!\")\n\nHere's a skeleton of a very simple Python program with a command line interface\nand configurable logging:\n\n.. code-block:: python\n\n \"\"\"\n Usage: demo.py [OPTIONS]\n\n This is the usage message of demo.py. Usually\n this text explains how to use the program.\n\n Supported options:\n -v, --verbose make more noise\n -h, --help show this message and exit\n \"\"\"\n\n import getopt\n import logging\n import sys\n import verboselogs\n\n logger = verboselogs.VerboseLogger('demo')\n logger.addHandler(logging.StreamHandler())\n logger.setLevel(logging.INFO)\n\n # Command line option defaults.\n verbosity = 0\n\n # Parse command line options.\n opts, args = getopt.getopt(sys.argv[1:], 'vqh', ['verbose', 'quiet', 'help'])\n\n # Map command line options to variables.\n for option, argument in opts:\n if option in ('-v', '--verbose'):\n verbosity += 1\n elif option in ('-q', '--quiet'):\n verbosity -= 1\n elif option in ('-h', '--help'):\n print __doc__.strip()\n sys.exit(0)\n else:\n assert False, \"Unhandled option!\"\n\n # Configure logger for requested verbosity.\n if verbosity >= 4:\n logger.setLevel(logging.SPAM)\n elif verbosity >= 3:\n logger.setLevel(logging.DEBUG)\n elif verbosity >= 2:\n logger.setLevel(logging.VERBOSE)\n elif verbosity >= 1:\n logger.setLevel(logging.NOTICE)\n elif verbosity < 0:\n logger.setLevel(logging.WARNING)\n\n # Your code goes here.\n ...\n\nIf you want to set VerboseLogger_ as the default logging class for all\nsubsequent logger instances, you can do so using `verboselogs.install()`_:\n\n.. code-block:: python\n\n import logging\n import verboselogs\n\n verboselogs.install()\n logger = logging.getLogger(__name__) # will be a VerboseLogger instance\n\nPylint plugin\n-------------\n\nIf using the above `verboselogs.install()`_ approach, Pylint_ is not smart\nenough to recognize that logging_ is using verboselogs, resulting in errors\nlike::\n\n E:285,24: Module 'logging' has no 'VERBOSE' member (no-member)\n E:375,12: Instance of 'RootLogger' has no 'verbose' member (no-member)\n\nTo fix this, verboselogs provides a Pylint plugin verboselogs.pylint_ which,\nwhen loaded with ``pylint --load-plugins verboselogs.pylint``, adds the\nverboselogs methods and constants to Pylint's understanding of the logging_\nmodule.\n\nOverview of logging levels\n--------------------------\n\nThe table below shows the names, `numeric values`_ and descriptions_ of the\npredefined log levels and the VERBOSE, NOTICE, and SPAM levels defined by this\npackage, plus some notes that I added.\n\n======== ===== ============================= =============================\nLevel Value Description Notes\n======== ===== ============================= =============================\nNOTSET 0 When a logger is created, the This level isn't intended to\n level is set to NOTSET (note be used explicitly, however\n that the root logger is when a logger has its level\n created with level WARNING). set to NOTSET its effective\n level will be inherited from\n the parent logger.\nSPAM 5 Way too verbose for regular\n debugging, but nice to have\n when someone is getting\n desperate in a late night\n debugging session and decides\n that they want as much\n instrumentation as possible!\n :-)\nDEBUG 10 Detailed information, Usually at this level the\n typically of interest only logging output is so low\n when diagnosing problems. level that it's not useful\n to users who are not\n familiar with the software's\n internals.\nVERBOSE 15 Detailed information that\n should be understandable to\n experienced users to provide\n insight in the software's\n behavior; a sort of high\n level debugging information.\nINFO 20 Confirmation that things\n are working as expected.\nNOTICE 25 Auditing information about\n things that have multiple\n success paths or may need to\n be reverted.\nWARNING 30 An indication that something\n unexpected happened, or\n indicative of some problem\n in the near future (e.g.\n \u2018disk space low\u2019). The\n software is still working\n as expected.\nSUCCESS 35 A very explicit confirmation\n of success.\nERROR 40 Due to a more serious\n problem, the software has not\n been able to perform some\n function.\nCRITICAL 50 A serious error, indicating\n that the program itself may\n be unable to continue\n running.\n======== ===== ============================= =============================\n\nContact\n-------\n\nThe latest version of verboselogs is available on PyPI_ and GitHub_. The\ndocumentation is hosted on `Read the Docs`_. For bug reports please create an\nissue on GitHub_. If you have questions, suggestions, etc. feel free to send me\nan e-mail at `peter@peterodding.com`_.\n\nLicense\n-------\n\nThis software is licensed under the `MIT license`_.\n\n\u00a9 2017 Peter Odding.\n\n.. External references:\n.. _descriptions: http://docs.python.org/howto/logging.html#when-to-use-logging\n.. _GitHub: https://github.com/xolox/python-verboselogs\n.. _logging: http://docs.python.org/library/logging.html\n.. _MIT license: http://en.wikipedia.org/wiki/MIT_License\n.. _NOTICE: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.NOTICE\n.. _numeric values: http://docs.python.org/howto/logging.html#logging-levels\n.. _per user site-packages directory: https://www.python.org/dev/peps/pep-0370/\n.. _peter@peterodding.com: peter@peterodding.com\n.. _Pylint: https://pypi.python.org/pypi/pylint\n.. _PyPI: https://pypi.python.org/pypi/verboselogs\n.. _Read the Docs: https://verboselogs.readthedocs.io\n.. _SPAM: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.SPAM\n.. _SUCCESS: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.SUCCESS\n.. _VERBOSE: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.VERBOSE\n.. _VerboseLogger: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.VerboseLogger\n.. _verboselogs.install(): http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.install\n.. _verboselogs.pylint: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.pylint\n.. _verboselogs: https://pypi.python.org/pypi/verboselogs/\n.. _virtual environments: http://docs.python-guide.org/en/latest/dev/virtualenvs/\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Verbose logging level for Python's logging module",
"version": "1.7",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "da40d0a9becbd9c4ffb0e9bd3f74a0d4",
"sha256": "d63f23bf568295b95d3530c6864a0b580cec70e7ff974177dead1e4ffbc6ff49"
},
"downloads": -1,
"filename": "verboselogs-1.7-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "da40d0a9becbd9c4ffb0e9bd3f74a0d4",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 11907,
"upload_time": "2017-08-07T19:46:15",
"upload_time_iso_8601": "2017-08-07T19:46:15.266839Z",
"url": "https://files.pythonhosted.org/packages/b8/9d/c5c3cb0093642042fd604b53928ac65e7650fdc5a8a97814288e29beab84/verboselogs-1.7-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "7c33bd58875e0d316a4f8d7505e946ff",
"sha256": "e33ddedcdfdafcb3a174701150430b11b46ceb64c2a9a26198c76a156568e427"
},
"downloads": -1,
"filename": "verboselogs-1.7.tar.gz",
"has_sig": false,
"md5_digest": "7c33bd58875e0d316a4f8d7505e946ff",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10338,
"upload_time": "2017-08-07T19:46:16",
"upload_time_iso_8601": "2017-08-07T19:46:16.674766Z",
"url": "https://files.pythonhosted.org/packages/29/15/90ffe9bdfdd1e102bc6c21b1eea755d34e69772074b6e706cab741b9b698/verboselogs-1.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2017-08-07 19:46:16",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "verboselogs"
}
JSON