logging: Documented usage of callables as filters.
This commit is contained in:
parent
435d306aa9
commit
fc082cafa6
|
@ -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
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
Loading…
Reference in New Issue