Merged revisions 66085 (with modifications) via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r66085 | nick.coghlan | 2008-08-31 23:10:50 +1000 (Sun, 31 Aug 2008) | 1 line

  Issue 2235: document the ability to block inheritance of __hash__ in the language reference
........

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index e167fbd2db8ff8976502c0e77533ad477c12a262..879349081d242e39502d3c60bd2df8b60b0fe1f8 100644 (file)
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -1239,12 +1239,29 @@ Basic customization
    be in the wrong hash bucket).
 
    User-defined classes have :meth:`__cmp__` and :meth:`__hash__` methods
-   by default; with them, all objects compare unequal and ``x.__hash__()``
-   returns ``id(x)``.
-
+   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`.
 
 .. method:: object.__bool__(self)
-
    .. index:: single: __len__() (mapping object method)
 
    Called to implement truth value testing, and the built-in operation ``bool()``;