Issue 22000: cross type comparisons clarification (original) (raw)

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). """

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.