Merged revisions 79279,79284,79293,79373,79376,79379,79876,79888 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r79279 | vinay.sajip | 2010-03-22 07:33:08 -0500 (Mon, 22 Mar 2010) | 1 line
Issue #8200: logging: Handle errors when multiprocessing is not fully loaded when logging occurs.
........
r79284 | vinay.sajip | 2010-03-22 08:02:28 -0500 (Mon, 22 Mar 2010) | 1 line
Issue #8201: logging: Handle config errors when non-ASCII and Unicode logger names exist at the same time.
........
r79293 | vinay.sajip | 2010-03-22 10:29:01 -0500 (Mon, 22 Mar 2010) | 1 line
logging: Added getChild utility method to Logger and added isEnabledFor method to LoggerAdapter.
........
r79373 | vinay.sajip | 2010-03-24 09:31:21 -0500 (Wed, 24 Mar 2010) | 1 line
logging: Added LOG_FTP for SysLogHandler and updated documentation.
........
r79376 | vinay.sajip | 2010-03-24 10:10:40 -0500 (Wed, 24 Mar 2010) | 1 line
logging: Documentation tweak.
........
r79379 | vinay.sajip | 2010-03-24 12:36:35 -0500 (Wed, 24 Mar 2010) | 1 line
logging: Updated SysLogHandler documentation.
........
r79876 | vinay.sajip | 2010-04-06 17:32:37 -0500 (Tue, 06 Apr 2010) | 1 line
Issue #8327: logging: Clarification of propagation functionality in documentation.
........
r79888 | vinay.sajip | 2010-04-07 04:40:52 -0500 (Wed, 07 Apr 2010) | 1 line
Issue #8331: logging: fixed some grammatical errors in documentation.
........
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index 6324806..32cad92 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -244,16 +244,16 @@
methods listed above, but this is how to log at custom log levels.
:func:`getLogger` returns a reference to a logger instance with the specified
-if it it is provided, or ``root`` if not. The names are period-separated
+if it is provided, or ``root`` if not. The names are period-separated
hierarchical structures. Multiple calls to :func:`getLogger` with the same name
will return a reference to the same logger object. Loggers that are further
down in the hierarchical list are children of loggers higher up in the list.
For example, given a logger with a name of ``foo``, loggers with names of
-``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all children of ``foo``.
-Child loggers propagate messages up to their parent loggers. Because of this,
-it is unnecessary to define and configure all the loggers an application uses.
-It is sufficient to configure a top-level logger and create child loggers as
-needed.
+``foo.bar``, ``foo.bar.baz``, and ``foo.bam`` are all descendants of ``foo``.
+Child loggers propagate messages up to the handlers associated with their
+ancestor loggers. Because of this, it is unnecessary to define and configure
+handlers for all the loggers an application uses. It is sufficient to
+configure handlers for a top-level logger and create child loggers as needed.
Handlers
@@ -281,15 +281,16 @@
are there two :func:`setLevel` methods? The level set in the logger
determines which severity of messages it will pass to its handlers. The level
set in each handler determines which messages that handler will send on.
- :func:`setFormatter` selects a Formatter object for this handler to use.
+
+* :func:`setFormatter` selects a Formatter object for this handler to use.
* :func:`addFilter` and :func:`removeFilter` respectively configure and
deconfigure filter objects on handlers.
-Application code should not directly instantiate and use handlers. Instead, the
-:class:`Handler` class is a base class that defines the interface that all
-Handlers should have and establishes some default behavior that child classes
-can use (or override).
+Application code should not directly instantiate and use instances of
+:class:`Handler`. Instead, the :class:`Handler` class is a base class that
+defines the interface that all handlers should have and establishes some
+default behavior that child classes can use (or override).
Formatters
@@ -521,7 +522,9 @@
can have zero, one or more handlers associated with it (via the
:meth:`addHandler` method of :class:`Logger`). In addition to any handlers
directly associated with a logger, *all handlers associated with all ancestors
-of the logger* are called to dispatch the message.
+of the logger* are called to dispatch the message (unless the *propagate* flag
+for a logger is set to a false value, at which point the passing to ancestor
+handlers stops).
Just as for loggers, handlers can have levels associated with them. A handler's
level acts as a filter in the same way as a logger's level does. If a handler
@@ -849,8 +852,8 @@
.. attribute:: Logger.propagate
If this evaluates to false, logging messages are not passed by this logger or by
- child loggers to higher level (ancestor) loggers. The constructor sets this
- attribute to 1.
+ its child loggers to the handlers of higher level (ancestor) loggers. The
+ constructor sets this attribute to 1.
.. method:: Logger.setLevel(lvl)
@@ -889,6 +892,16 @@
:const:`NOTSET` is found, and that value is returned.
+.. method:: Logger.getChild(suffix)
+
+ Returns a logger which is a descendant to this logger, as determined by the suffix.
+ Thus, ``logging.getLogger('abc').getChild('def.ghi')`` would return the same
+ logger as would be returned by ``logging.getLogger('abc.def.ghi')``. This is a
+ convenience method, useful when the parent logger is named using e.g. ``__name__``
+ rather than a literal string.
+
+ .. versionadded:: 3.2
+
.. method:: Logger.debug(msg, *args, **kwargs)
Logs a message with level :const:`DEBUG` on this logger. The *msg* is the
@@ -2012,8 +2025,11 @@
or integers - if strings are passed, internal mapping dictionaries are
used to convert them to integers.
- **Priorities**
+ The symbolic ``LOG_`` values are defined in :class:`SysLogHandler` and
+ mirror the values defined in the ``sys/syslog.h`` header file.
+ +------------------------------------------+
+ | Priorities |
+--------------------------+---------------+
| Name (string) | Symbolic value|
+==========================+===============+
@@ -2034,8 +2050,8 @@
| ``warn`` or ``warning`` | LOG_WARNING |
+--------------------------+---------------+
- **Facilities**
-
+ +-------------------------------+
+ | Facilities |
+---------------+---------------+
| Name (string) | Symbolic value|
+===============+===============+
@@ -2481,6 +2497,11 @@
methods have the same signatures as their counterparts in :class:`Logger`, so
you can use the two types of instances interchangeably.
+.. versionchanged:: 2.7
+
+The :meth:`isEnabledFor` method was added to :class:`LoggerAdapter`. This method
+delegates to the underlying logger.
+
Thread Safety
-------------