From 6e8fef07e5d1a3372d0c729c81dd383a23b053d5 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Mon, 18 Aug 2008 13:14:22 +0000 Subject: [PATCH] Issue 2235: document PyObject_HashNotImplemented --- Doc/c-api/object.rst | 10 ++++++++++ Doc/c-api/typeobj.rst | 8 ++++++++ Misc/NEWS | 3 +++ 3 files changed, 21 insertions(+) diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index 7bb845a7a68..883d095df13 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -269,6 +269,16 @@ is considered sufficient for this determination. This is the equivalent of the Python expression ``hash(o)``. +.. cfunction:: long PyObject_HashNotImplemented(PyObject *o) + + Set a TypeError indicating that ``type(o)`` is not hashable and return ``-1``. + This function receives special treatment when stored in a ``tp_hash`` slot, + allowing a type to explicit indicate to the interpreter that it is not + hashable. + + .. versionadded:: 2.6 + + .. cfunction:: int PyObject_IsTrue(PyObject *o) Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise. diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index 1807c92b5ee..463223a4784 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -324,6 +324,14 @@ type objects) *must* have the :attr:`ob_size` field. error occurs during the computation of the hash value, the function should set an exception and return ``-1``. + This field can be set explicitly to :cfunc:`PyObject_HashNotImplemented` to + block inheritance of the hash method from a parent type. This is interpreted + as the equivalent of ``__hash__ = None`` at the Python level, causing + ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note + that the converse is also true - setting ``__hash__ = None`` on a class at + the Python level will result in the ``tp_hash`` slot being set to + :cfunc:`PyObject_HashNotImplemented`. + When this field is not set, two possibilities exist: if the :attr:`tp_compare` and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on the object's address is returned; otherwise, a :exc:`TypeError` is raised. diff --git a/Misc/NEWS b/Misc/NEWS index 919071453b6..09f11386898 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -166,6 +166,9 @@ Build Documentation ------------- +- Issue #2235: the C API function PyObject_HashNotImplemented and its + interaction with the tp_hash slot (added in 2.6b2) are now documented + - Issue #643841: The language reference now provides more detailed coverage of the lookup process for special methods. The disclaimers regarding lack of coverage of new-style classes have also been