logging: Documented usage of callables as filters.

2 files changed, 16 insertions, 12 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
 ^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Lib/logging/__init__.py b/Lib/logging/__init__.py
index 551d85e..03ceb9c 100644
--- a/Lib/logging/__init__.py
+++ b/Lib/logging/__init__.py
@@ -613,13 +613,8 @@ class Filterer(object):
         for f in self.filters:
             if hasattr(f, 'filter'):
                 result = f.filter(record)
-            elif hasattr(f, '__call__'):
-                try:
-                    result = f(record)
-                except Exception:
-                    result = True # filter failed, assume a pass
             else:
-                result = False # we don't know what f is
+                result = f(record) # assume callable - will raise if not
             if not result:
                 rv = 0
                 break