Merged revisions 58742-58816 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk
........
r58745 | georg.brandl | 2007-11-01 10:19:33 -0700 (Thu, 01 Nov 2007) | 2 lines
#1364: os.lstat is available on Windows too, as an alias to os.stat.
........
r58750 | christian.heimes | 2007-11-01 12:48:10 -0700 (Thu, 01 Nov 2007) | 1 line
Backport of import tests for bug http://bugs.python.org/issue1293 and bug http://bugs.python.org/issue1342
........
r58751 | christian.heimes | 2007-11-01 13:11:06 -0700 (Thu, 01 Nov 2007) | 1 line
Removed non ASCII text from test as requested by Guido. Sorry :/
........
r58753 | georg.brandl | 2007-11-01 13:37:02 -0700 (Thu, 01 Nov 2007) | 2 lines
Fix markup glitch.
........
r58757 | gregory.p.smith | 2007-11-01 14:08:14 -0700 (Thu, 01 Nov 2007) | 4 lines
Fix bug introduced in revision 58385. Database keys could no longer
have NULL bytes in them. Replace the errant strdup with a
malloc+memcpy. Adds a unit test for the correct behavior.
........
r58758 | gregory.p.smith | 2007-11-01 14:15:36 -0700 (Thu, 01 Nov 2007) | 3 lines
Undo revision 58533 58534 fixes. Those were a workaround for
a problem introduced by 58385.
........
r58759 | gregory.p.smith | 2007-11-01 14:17:47 -0700 (Thu, 01 Nov 2007) | 2 lines
false "fix" undone as correct problem was found and fixed.
........
r58765 | mark.summerfield | 2007-11-02 01:24:59 -0700 (Fri, 02 Nov 2007) | 3 lines
Added more file-handling related cross-references.
........
r58766 | nick.coghlan | 2007-11-02 03:09:12 -0700 (Fri, 02 Nov 2007) | 1 line
Fix for bug 1705170 - contextmanager swallowing StopIteration (2.5 backport candidate)
........
r58784 | thomas.heller | 2007-11-02 12:10:24 -0700 (Fri, 02 Nov 2007) | 4 lines
Issue #1292: On alpha, arm, ppc, and s390 linux systems the
--with-system-ffi configure option defaults to "yes" because the
bundled libffi sources are too old.
........
r58785 | thomas.heller | 2007-11-02 12:11:23 -0700 (Fri, 02 Nov 2007) | 1 line
Enable the full ctypes c_longdouble tests again.
........
r58796 | georg.brandl | 2007-11-02 13:06:17 -0700 (Fri, 02 Nov 2007) | 4 lines
Make "hashable" a glossary entry and clarify docs on __cmp__, __eq__ and __hash__.
I hope the concept of hashability is better understandable now.
Thanks to Tim Hatch for pointing out the flaws here.
........
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 3ebc973..69ac9dc 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -388,9 +388,10 @@
Frozen sets
.. index:: object: frozenset
- These represent an immutable set. They are created by the built-in
- :func:`frozenset` constructor. As a frozenset is immutable and hashable, it can
- be used again as an element of another set, or as a dictionary key.
+ These represent an immutable set. They are created by the built-in
+ :func:`frozenset` constructor. As a frozenset is immutable and
+ :term:`hashable`, it can be used again as an element of another set, or as
+ a dictionary key.
.. % Set types
@@ -1242,6 +1243,9 @@
object.__gt__(self, other)
object.__ge__(self, other)
+ .. 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
operator symbols and method names is as follows: ``x<y`` calls ``x.__lt__(y)``,
@@ -1256,14 +1260,16 @@
context (e.g., in the condition of an ``if`` statement), Python will call
:func:`bool` on the value to determine if the result is true or false.
- There are no implied relationships among the comparison operators. The truth of
- ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when defining
- :meth:`__eq__`, one should also define :meth:`__ne__` so that the operators will
- behave as expected.
+ There are no implied relationships among the comparison operators. The truth
+ of ``x==y`` does not imply that ``x!=y`` is false. Accordingly, when
+ defining :meth:`__eq__`, one should also define :meth:`__ne__` so that the
+ operators will behave as expected. See the paragraph on :meth:`__hash__` for
+ some important notes on creating :term:`hashable` objects which support
+ custom comparison operations and are usable as dictionary keys.
- There are no reflected (swapped-argument) versions of these methods (to be used
- when the left argument does not support the operation but the right argument
- does); rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
+ There are no swapped-argument versions of these methods (to be used when the
+ left argument does not support the operation but the right argument does);
+ rather, :meth:`__lt__` and :meth:`__gt__` are each other's reflection,
:meth:`__le__` and :meth:`__ge__` are each other's reflection, and
:meth:`__eq__` and :meth:`__ne__` are their own reflection.
@@ -1276,14 +1282,15 @@
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 objects which support custom comparison operations
- and are usable as dictionary keys. (Note: the restriction that exceptions are
- not propagated by :meth:`__cmp__` has been removed since Python 1.5.)
+ 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. (Note: the restriction that exceptions are not
+ propagated by :meth:`__cmp__` has been removed since Python 1.5.)
.. method:: object.__hash__(self)
@@ -1293,19 +1300,12 @@
builtin: hash
single: __cmp__() (object method)
- Called for the key object for dictionary operations, and by the built-in
- function :func:`hash`. Should return a 32-bit integer usable as a hash value
+ 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
for dictionary operations. The only required property is that objects which
compare equal have the same hash value; it is advised to somehow mix together
(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__` 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).
+ also play a part in comparison of objects.
:meth:`__hash__` may also return a long integer object; the 32-bit integer is
then derived from the hash of that object.