From: Nick Coghlan Date: Sun, 31 Aug 2008 13:21:24 +0000 (+0000) Subject: Merged revisions 66085 (with modifications) via svnmerge from X-Git-Tag: v3.0rc1~151 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=73c96dbf34c70bbf1ef807b98d51cf9c0e9dc042;p=python 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 e167fbd2db..879349081d 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__ = .__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()``;