logging: Documented usage of callables as filters.

1 files changed, 15 insertions, 6 deletions

diff --git a/Doc/library/logging.rst b/Doc/library/logging.rst
index e675bc1..d42f7d7 100644
--- a/Doc/library/logging.rst
+++ b/Doc/library/logging.rst
@@ -3040,12 +3040,12 @@ Currently, the useful mapping keys in a :class:`LogRecord` are:
 Filter Objects
 --------------
 
-: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
-"A.B", "A.B.C", "A.B.C.D", "A.B.D" etc. but not "A.BB", "B.A.B" etc. If
-initialized with the empty string, all events are passed.
+``Filters` can be used by ``Handlers`` and ``Loggers`` 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 "A.B", "A.B.C",
+"A.B.C.D", "A.B.D" etc. but not "A.BB", "B.A.B" etc. If initialized with the
+empty string, all events are passed.
 
 
 .. class:: Filter(name='')
@@ -3068,6 +3068,15 @@ 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.
 
+.. versionchanged:: 3.2
+
+You don't need to create specialized ``Filter`` classes: you can use a plain
+function (or other callable) as a filter. The filtering logic will check to
+see if the filter object has a ``filter`` attribute: if it does, it's assumed
+to be a ``Filter`` and its :meth:`~Filter.filter` method is called. Otherwise,
+it's assumed to be a callable and called with the record as the single
+parameter. The result should conform to that of :meth:`~Filter.filter`.
+
 Other uses for filters
 ^^^^^^^^^^^^^^^^^^^^^^