diff options
| -rw-r--r-- | Doc/library/logging.rst | 41 |
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 |