docstring of filter function is incorrect

[Pierre-Thibault]

BPO	33006
Nosy	@rhettinger, @ncoghlan, @ned-deily, @TonyFlury, @miss-islington, @Pierre-Thibault
PRs	[2.7] bpo-33006 - Correct filter doc string to clarify 2nd argument can be iterable #6015

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2019-05-29.02:04:01.836>
created_at = <Date 2018-03-06.01:36:31.261>
labels = ['docs']
title = 'docstring of filter function is incorrect'
updated_at = <Date 2019-05-29.02:04:01.836>
user = 'https://github.com/Pierre-Thibault'

bugs.python.org fields:

activity = <Date 2019-05-29.02:04:01.836>
actor = 'ned.deily'
assignee = 'docs@python'
closed = True
closed_date = <Date 2019-05-29.02:04:01.836>
closer = 'ned.deily'
components = ['Documentation']
creation = <Date 2018-03-06.01:36:31.261>
creator = 'Pierre Thibault'
dependencies = []
files = []
hgrepos = []
issue_num = 33006
keywords = ['patch']
message_count = 5.0
messages = ['313302', '315972', '315974', '343849', '343852']
nosy_count = 7.0
nosy_names = ['rhettinger', 'ncoghlan', 'ned.deily', 'docs@python', 'anthony-flury', 'miss-islington', 'Pierre Thibault']
pr_nums = ['6015']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue33006'
versions = ['Python 2.7']

[Pierre-Thibault]

help(filter)

Help on built-in function filter in module __builtin__:

filter(...)
    filter(function or None, sequence) -> list, tuple, or string

Return those items of sequence for which function(item) is true.  If
function is None, return the items that are true.  If sequence is a tuple
or string, return the same type, else return a list.

(END)

The second argument can be an iterable. Suggestion: Replace the docstring with the definition found at https://docs.python.org/2/library/functions.html#filter.

[TonyFlury]

Strictly speaking the official Python2 reference document isn't a great example - for instance:

' If function is None, the identity function is assumed, that is, all elements of iterable that are false are removed.'

Implies that items are removed from the iterable are removed, but they aren't; they are simply not included in the sequence that is returned.

Does the documentation need to be fixed too ?

[Pierre-Thibault]

I guess it does since it gives false information.

2018-04-30 18:05 GMT-04:00 Anthony Flury <report@bugs.python.org>:

Anthony Flury <anthony.flury@btinternet.com> added the comment:

Strictly speaking the official Python2 reference document isn't a great
example - for instance:

' If function is None, the identity function is assumed, that is, all
elements of iterable that are false are removed.'

Implies that items are removed from the iterable are removed, but they
aren't; they are simply not included in the sequence that is returned.

Does the documentation need to be fixed too ?

----------
nosy: +anthony-flury

---

Python tracker <report@bugs.python.org>
<https://bugs.python.org/issue33006\>

---

[miss-islington]

New changeset 09ba833 by Miss Islington (bot) (Tony Flury) in branch '2.7':
[2.7] bpo-33006 - Correct filter doc string to clarify 2nd argument can be iterable (GH-6015)
09ba833

[ned-deily]

Thanks for the docstring improvement! It looks like the Library Reference entry for filter has similar wording in 3.x and 2.7 with regard to "items are removed". If soneone feels strongly that that is not precise enough, suggest supplying a separate doc PR.