Issue 2235: document PyObject_HashNotImplemented

diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst
index 7bb845a7a68a01f0630cafadf93c41f099f4d792..883d095df138ea7703782cfda37d812e84569e39 100644 (file)
--- 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 1807c92b5eedaa4c3c367a8cf96ca8ffc461095b..463223a47847c9ef154f1406e9a84bb4ec50c24b 100644 (file)
--- 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 919071453b6bbd95915dfbf4bb3153e9d8d55199..09f1138689802c2d339de12631523004b0e112d9 100644 (file)
--- 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