[Python-checkins] r85029 - in python/branches: py3k/Doc/library/logging.rst release27-maint/Doc/library/logging.rst

[vinay.sajip]

Author: vinay.sajip
Date: Mon Sep 27 15:53:47 2010
New Revision: 85029

Log:
logging: Updated library configuration documentation.

Modified:
   python/branches/py3k/Doc/library/logging.rst
   python/branches/release27-maint/Doc/library/logging.rst

Modified: python/branches/py3k/Doc/library/logging.rst
==============================================================================
--- python/branches/py3k/Doc/library/logging.rst	(original)
+++ python/branches/py3k/Doc/library/logging.rst	Mon Sep 27 15:53:47 2010
@@ -526,10 +526,18 @@
 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:`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.
+
 .. versionadded:: 3.1
 
-   The :class:`NullHandler` class was not present in previous versions, but is
-   now included, so that it need not be defined in library code.
+The :class:`NullHandler` class was not present in previous versions, but is
+now included, so that it need not be defined in library code.
 
 
 
@@ -2141,6 +2149,16 @@
 
       This method does nothing.
 
+   .. method:: handle(record)
+
+      This method does nothing.
+
+   .. method:: createLock()
+
+      This method returns `None` for the lock, since there is no
+      underlying I/O to which access needs to be serialized.
+
+
 See :ref:`library-config` for more information on how to use
 :class:`NullHandler`.
 

Modified: python/branches/release27-maint/Doc/library/logging.rst
==============================================================================
--- python/branches/release27-maint/Doc/library/logging.rst	(original)
+++ python/branches/release27-maint/Doc/library/logging.rst	Mon Sep 27 15:53:47 2010
@@ -530,6 +530,14 @@
 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:`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.
+
 .. versionadded:: 2.7
 
 The :class:`NullHandler` class was not present in previous versions, but is now
@@ -1957,6 +1965,16 @@
 
       This method does nothing.
 
+   .. method:: handle(record)
+
+      This method does nothing.
+
+   .. method:: createLock()
+
+      This method returns `None` for the lock, since there is no
+      underlying I/O to which access needs to be serialized.
+
+
 See :ref:`library-config` for more information on how to use
 :class:`NullHandler`.