[Terry Reedy
... It is, in the section on how to understand and use value comparison *operators* ('==', etc.). https://docs.python.org/3/reference/expressions.html#value-comparisons
First "The default behavior for equality comparison (== and !=) is based on the identity of the objects."
Then in particular, "The built-in containers typically assume identical objects are equal to themselves. That lets them bypass equality tests for identical objects to improve performance and to maintain their internal invariants."
Cool! I didn't find that, and I assume Victor didn't either. It's good! I think it needs more words, though, to flesh out what about this is allowed by the language (as opposed to what CPython happens to do), and to get closer to what Guido is trying to get at with his "*implicit* calls". For example, it's at work here, but there's not a built-in container in sight:
import math def f(): ... while True: ... yield math.nan math.nan in f() True
For example, in __eq__() method documentation: https://docs.python.org/dev/reference/datamodel.html#object.__eq
The text that follows discusses rich comparison *special methods* and how to write them. It should refer people to the value-comparisons section for information on specific classes, as in the second quote above. It would not hurt if the operator section referred people back to special method discussion. I think you should go ahead and add one or both links.
Agreed. If I want to know why my __eq__ (or __ne__) isn't being called, it's __eq__/__ne__ docs I'm going to look at first. And probably last, unless I'm nudged in the right direction.