summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorVinay Sajip <vinay_sajip@yahoo.co.uk>2013-01-21 19:45:27 (GMT)
committerVinay Sajip <vinay_sajip@yahoo.co.uk>2013-01-21 19:45:27 (GMT)
commitf29839e8e81e7e3b7434f7855045ccc40d15c123 (patch)
treee6bf161044e3ee81f60fa575c6ab94885f86565f
parent529230142ffec0f41fec79226a7d7784cbda3eaf (diff)
parent6c4c16cdb8799c6449b4c4854be11e2458b9797c (diff)
downloadcpython-f29839e8e81e7e3b7434f7855045ccc40d15c123.zip
cpython-f29839e8e81e7e3b7434f7855045ccc40d15c123.tar.gz
cpython-f29839e8e81e7e3b7434f7855045ccc40d15c123.tar.bz2
Issue #17007: Merged doc update from 3.2.
-rw-r--r--Doc/library/logging.rst41
1 files changed, 29 insertions, 12 deletions
diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index c7ef311..dc8662b 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -70,16 +70,25 @@ is the module's name in the Python package namespace.
.. attribute:: Logger.propagate
- If this evaluates to true, logging messages are passed by this logger and by
- its child loggers to the handlers of higher level (ancestor) loggers.
- Messages are passed directly to the ancestor loggers' handlers - neither the
- level nor filters of the ancestor loggers in question are considered.
+ If this evaluates to true, events logged to this logger will be passed to the
+ handlers of higher level (ancestor) loggers, in addition to any handlers
+ attached to this logger. Messages are passed directly to the ancestor
+ loggers' handlers - neither the level nor filters of the ancestor loggers in
+ question are considered.
If this evaluates to false, logging messages are not passed to the handlers
of ancestor loggers.
The constructor sets this attribute to ``True``.
+ .. note:: If you attach a handler to several loggers, it may emit the same
+ record multiple times. In general, you should not need to attach a
+ handler to more than one logger - if you just attach it to the
+ appropriate logger which is highest in the logger hierarchy, then it
+ will see all events logged by all descendant loggers, provided that
+ their propagate setting is left set to ``True``. A common scenario is to
+ attach handlers only to the root logger, and let propagation take care of
+ the rest.
.. method:: Logger.setLevel(lvl)
@@ -255,7 +264,10 @@ is the module's name in the Python package namespace.
.. method:: Logger.filter(record)
Applies this logger's filters to the record and returns a true value if the
- record is to be processed.
+ record is to be processed. The filters are consulted in turn, until one of
+ them returns a false value. If none of them return a false value, the record
+ will be processed (passed to handlers). If one returns a false value, no
+ further processing of the record occurs.
.. method:: Logger.addHandler(hdlr)
@@ -364,7 +376,10 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
.. method:: Handler.filter(record)
Applies this handler's filters to the record and returns a true value if the
- record is to be processed.
+ record is to be processed. The filters are consulted in turn, until one of
+ them returns a false value. If none of them return a false value, the record
+ will be emitted. If one returns a false value, the handler will not emit the
+ record.
.. method:: Handler.flush()
@@ -547,12 +562,12 @@ empty string, all events are passed.
yes. If deemed appropriate, the record may be modified in-place by this
method.
-Note that filters attached to handlers are consulted whenever an event is
+Note that filters attached to handlers are consulted before an event is
emitted by the handler, whereas filters attached to loggers are consulted
-whenever an event is logged to the handler (using :meth:`debug`, :meth:`info`,
-etc.) This means that events which have been generated by descendant loggers
-will not be filtered by a logger's filter setting, unless the filter has also
-been applied to those descendant loggers.
+whenever an event is logged (using :meth:`debug`, :meth:`info`,
+etc.), before sending an event to handlers. This means that events which have
+been generated by descendant loggers will not be filtered by a logger's filter
+setting, unless the filter has also been applied to those descendant loggers.
You don't actually need to subclass ``Filter``: you can pass any instance
which has a ``filter`` method with the same semantics.
@@ -596,7 +611,9 @@ wire).
record.
:param name: The name of the logger used to log the event represented by
- this LogRecord.
+ this LogRecord. Note that this name will always have this
+ value, even though it may be emitted by a handler attached to
+ a different (ancestor) logger.
:param level: The numeric level of the logging event (one of DEBUG, INFO etc.)
Note that this is converted to *two* attributes of the LogRecord:
``levelno`` for the numeric value and ``levelname`` for the