mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-15 06:10:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 12

Issue #8327: logging: Clarification of propagation functionality in documentation.

Browse source
This commit is contained in:
Vinay Sajip 2010-04-06 22:32:37 +00:00
parent ad971d62ee
commit ccd8bc8a83
1 changed files with 16 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

29
Doc/library/logging.rst
View file

@ -251,11 +251,11 @@ 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
@ -283,15 +283,16 @@ custom handlers) are the following configuration methods:
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
@ -523,7 +524,9 @@ support desk staff, system administrators, developers). Handlers are passed
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
@ -854,8 +857,8 @@ instantiated directly, but always through the module-level function
.. 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)