diff options
| -rw-r--r-- | Doc/glossary.rst | 4 | ||||
| -rw-r--r-- | Doc/library/decimal.rst | 17 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 15 | ||||
| -rw-r--r-- | Doc/library/xmlrpc.client.rst | 6 | ||||
| -rw-r--r-- | Doc/reference/datamodel.rst | 70 |
5 files changed, 44 insertions, 68 deletions
diff --git a/Doc/glossary.rst b/Doc/glossary.rst index 1adf779..c789ae5 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -246,8 +246,8 @@ Glossary hashable An object is *hashable* if it has a hash value which never changes during its lifetime (it needs a :meth:`__hash__` method), and can be compared to - other objects (it needs an :meth:`__eq__` or :meth:`__cmp__` method). - Hashable objects which compare equal must have the same hash value. + other objects (it needs an :meth:`__eq__` method). Hashable objects which + compare equal must have the same hash value. Hashability makes an object usable as a dictionary key and a set member, because these data structures use the hash value internally. diff --git a/Doc/library/decimal.rst b/Doc/library/decimal.rst index d24cddf..ad8b65c 100644 --- a/Doc/library/decimal.rst +++ b/Doc/library/decimal.rst @@ -375,15 +375,14 @@ Decimal objects .. method:: compare(other[, context]) - Compare the values of two Decimal instances. This operation behaves in - the same way as the usual comparison method :meth:`__cmp__`, except that - :meth:`compare` returns a Decimal instance rather than an integer, and if - either operand is a NaN then the result is a NaN:: - - a or b is a NaN ==> Decimal('NaN') - a < b ==> Decimal('-1') - a == b ==> Decimal('0') - a > b ==> Decimal('1') + Compare the values of two Decimal instances. :meth:`compare` returns a + Decimal instance, and if either operand is a NaN then the result is a + NaN:: + + a or b is a NaN ==> Decimal('NaN') + a < b ==> Decimal('-1') + a == b ==> Decimal('0') + a > b ==> Decimal('1') .. method:: compare_signal(other[, context]) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 5ed5609..04dd888 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -173,7 +173,6 @@ any operand is a complex number, the objects are of different types that cannot be compared, or other cases where there is no defined ordering. .. index:: - single: __cmp__() (instance method) single: __eq__() (instance method) single: __ne__() (instance method) single: __lt__() (instance method) @@ -181,15 +180,14 @@ be compared, or other cases where there is no defined ordering. single: __gt__() (instance method) single: __ge__() (instance method) -Instances of a class normally compare as non-equal unless the class defines the -:meth:`__eq__` or :meth:`__cmp__` method. +Non-identical instances of a class normally compare as non-equal unless the +class defines the :meth:`__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 :meth:`__cmp__`, :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and -:meth:`__ge__` (in general, either :meth:`__cmp__` or both :meth:`__lt__` and -:meth:`__eq__` are sufficient, if you want the conventional meanings of the -comparison operators). +methods :meth:`__lt__`, :meth:`__le__`, :meth:`__gt__`, and :meth:`__ge__` (in +general, :meth:`__lt__` and :meth:`__eq__` are sufficient, if you want the +conventional meanings of the comparison operators). The behavior of the :keyword:`is` and :keyword:`is not` operators cannot be customized; also they can be applied to any two objects and never raise an @@ -1642,8 +1640,7 @@ The constructors for both classes work the same: The subset and equality comparisons do not generalize to a complete ordering function. For example, any two disjoint sets are not equal and are not subsets of each other, so *all* of the following return ``False``: ``a<b``, - ``a==b``, or ``a>b``. Accordingly, sets do not implement the :meth:`__cmp__` - method. + ``a==b``, or ``a>b``. Since sets only define partial ordering (subset relationships), the output of the :meth:`list.sort` method is undefined for lists of sets. diff --git a/Doc/library/xmlrpc.client.rst b/Doc/library/xmlrpc.client.rst index 1f18810..23bb650 100644 --- a/Doc/library/xmlrpc.client.rst +++ b/Doc/library/xmlrpc.client.rst @@ -210,7 +210,7 @@ use by the marshalling/unmarshalling code: Write the XML-RPC encoding of this :class:`DateTime` item to the *out* stream object. -It also supports certain of Python's built-in operators through :meth:`__cmp__` +It also supports certain of Python's built-in operators through rich comparison and :meth:`__repr__` methods. A working example follows. The server code:: @@ -273,8 +273,8 @@ internal use by the marshalling/unmarshalling code: which was the de facto standard base64 specification when the XML-RPC spec was written. -It also supports certain of Python's built-in operators through a -:meth:`__cmp__` method. +It also supports certain of Python's built-in operators through :meth:`__eq__` +and :meth:`__ne__` methods. Example usage of the binary objects. We're going to transfer an image over XMLRPC:: diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst index ddc605b..b154663 100644 --- a/Doc/reference/datamodel.rst +++ b/Doc/reference/datamodel.rst @@ -1168,8 +1168,7 @@ Basic customization .. index:: single: comparisons - These are the so-called "rich comparison" methods, and are called for comparison - operators in preference to :meth:`__cmp__` below. The correspondence between + These are the so-called "rich comparison" methods. The correspondence between operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``, ``x<=y`` calls ``x.__le__(y)``, ``x==y`` calls ``x.__eq__(y)``, ``x!=y`` calls ``x.__ne__(y)``, ``x>y`` calls ``x.__gt__(y)``, and ``x>=y`` calls @@ -1198,28 +1197,11 @@ Basic customization Arguments to rich comparison methods are never coerced. -.. method:: object.__cmp__(self, other) - - .. index:: - builtin: cmp - single: comparisons - - Called by comparison operations if rich comparison (see above) is not - defined. Should return a negative integer if ``self < other``, zero if - ``self == other``, a positive integer if ``self > other``. If no - :meth:`__cmp__`, :meth:`__eq__` or :meth:`__ne__` operation is defined, class - instances are compared by object identity ("address"). See also the - description of :meth:`__hash__` for some important notes on creating - :term:`hashable` objects which support custom comparison operations and are - usable as dictionary keys. - - .. method:: object.__hash__(self) .. index:: object: dictionary builtin: hash - single: __cmp__() (object method) Called for the key object for dictionary operations, and by the built-in function :func:`hash`. Should return an integer usable as a hash value @@ -1228,37 +1210,35 @@ Basic customization (e.g., using exclusive or) the hash values for the components of the object that also play a part in comparison of objects. - If a class does not define a :meth:`__cmp__` or :meth:`__eq__` method it - should not define a :meth:`__hash__` operation either; if it defines - :meth:`__cmp__` or :meth:`__eq__` but not :meth:`__hash__`, its instances - will not be usable as dictionary keys. If a class defines mutable objects - and implements a :meth:`__cmp__` or :meth:`__eq__` method, it should not - implement :meth:`__hash__`, since the dictionary implementation requires that - a key's hash value is immutable (if the object's hash value changes, it will - be in the wrong hash bucket). + If a class does not define an :meth:`__eq__` method it should not define a + :meth:`__hash__` operation either; if it defines :meth:`__eq__` but not + :meth:`__hash__`, its instances will not be usable as dictionary keys. If a + class defines mutable objects and implements an :meth:`__eq__` method, it + should not implement :meth:`__hash__`, since the dictionary implementation + requires that a key's hash value is immutable (if the object's hash value + changes, it will be in the wrong hash bucket). - User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods + User-defined classes have :meth:`__eq__` and :meth:`__hash__` methods by default; with them, all objects compare unequal (except with themselves) and ``x.__hash__()`` returns ``id(x)``. Classes which inherit a :meth:`__hash__` method from a parent class but - change the meaning of :meth:`__cmp__` or :meth:`__eq__` such that the hash - value returned is no longer appropriate (e.g. by switching to a value-based - concept of equality instead of the default identity based equality) can - explicitly flag themselves as being unhashable by setting - ``__hash__ = None`` in the class definition. Doing so means that not only - will instances of the class raise an appropriate :exc:`TypeError` when - a program attempts to retrieve their hash value, but they will also be - correctly identified as unhashable when checking - ``isinstance(obj, collections.Hashable)`` (unlike classes which define - their own :meth:`__hash__` to explicitly raise :exc:`TypeError`). - - If a class that overrrides :meth:`__cmp__` or :meth:`__eq__` needs to - retain the implementation of :meth:`__hash__` from a parent class, - the interpreter must be told this explicitly by setting - ``__hash__ = <ParentClass>.__hash__``. Otherwise the inheritance of - :meth:`__hash__` will be blocked, just as if :attr:`__hash__` had been - explicitly set to :const:`None`. + change the meaning of :meth:`__eq__` such that the hash value returned is no + longer appropriate (e.g. by switching to a value-based concept of equality + instead of the default identity based equality) can explicitly flag + themselves as being unhashable by setting ``__hash__ = None`` in the class + definition. Doing so means that not only will instances of the class raise an + appropriate :exc:`TypeError` when a program attempts to retrieve their hash + value, but they will also be correctly identified as unhashable when checking + ``isinstance(obj, collections.Hashable)`` (unlike classes which define their + own :meth:`__hash__` to explicitly raise :exc:`TypeError`). + + If a class that overrrides :meth:`__eq__` needs to retain the implementation + of :meth:`__hash__` from a parent class, the interpreter must be told this + explicitly by setting ``__hash__ = <ParentClass>.__hash__``. Otherwise the + inheritance of :meth:`__hash__` will be blocked, just as if :attr:`__hash__` + had been explicitly set to :const:`None`. + .. method:: object.__bool__(self) |