Merge pull request #3: Add NOTICE log level

Makefile

@@ -1,7 +1,7 @@
-# Verbose and spam log levels for Python's logging module.
+# Verbose, notice, and spam log levels for Python's logging module.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: June 23, 2016
+# Last Change: July 26, 2016
 # URL: https://verboselogs.readthedocs.io
 
 WORKON_HOME ?= $(HOME)/.virtualenvs
@@ -19,7 +19,6 @@ default:
 	@echo '    make reset     recreate the virtual environment'
 	@echo '    make check     check coding style (PEP-8, PEP-257)'
 	@echo '    make test      run the test suite'
-	@echo '    make readme    update usage in readme'
 	@echo '    make docs      update documentation using Sphinx'
 	@echo '    make publish   publish changes to GitHub/PyPI'
 	@echo '    make clean     cleanup all temporary files'

README.rst

@@ -8,9 +8,10 @@ verboselogs: Verbose logging level for Python's logging module
    :target: https://coveralls.io/r/xolox/python-verboselogs?branch=master
 
 The verboselogs_ package extends Python's logging_ module to add the log levels
-VERBOSE_ and SPAM_:
+VERBOSE_, NOTICE_, and SPAM_:
 
 - The VERBOSE level sits between the predefined INFO and DEBUG levels.
+- The NOTICE level sits between the predefined WARNING and INFO levels.
 - The SPAM level sits between the predefined DEBUG and NOTSET levels.
 
 The code to do this is simple and short, but I still don't want to copy/paste
@@ -92,12 +93,14 @@ and configurable logging:
            assert False, "Unhandled option!"
 
    # Configure logger for requested verbosity.
-   if verbosity >= 3:
+   if verbosity >= 4:
        logger.setLevel(logging.SPAM)
-   elif verbosity >= 2:
+   elif verbosity >= 3:
        logger.setLevel(logging.DEBUG)
-   elif verbosity >= 1:
+   elif verbosity >= 2:
        logger.setLevel(logging.VERBOSE)
+   elif verbosity >= 1:
+       logger.setLevel(logging.NOTICE)
    elif verbosity < 0:
        logger.setLevel(logging.WARNING)
 
@@ -134,8 +137,8 @@ Overview of logging levels
 --------------------------
 
 The table below shows the names, `numeric values`_ and descriptions_ of the
-predefined log levels and the VERBOSE and SPAM levels defined by this package,
-plus some notes that I added.
+predefined log levels and the VERBOSE, NOTICE, and SPAM levels defined by this
+package, plus some notes that I added.
 
 ========  =====  =============================  =============================
 Level     Value  Description                    Notes
@@ -166,6 +169,10 @@ VERBOSE   15     Detailed information that
                  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
@@ -210,6 +217,7 @@ This software is licensed under the `MIT license`_.
 .. _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
+.. _NOTICE: http://verboselogs.readthedocs.io/en/latest/api.html#verboselogs.NOTICE
 .. _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

docs/conf.py

@@ -1,7 +1,7 @@
-# Verbose and spam log levels for Python's logging module.
+# Verbose, notice, and spam log levels for Python's logging module.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: June 23, 2016
+# Last Change: July 26, 2016
 # URL: https://verboselogs.readthedocs.io
 
 """Sphinx documentation configuration for the `verboselogs` package."""
@@ -67,7 +67,7 @@
 # Refer to the Python standard library.
 # From: http://twistedmatrix.com/trac/ticket/4582.
 intersphinx_mapping = dict(
-    python=('http://docs.python.org', None),
+    python=('https://docs.python.org/2', None),
 )
 
 # -- Options for HTML output ---------------------------------------------------

setup.py

@@ -1,9 +1,9 @@
 #!/usr/bin/env python
 
-# Verbose and spam log levels for Python's logging module.
+# Verbose, notice, and spam log levels for Python's logging module.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: June 23, 2016
+# Last Change: July 26, 2016
 # URL: https://verboselogs.readthedocs.io
 
 """Setup script for the `verboselogs` package."""

verboselogs/__init__.py

@@ -1,24 +1,36 @@
-# Verbose and spam log levels for Python's logging module.
+# Verbose, notice, and spam log levels for Python's logging module.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: June 23, 2016
+# Last Change: July 26, 2016
 # URL: https://verboselogs.readthedocs.io
 
 """
-Verbose and spam log levels for Python's :mod:`logging` module.
-
-The :mod:`verboselogs` module defines the :data:`VERBOSE` and :data:`SPAM`
-constants, the :class:`VerboseLogger` class and the :func:`add_log_level()` and
-:func:`install()` functions. At import time :func:`add_log_level()` is used to
-register the custom log levels :data:`VERBOSE` and :data:`SPAM` with Python's
-:mod:`logging` module.
+Verbose, notice, and spam log levels for Python's :mod:`logging` module.
+
+The :mod:`verboselogs` module defines the :data:`VERBOSE`, :data:`NOTICE`, and
+:data:`SPAM` constants, the :class:`VerboseLogger` class and the
+:func:`add_log_level()` and :func:`install()` functions. At import time
+:func:`add_log_level()` is used to register the custom log levels
+:data:`VERBOSE`, :data:`NOTICE`, and :data:`SPAM` with Python's :mod:`logging`
+module.
 """
 
 import logging
 
-__version__ = '1.4'
+__version__ = '1.5'
 """Semi-standard module versioning."""
 
+NOTICE = 25
+"""
+The numeric value of the 'notice' log level (a number).
+
+The value of :data:`NOTICE` positions the notice log level between the
+:data:`~logging.WARNING` and :data:`~logging.INFO` levels.
+
+:see also: The :func:`~VerboseLogger.notice()` method of the
+           :class:`VerboseLogger` class.
+"""
+
 VERBOSE = 15
 """
 The numeric value of the 'verbose' log level (a number).
@@ -73,6 +85,9 @@ def add_log_level(value, name):
     setattr(logging, name, value)
 
 
+# Define the NOTICE log level.
+add_log_level(NOTICE, 'NOTICE')
+
 # Define the VERBOSE log level.
 add_log_level(VERBOSE, 'VERBOSE')
 
@@ -86,9 +101,9 @@ class VerboseLogger(logging.Logger):
     Custom logger class to support the additional logging levels.
 
     This subclass of :class:`logging.Logger` adds support for the additional
-    logging methods :func:`verbose()` and :func:`spam()`. You can use
-    :func:`install()` to make :class:`VerboseLogger` the default logger
-    class.
+    logging methods :func:`verbose()`,  :func:`notice()`, and :func:`spam()`.
+    You can use :func:`install()` to make :class:`VerboseLogger` the default
+    logger class.
     """
 
     def __init__(self, *args, **kw):
@@ -110,6 +125,10 @@ def __init__(self, *args, **kw):
         logging.Logger.__init__(self, *args, **kw)
         self.parent = logging.getLogger()
 
+    def notice(self, *args, **kw):
+        """Log a message with level :data:`NOTICE`. The arguments are interpreted as for :func:`logging.debug()`."""
+        self.log(NOTICE, *args, **kw)
+
     def verbose(self, *args, **kw):
         """Log a message with level :data:`VERBOSE`. The arguments are interpreted as for :func:`logging.debug()`."""
         self.log(VERBOSE, *args, **kw)

verboselogs/pylint.py

@@ -1,7 +1,7 @@
-# Verbose and spam log levels for Python's logging module.
+# Verbose, notice, and spam log levels for Python's logging module.
 #
 # Author: Glenn Matthews <glenn@e-dad.net>
-# Last Change: June 23, 2016
+# Last Change: July 26, 2016
 # URL: https://verboselogs.readthedocs.io
 
 """
@@ -18,16 +18,16 @@ def register(linter):
 
 
 def verboselogs_class_transform(cls):
-    """Make Pylint aware of ``RootLogger.verbose()`` and ``RootLogger.spam()``."""
+    """Make Pylint aware of ``RootLogger.verbose()``, ``RootLogger.notice()``, and ``RootLogger.spam()``."""
     if cls.name == 'RootLogger':
-        for meth in ['verbose', 'spam']:
+        for meth in ['notice', 'verbose', 'spam']:
             cls.locals[meth] = [scoped_nodes.Function(meth, None)]
 
 
 def verboselogs_module_transform(mod):
-    """Make Pylint aware of ``logging.VERBOSE`` and ``logging.SPAM``."""
+    """Make Pylint aware of ``logging.VERBOSE``, ``logging.notice()``, and ``logging.SPAM``."""
     if mod.name == 'logging':
-        for const in ['VERBOSE', 'SPAM']:
+        for const in ['NOTICE', 'VERBOSE', 'SPAM']:
             mod.locals[const] = [nodes.Const(const)]
 
 

verboselogs/tests.py

@@ -1,7 +1,7 @@
-# Verbose and spam log levels for Python's logging module.
+# Verbose, notice, and spam log levels for Python's logging module.
 #
 # Author: Peter Odding <peter@peterodding.com>
-# Last Change: June 23, 2016
+# Last Change: July 26, 2016
 # URL: https://verboselogs.readthedocs.io
 
 """Test suite for the `verboselogs` package."""
@@ -38,8 +38,14 @@ def test_install(self):
         assert isinstance(custom_logger, verboselogs.VerboseLogger)
 
     def test_custom_methods(self):
-        """Test :func:`~verboselogs.VerboseLogger.verbose()` and :func:`~verboselogs.VerboseLogger.spam()`."""
-        for name in 'verbose', 'spam':
+        """
+        Test logging functions.
+
+        Test :func:`~verboselogs.VerboseLogger.verbose()`,
+        :func:`~verboselogs.VerboseLogger.notice()`, and
+        :func:`~verboselogs.VerboseLogger.spam()`.
+        """
+        for name in 'notice', 'verbose', 'spam':
             logger = verboselogs.VerboseLogger(random_string())
             logger.log = mock.MagicMock()
             level = getattr(verboselogs, name.upper())