summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorVinay Sajip <vinay_sajip@yahoo.co.uk>2013-01-07 14:19:12 (GMT)
committerVinay Sajip <vinay_sajip@yahoo.co.uk>2013-01-07 14:19:12 (GMT)
commited6f37cad12073128a52aca2ae1e0ee394352865 (patch)
tree9afbd3f5a276cb2f5981f69aff560bc1ba4a7e80 /Doc
parent4e62033b574e9699412ffca5541393f6dc8165fb (diff)
parent0e82fd1f78a9ae07c16b1f57a0f39bc56f798b30 (diff)
downloadcpython-ed6f37cad12073128a52aca2ae1e0ee394352865.zip
cpython-ed6f37cad12073128a52aca2ae1e0ee394352865.tar.gz
cpython-ed6f37cad12073128a52aca2ae1e0ee394352865.tar.bz2
Closes #16884: Merged logging documentation fixes from 3.3.
Diffstat (limited to 'Doc')
-rw-r--r--Doc/howto/logging.rst15
-rw-r--r--Doc/library/logging.rst43
2 files changed, 37 insertions, 21 deletions
diff --git a/Doc/howto/logging.rst b/Doc/howto/logging.rst
index 44b2f59..1e8b662 100644
--- 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
index 0d956b0..2a94e1a 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -948,14 +948,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)
@@ -1011,12 +1011,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.
@@ -1115,6 +1115,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
------------------------------------