New submission from Jim Jewett: https://docs.python.org/3.5/reference/expressions.html#not-in Containers are permitted to (and generally do) read "same as" as "is or __eq__), which can be confusing -- particularly in the section defining __eq__. Several suggested changes: """ The values float('NaN') and Decimal('NaN') are special. The are identical to themselves, x is x but are not equal to themselves, x != x. Additionally, comparing any value to a not-a-number value will return False. For example, both 3 < float('NaN') and float('NaN') < 3 will return False. """ --> ("the" -> "they"; add a comma; add a final sentence) --> """ The values float('NaN') and Decimal('NaN') are special. They are identical to themselves, x is x, but are not equal to themselves, x != x. Additionally, comparing any value to a not-a-number value will return False. For example, both 3 < float('NaN') and float('NaN') < 3 will return False. Note, however, that containers will normally implement item equality as "a is b or a==b", so that [f]==[f] and f in [f] may be true even when f!=f. """ also: """ Tuples and lists are compared lexicographically using comparison of corresponding elements. This means that to compare equal, each element must compare equal and the two sequences must be of the same type and have the same length. """ --> (re-order; add the NaN workaround) --> """ Tuples and lists are compared lexicographically using comparison of corresponding elements. This means that to compare equal, two sequences must be of the same type and have the same length, and each pair of corresponding elements must be identical or compare equal. (Sequences can assume that identical elements are equal, despite odd cases like float('NaN').) """ I *think* it is OK to leave that caveat out of the mapping case, because "have the same (key, value) pairs" would now refer to the above. ---------- assignee: docs@python components: Documentation messages: 223362 nosy: Jim.Jewett, docs@python priority: normal severity: normal status: open title: containers "same" does not always mean "__eq__". type: enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue22001> _______________________________________