classification
Title: Documentation for logging.Filter.filter reports the wrong return type
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.10, Python 3.9, Python 3.8
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Riccardo Coccioli, docs@python, miss-islington, soulmerge, vinay.sajip
Priority: normal Keywords: patch

Created on 2020-10-12 09:00 by Riccardo Coccioli, last changed 2020-10-16 17:22 by vinay.sajip. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 22692 merged soulmerge, 2020-10-14 08:02
PR 22724 merged miss-islington, 2020-10-16 16:46
PR 22725 merged miss-islington, 2020-10-16 16:46
Messages (5)
msg378480 - (view) Author: Riccardo Coccioli (Riccardo Coccioli) * Date: 2020-10-12 09:00
The documentation for the logging.Filter().filter() method states:

#-----
Is the specified record to be logged? Returns 0 for no, nonzero for yes. If deemed appropriate, the record may be modified in-place.
#-----

While its implementation returns a boolean in Lib/logging/__init__.py.
Moreover the most recent version of mypy (0.790) reports it as an error if a custom class inherit from logging.Filter and implement a filter() method that returns an int as specified in the documentation:

#-----
error: Return type "int" of "filter" incompatible with return type "bool" in supertype "Filter"  [override]
#-----

P.S. As a side note, the API for filter() is quite counter-intuitive as it requires the filter() method to return False to filter out the record and True to include it.
msg378501 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2020-10-12 14:47
I agree that the documentation now should use Booleans rather than ints for the return type. It's a hangover from the pre-bool days of Python 1.5.2 ...

> P.S. As a side note, the API for filter() is quite counter-intuitive

That depends on if you consider the "filter" operation as "filter in" or "filter out", but the documentation is clear on what needs to be returned for a particular outcome.
msg378716 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2020-10-16 14:14
New changeset e9959c71185d0850c84e3aba0301fbc238f194a9 by Necdet Can Atesman in branch 'master':
bpo-42011: Update documentation of logging.Filter.filter() (GH-22692)
https://github.com/python/cpython/commit/e9959c71185d0850c84e3aba0301fbc238f194a9
msg378722 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2020-10-16 17:20
New changeset 8f7eab788aedcf1a23ef9be767e1b3502a6bbd5c by Miss Skeleton (bot) in branch '3.8':
bpo-42011: Update documentation of logging.Filter.filter() (GH-22692) (GH-22724)
https://github.com/python/cpython/commit/8f7eab788aedcf1a23ef9be767e1b3502a6bbd5c
msg378723 - (view) Author: Vinay Sajip (vinay.sajip) * (Python committer) Date: 2020-10-16 17:21
New changeset dff9161821032acfd2588d42d88511ebdbabaaf3 by Miss Skeleton (bot) in branch '3.9':
bpo-42011: Update documentation of logging.Filter.filter() (GH-22692) (GH-22725)
https://github.com/python/cpython/commit/dff9161821032acfd2588d42d88511ebdbabaaf3
History
Date User Action Args
2020-10-16 17:22:48vinay.sajipsetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2020-10-16 17:21:56vinay.sajipsetmessages: + msg378723
2020-10-16 17:20:37vinay.sajipsetmessages: + msg378722
2020-10-16 16:46:57miss-islingtonsetpull_requests: + pull_request21691
2020-10-16 16:46:49miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request21690
2020-10-16 14:14:25vinay.sajipsetmessages: + msg378716
2020-10-14 08:02:53soulmergesetkeywords: + patch
nosy: + soulmerge

pull_requests: + pull_request21663
stage: patch review
2020-10-12 14:47:54vinay.sajipsetversions: - Python 3.5, Python 3.6, Python 3.7
2020-10-12 14:47:14vinay.sajipsetmessages: + msg378501
2020-10-12 13:03:07xtreaksetnosy: + vinay.sajip
2020-10-12 09:00:43Riccardo Cocciolicreate