Issue #16884: updated logging documentation to include lastResort and use 'note' directives where appropriate.

vsajip · vsajip · commit e50f4d2220c2 · 2013-01-07T14:16:52.000Z
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
@@ -780,13 +780,14 @@ should have the desired effect. If an organisation produces a number of
 libraries, then the logger name specified can be 'orgname.foo' rather than
 just 'foo'.
 
-**PLEASE NOTE:** It is strongly advised that you *do not add any handlers other
-than* :class:`~logging.NullHandler` *to your library's loggers*. This is
-because the configuration of handlers is the prerogative of the application
-developer who uses your library. The application developer knows their target
-audience and what handlers are most appropriate for their application: if you
-add handlers 'under the hood', you might well interfere with their ability to
-carry out unit tests and deliver logs which suit their requirements.
+.. note:: It is strongly advised that you *do not add any handlers other
+   than* :class:`~logging.NullHandler` *to your library's loggers*. This is
+   because the configuration of handlers is the prerogative of the application
+   developer who uses your library. The application developer knows their
+   target audience and what handlers are most appropriate for their
+   application: if you add handlers 'under the hood', you might well interfere
+   with their ability to carry out unit tests and deliver logs which suit their
+   requirements.
 
 
 Logging Levels
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
@@ -928,14 +928,14 @@ functions.
    Logs a message with level *level* on the root logger. The other arguments are
    interpreted as for :func:`debug`.
 
-   PLEASE NOTE: The above module-level functions which delegate to the root
-   logger should *not* be used in threads, in versions of Python earlier than
-   2.7.1 and 3.2, unless at least one handler has been added to the root
-   logger *before* the threads are started. These convenience functions call
-   :func:`basicConfig` to ensure that at least one handler is available; in
-   earlier versions of Python, this can (under rare circumstances) lead to
-   handlers being added multiple times to the root logger, which can in turn
-   lead to multiple messages for the same event.
+   .. note:: The above module-level functions which delegate to the root
+      logger should *not* be used in threads, in versions of Python earlier
+      than 2.7.1 and 3.2, unless at least one handler has been added to the
+      root logger *before* the threads are started. These convenience functions
+      call :func:`basicConfig` to ensure that at least one handler is
+      available; in earlier versions of Python, this can (under rare
+      circumstances) lead to handlers being added multiple times to the root
+      logger, which can in turn lead to multiple messages for the same event.
 
 .. function:: disable(lvl)
 
@@ -991,12 +991,12 @@ functions.
    This function does nothing if the root logger already has handlers
    configured for it.
 
-   PLEASE NOTE: This function should be called from the main thread
-   before other threads are started. In versions of Python prior to
-   2.7.1 and 3.2, if this function is called from multiple threads,
-   it is possible (in rare circumstances) that a handler will be added
-   to the root logger more than once, leading to unexpected results
-   such as messages being duplicated in the log.
+   .. note:: This function should be called from the main thread
+      before other threads are started. In versions of Python prior to
+      2.7.1 and 3.2, if this function is called from multiple threads,
+      it is possible (in rare circumstances) that a handler will be added
+      to the root logger more than once, leading to unexpected results
+      such as messages being duplicated in the log.
 
    The following keyword arguments are supported.
 
@@ -1080,6 +1080,21 @@ functions.
       :kwargs: Additional keyword arguments.
 
 
+Module-Level Attributes
+-----------------------
+
+.. attribute:: lastResort
+
+   A "handler of last resort" is available through this attribute. This
+   is a :class:`StreamHandler` writing to ``sys.stderr`` with a level of
+   ``WARNING``, and is used to handle logging events in the absence of any
+   logging configuration. The end result is to just print the message to
+   ``sys.stderr``. This replaces the earlier error message saying that
+   "no handlers could be found for logger XYZ". If you need the earlier
+   behaviour for some reason, ``lastResort`` can be set to ``None``.
+
+   .. versionadded:: 3.2
+
 Integration with the warnings module
 ------------------------------------
 
