This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: Language reference for expressions incorrectly specifies what type of object(s) are expected
Type: Stage: resolved
Components: Documentation Versions: Python 3.11, Python 3.10, Python 3.9
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: andrei.avk, brett.cannon, docs@python, lukasz.langa, miss-islington, terry.reedy
Priority: low Keywords: patch

Created on 2020-10-02 15:27 by brett.cannon, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 27470 merged andrei.avk, 2021-07-30 01:05
PR 27490 merged miss-islington, 2021-07-30 16:52
PR 27491 merged miss-islington, 2021-07-30 16:52
Messages (7)
msg377817 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2020-10-02 15:27 claims that "Comparisons yield boolean values: True or False." But that's not necessarily true:

>>> class Spam: 
...  def __eq__(self, _): return 42
>>> Spam() == object()

That really only happens when an expressions is used in a boolean context like an `if` statements guard expression.
msg377847 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2020-10-03 01:43
For rich comparisons, a proper explanation is given in the rich comparison entry in the datamodel section ( #41910) 

"A rich comparison method may return the singleton NotImplemented if it does not implement the operation for a given pair of arguments. By convention, False and True are returned for a successful comparison. However, these methods can return any value, so if the comparison operator is used in a Boolean context (e.g., in the condition of an if statement), Python will call bool() on the value to determine if the result is true or false."

bool(x) calls x.__bool__ and requires that the latter return False or True.

As for the other two comparisons, x is y always returns False or True for a proper implementation because int == int always does.  If y.__contains__(x) does not raise, x in y returns bool(y.__contains__(x)), clamping aberrant implementations of __contains__.

A replacement text might be 

"Comparisons normally yield boolean values: True or False.  But rich comparisons not in a Boolean context may yield anything."

Possibly link 'rich comparisons' to the datamodel section.
msg379259 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2020-10-21 21:56
It turns out the "expressions" page of the language reference makes multiple claims about types which do not hold, e.g. for multiplication, "The arguments must either both be numbers, or one argument must be an integer and the other must be a sequence", or for `&` that its arguments "must be integers".

So this is much larger than just comparison operators.
msg398525 - (view) Author: Andrei Kulakov (andrei.avk) * (Python triager) Date: 2021-07-30 01:07
I've put up a PR here:
msg398573 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-07-30 16:52
New changeset 4bd9caafb64589288e5171087070bde726178c58 by andrei kulakov in branch 'main':
bpo-41911: Update docs for various expressions (GH-27470)
msg398583 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-07-30 17:25
New changeset 843b3d28209b7754c51c6cc3844f66808b6dbdaf by Miss Islington (bot) in branch '3.10':
bpo-41911: Update docs for various expressions (GH-27470) (GH-27490)
msg398584 - (view) Author: Łukasz Langa (lukasz.langa) * (Python committer) Date: 2021-07-30 17:26
New changeset b57011d2a5375bc9f255361dc64c9e6fbc203e0e by Miss Islington (bot) in branch '3.9':
bpo-41911: Update docs for various expressions (GH-27470) (GH-27491)
Date User Action Args
2022-04-11 14:59:36adminsetgithub: 86077
2021-07-30 17:26:19lukasz.langasetstatus: open -> closed
stage: patch review -> resolved
resolution: fixed
versions: + Python 3.11, - Python 3.8
2021-07-30 17:26:04lukasz.langasetmessages: + msg398584
2021-07-30 17:25:53lukasz.langasetmessages: + msg398583
2021-07-30 16:52:58miss-islingtonsetpull_requests: + pull_request26007
2021-07-30 16:52:53miss-islingtonsetnosy: + miss-islington
pull_requests: + pull_request26006
2021-07-30 16:52:52lukasz.langasetnosy: + lukasz.langa
messages: + msg398573
2021-07-30 01:07:40andrei.avksetmessages: + msg398525
2021-07-30 01:05:58andrei.avksetkeywords: + patch
nosy: + andrei.avk

pull_requests: + pull_request25989
stage: patch review
2020-10-21 21:56:13brett.cannonsettitle: Language reference incorrectly says comparison expressions return boolean values -> Language reference for expressions incorrectly specifies what type of object(s) are expected
nosy: + docs@python

messages: + msg379259

assignee: brett.cannon -> docs@python
2020-10-03 01:43:58terry.reedysetnosy: + terry.reedy
messages: + msg377847
2020-10-02 15:27:33brett.cannoncreate