summaryrefslogtreecommitdiffstats
path: root/Doc
diff options
context:
space:
mode:
authorNick Coghlan <ncoghlan@gmail.com>2008-08-31 13:21:24 (GMT)
committerNick Coghlan <ncoghlan@gmail.com>2008-08-31 13:21:24 (GMT)
commit73c96dbf34c70bbf1ef807b98d51cf9c0e9dc042 (patch)
treecd7a0e7cae892faefb4f84765c3a74cb2cd964e3 /Doc
parent3a5d7e34adabf972adf3655696195b8d650afb3a (diff)
downloadcpython-73c96dbf34c70bbf1ef807b98d51cf9c0e9dc042.zip
cpython-73c96dbf34c70bbf1ef807b98d51cf9c0e9dc042.tar.gz
cpython-73c96dbf34c70bbf1ef807b98d51cf9c0e9dc042.tar.bz2
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 ........
Diffstat (limited to 'Doc')
-rw-r--r--Doc/reference/datamodel.rst25
1 files changed, 21 insertions, 4 deletions
diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index e167fbd..8793490 100644
--- 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()``;