From 73c96dbf34c70bbf1ef807b98d51cf9c0e9dc042 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 31 Aug 2008 13:21:24 +0000 Subject: 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 ........ --- Doc/reference/datamodel.rst | 25 +++++++++++++++++++++---- 1 file 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__ = .__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()``; -- cgit v0.12