classification
Title: cross type comparisons clarification
Type: behavior Stage: needs patch
Components: Documentation Versions: Python 3.5
process
Status: open Resolution:
Dependencies: 12067 Superseder:
Assigned To: docs@python Nosy List: Jim.Jewett, docs@python, ezio.melotti, martin.panter, r.david.murray, rhettinger
Priority: normal Keywords:

Created on 2014-07-17 18:38 by Jim.Jewett, last changed 2015-07-24 01:38 by rhettinger.

Messages (5)
msg223353 - (view) Author: Jim Jewett (Jim.Jewett) (Python triager) Date: 2014-07-17 18:38
https://docs.python.org/3.5/library/stdtypes.html
says "Objects of different types, except different numeric types, never compare equal."  

Despite the location, this seems to strong a statement, because of subclasses and classes which define __eq__.

A first attempt at rewording:

Existing: """
Objects of different types, except different numeric types, never compare equal. Furthermore, some types (for example, function objects) support only a degenerate notion of comparison where any two objects of that type are unequal. The <, <=, > and >= operators will raise a TypeError exception when comparing a complex number with another built-in numeric type, when the objects are of different types that cannot be compared, or in other cases where there is no defined ordering.

Non-identical instances of a class normally compare as non-equal unless the class defines the __eq__() method.

Instances of a class cannot be ordered with respect to other instances of the same class, or other types of object, unless the class defines enough of the methods __lt__(), __le__(), __gt__(), and __ge__() (in general, __lt__() and __eq__() are sufficient, if you want the conventional meanings of the comparison operators).

The behavior of the is and is not operators cannot be customized; also they can be applied to any two objects and never raise an exception.

Two more operations with the same syntactic priority, in and not in, are supported only by sequence types (below).
"""

-->

"""
The is and is not operators can be applied to any pair of objects, and will never raise an exception.  They cannot be customized, as they refer to implementation details.  (For example, "abc" is "abc" may or may not be true.)

Other comparisons refer to an object's meaning, and therefore must be defined by the object's own class.  "abc" == "abc" is always True, because the str class defines equality that way.

The default implementation uses is (object identity) for equality and  raises a TypeError for the ordering comparisons.  Defining the __eq__ method allows different instances to be equivalent; also defining the __lt__ method allows them to be ordered in the normal way.  Some classes will also define __le__, __ne__, __ge__, and __gt__, either for efficiency or to provide unusual behavior.  

Except for numbers, instances of two different standard classes will be unequal, and will raise a TypeError when compared for ordering.

Two more operations with the same syntactic priority, in and not in, are supported only by sequence types (below).
"""
msg223513 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2014-07-20 15:27
'type' and 'class' are two different names for the same concept in python3, so this paragraph simply appears to be out of date and indeed in need of complete rewording.
msg236252 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-02-20 05:54
I think the patch for Issue 12067 covers all of the suggested points here, and is more accurate in some cases.
msg247083 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-07-22 03:31
Actually, this is about a different section of the documentation. But it might still be best to update /Doc/reference/expressions.rst first in Issue 12067, and then sort out /Doc/library/stdtypes.rst to match.

Why do we need a dedicated section in Built-in Types about Comparisons? I think it might make more sense to just document how comparisons work separately for each type (Numeric, Sequence, Text, etc), if this is not already done.
msg247238 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-07-24 01:38
> Why do we need a dedicated section in Built-in Types about Comparisons?

It is nice to have some of that information collected together.  I think people learn about comparison logic as a single topic rather than piecemeal type by type.

To Jim's point, the discussion of "is" and "is not" should probably be factored-out (their meaning is type-invariant and is not overridable with a dunder method).  Also, they don't have the same reflective logic as the rich comparisons.
History
Date User Action Args
2015-07-24 01:38:53rhettingersetnosy: + rhettinger
messages: + msg247238
2015-07-22 03:31:44martin.pantersetdependencies: + Doc: remove errors about mixed-type comparisons.
messages: + msg247083
2015-02-20 05:54:06martin.pantersetnosy: + martin.panter
messages: + msg236252
2014-08-05 05:32:18ezio.melottisetnosy: + ezio.melotti

stage: needs patch
2014-07-20 15:27:11r.david.murraysetnosy: + r.david.murray
messages: + msg223513
2014-07-17 18:38:32Jim.Jewettcreate