[Python-checkins] r84859 - in python/branches: py3k/Doc/library/logging.rst release27-maint/Doc/library/logging.rst

Fri Sep 17 14:45:26 CEST 2010

Author: vinay.sajip
Date: Fri Sep 17 14:45:26 2010
New Revision: 84859
Log:
Improved Filter documentation.
Modified:
 python/branches/py3k/Doc/library/logging.rst
 python/branches/release27-maint/Doc/library/logging.rst
Modified: python/branches/py3k/Doc/library/logging.rst
==============================================================================

--- python/branches/py3k/Doc/library/logging.rst	(original)
+++ python/branches/py3k/Doc/library/logging.rst	Fri Sep 17 14:45:26 2010
@@ -1465,6 +1465,8 @@
 2008年01月18日 14:49:54,033 d.e.f WARNING IP: 127.0.0.1 User: jim A message at WARNING level with 2 parameters
 
 
+.. _filters-contextual:
+
 Using Filters to impart contextual information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -2852,6 +2854,18 @@
 will not be filtered by a logger's filter setting, unless the filter has also
 been applied to those descendant loggers.
 
+Other uses for filters
+^^^^^^^^^^^^^^^^^^^^^^
+
+Although filters are used primarily to filter records based on more
+sophisticated criteria than levels, they get to see every record which is
+processed by the handler or logger they're attached to: this can be useful if
+you want to do things like counting how many records were processed by a
+particular logger or handler, or adding, changing or removing attributes in
+the LogRecord being processed. Obviously changing the LogRecord needs to be
+done with some care, but it does allow the injection of contextual information
+into logs (see :ref:`filters-contextual`).
+
 .. _log-record:
 
 LogRecord Objects
Modified: python/branches/release27-maint/Doc/library/logging.rst
==============================================================================
--- python/branches/release27-maint/Doc/library/logging.rst	(original)
+++ python/branches/release27-maint/Doc/library/logging.rst	Fri Sep 17 14:45:26 2010
@@ -1479,6 +1479,8 @@
 
 The :class:`LoggerAdapter` class was not present in previous versions.
 
+.. _filters-contextual:
+
 Using Filters to impart contextual information
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -2657,7 +2659,7 @@
 Filter Objects
 --------------
 
-Filters can be used by :class:`Handler`\ s and :class:`Logger`\ s for
+:class:`Filter`\ s can be used by :class:`Handler`\ s and :class:`Logger`\ s for
 more sophisticated filtering than is provided by levels. The base filter class
 only allows events which are below a certain point in the logger hierarchy. For
 example, a filter initialized with "A.B" will allow events logged by loggers
@@ -2685,6 +2687,18 @@
 will not be filtered by a logger's filter setting, unless the filter has also
 been applied to those descendant loggers.
 
+Other uses for filters
+^^^^^^^^^^^^^^^^^^^^^^
+
+Although filters are used primarily to filter records based on more
+sophisticated criteria than levels, they get to see every record which is
+processed by the handler or logger they're attached to: this can be useful if
+you want to do things like counting how many records were processed by a
+particular logger or handler, or adding, changing or removing attributes in
+the LogRecord being processed. Obviously changing the LogRecord needs to be
+done with some care, but it does allow the injection of contextual information
+into logs (see :ref:`filters-contextual`).
+
 .. _log-record:
 
 LogRecord Objects
