filter docs unclear wording

[unfamiliarplace]

BPO	26847
Nosy	@birkenfeld, @MojoVampire, @unfamiliarplace

^{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 2016-04-26.05:44:46.418>
created_at = <Date 2016-04-26.03:15:40.527>
labels = ['type-feature', 'invalid', 'docs']
title = 'filter docs unclear wording'
updated_at = <Date 2016-04-26.13:06:41.943>
user = 'https://github.com/unfamiliarplace'

bugs.python.org fields:

activity = <Date 2016-04-26.13:06:41.943>
actor = 'unfamiliarplace'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-04-26.05:44:46.418>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2016-04-26.03:15:40.527>
creator = 'unfamiliarplace'
dependencies = []
files = []
hgrepos = []
issue_num = 26847
keywords = []
message_count = 6.0
messages = ['264206', '264207', '264208', '264209', '264216', '264275']
nosy_count = 4.0
nosy_names = ['georg.brandl', 'docs@python', 'josh.r', 'unfamiliarplace']
pr_nums = []
priority = 'normal'
resolution = 'not a bug'
stage = None
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue26847'
versions = ['Python 3.5']

[unfamiliarplace]

The current docs for both filter and itertools.filterfalse use the following wording (emphasis added):

all elements that are false are removed
returns the items that are false
This could be confusing for a new Python programmer, because the actual behaviour is that elements are equality-compared, not identity-compared.

Suggested wording: "are equal to False"

https://docs.python.org/3.5/library/functions.html#filter
https://docs.python.org/3.5/library/itertools.html#itertools.filterfalse

[MojoVampire]

"are equal to False" would be wrong though. Any "falsy" value is preserved by filterfalse, and removed by filter. They need not be equal to False (the bool singleton); empty containers (e.g. (), [], {}, "") are all considered false, and behave as such, despite not being equal to False.

[MojoVampire]

That's why lower case "false" is used, not "False"; the former is the loose definition, the latter is the strict singleton.

[unfamiliarplace]

josh, we're saying the same thing but misunderstanding each other. :)

I realize that they can be empty containers, etc., and that's why I think "equal to False" is appropriate -- because those things *are* equal to False:

>>> [] == False
True
>>> 0 == False
True
etc.

However, they are not identical to False:

>>> [] is False
False
>>> 0 is False
False

And that's why I think the wording "are false" is potentially misleading.

Perhaps there's a better wording than "equal to False" (compares equivalently to False? or simply: are falsey? :p), but anyhow, we're identifying the same behaviour here.

[birkenfeld]

You didn't test your examples:

>>> [] == False
False

False is not equal to the "empty value" of any other type than other numeric types. (This is mostly because of how booleans were originally introduced to Python.)

"is false", on the other hand, is the conventional shorthand for bool(x) == False.

[unfamiliarplace]

For shame! ... I deserved that callout. :S

My examples should have included the cast to bool, which is indeed not the same as the values' being "equal to False" in themselves...

I didn't realize that "is false" was conventional shorthand for that cast and comparison. Thanks!