mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-26 18:29:57 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Issue #17007: Merged doc update from 3.2.

Browse source
This commit is contained in:
Vinay Sajip 2013-01-21 19:45:27 +00:00
commit f29839e8e8
1 changed files with 29 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

41
Doc/library/logging.rst
View file

@ -70,16 +70,25 @@ is the module's name in the Python package namespace.
.. attribute:: Logger.propagate .. attribute:: Logger.propagate
If this evaluates to true, logging messages are passed by this logger and by If this evaluates to true, events logged to this logger will be passed to the
its child loggers to the handlers of higher level (ancestor) loggers. handlers of higher level (ancestor) loggers, in addition to any handlers
Messages are passed directly to the ancestor loggers' handlers - neither the attached to this logger. Messages are passed directly to the ancestor
level nor filters of the ancestor loggers in question are considered. 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 If this evaluates to false, logging messages are not passed to the handlers
of ancestor loggers. of ancestor loggers.
The constructor sets this attribute to ``True``. 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) .. method:: Logger.setLevel(lvl)
@ -255,7 +264,10 @@ is the module's name in the Python package namespace.
.. method:: Logger.filter(record) .. method:: Logger.filter(record)
Applies this logger's filters to the record and returns a true value if the 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) .. method:: Logger.addHandler(hdlr)
@ -364,7 +376,10 @@ subclasses. However, the :meth:`__init__` method in subclasses needs to call
.. method:: Handler.filter(record) .. method:: Handler.filter(record)
Applies this handler's filters to the record and returns a true value if the 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() .. 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 yes. If deemed appropriate, the record may be modified in-place by this
method. 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 emitted by the handler, whereas filters attached to loggers are consulted
whenever an event is logged to the handler (using :meth:`debug`, :meth:`info`, whenever an event is logged (using :meth:`debug`, :meth:`info`,
etc.) This means that events which have been generated by descendant loggers etc.), before sending an event to handlers. This means that events which have
will not be filtered by a logger's filter setting, unless the filter has also been generated by descendant loggers will not be filtered by a logger's filter
been applied to those descendant loggers. 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 You don't actually need to subclass ``Filter``: you can pass any instance
which has a ``filter`` method with the same semantics. which has a ``filter`` method with the same semantics.
@ -596,7 +611,9 @@ wire).
record. record.
:param name: The name of the logger used to log the event represented by :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.) :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: Note that this is converted to *two* attributes of the LogRecord:
``levelno`` for the numeric value and ``levelname`` for the ``levelno`` for the numeric value and ``levelname`` for the