[issue26847] filter docs unclear wording
New submission from Luke: 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 ---------- assignee: docs@python components: Documentation messages: 264206 nosy: docs@python, unfamiliarplace priority: normal severity: normal status: open title: filter docs unclear wording type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26847> _______________________________________
Josh Rosenberg added the comment: "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. ---------- nosy: +josh.r _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26847> _______________________________________
Josh Rosenberg added the comment: That's why lower case "false" is used, not "False"; the former is the loose definition, the latter is the strict singleton. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26847> _______________________________________
Luke added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26847> _______________________________________
Georg Brandl added the comment: 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`. ---------- nosy: +georg.brandl resolution: -> not a bug status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26847> _______________________________________
Luke added the comment: 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! ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue26847> _______________________________________
participants (3)
-
Georg Brandl -
Josh Rosenberg
-
Luke