gh-122854: Add Py_HashBuffer() function (#122855)

Author: vstinner

Doc/c-api/hash.rst

@@ -89,6 +89,25 @@ See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 
    .. versionadded:: 3.13
 
+
+.. c:function:: Py_hash_t Py_HashBuffer(const void *ptr, Py_ssize_t len)
+
+   Compute and return the hash value of a buffer of *len* bytes
+   starting at address *ptr*. The hash is guaranteed to match that of
+   :class:`bytes`, :class:`memoryview`, and other built-in objects
+   that implement the :ref:`buffer protocol <bufferobjects>`.
+
+   Use this function to implement hashing for immutable objects whose
+   :c:member:`~PyTypeObject.tp_richcompare` function compares to another
+   object's buffer.
+
+   *len* must be greater than or equal to ``0``.
+
+   This function always succeeds.
+
+   .. versionadded:: 3.14
+
+
 .. c:function:: Py_hash_t PyObject_GenericHash(PyObject *obj)
 
    Generic hashing function that is meant to be put into a type

Doc/whatsnew/3.14.rst

@@ -489,6 +489,9 @@ New Features
   similar to ``sep.join(iterable)`` in Python.
   (Contributed by Victor Stinner in :gh:`121645`.)
 
+* Add :c:func:`Py_HashBuffer` to compute and return the hash value of a buffer.
+  (Contributed by Antoine Pitrou and Victor Stinner in :gh:`122854`.)
+
 
 Porting to Python 3.14
 ----------------------

Include/cpython/pyhash.h

@@ -45,3 +45,5 @@ PyAPI_FUNC(PyHash_FuncDef*) PyHash_GetFuncDef(void);
 
 PyAPI_FUNC(Py_hash_t) Py_HashPointer(const void *ptr);
 PyAPI_FUNC(Py_hash_t) PyObject_GenericHash(PyObject *);
+
+PyAPI_FUNC(Py_hash_t) Py_HashBuffer(const void *ptr, Py_ssize_t len);

Include/internal/pycore_pyhash.h

@@ -20,9 +20,6 @@ _Py_HashPointerRaw(const void *ptr)
     return (Py_hash_t)x;
 }
 
-// Export for '_datetime' shared extension
-PyAPI_FUNC(Py_hash_t) _Py_HashBytes(const void*, Py_ssize_t);
-
 /* Hash secret
  *
  * memory layout on 64 bit systems

Lib/test/test_capi/test_hash.py

@@ -78,6 +78,16 @@ def python_hash_pointer(x):
         VOID_P_MAX = -1 & (2 ** (8 * SIZEOF_VOID_P) - 1)
         self.assertEqual(hash_pointer(VOID_P_MAX), -2)
 
+    def test_hash_buffer(self):
+        hash_buffer = _testcapi.hash_buffer
+
+        def check(data):
+            self.assertEqual(hash_buffer(data), hash(data))
+
+        check(b'')
+        check(b'abc')
+        check(b'x' * 1024)
+
 
 if __name__ == "__main__":
     unittest.main()

Misc/NEWS.d/next/C_API/2024-08-09-13-12-20.gh-issue-122854.-1OgvU.rst

@@ -0,0 +1,2 @@
+Add :c:func:`Py_HashBuffer` to compute and return the hash value of a buffer.
+Patch by Antoine Pitrou and Victor Stinner.

Modules/_datetimemodule.c

@@ -3842,7 +3842,7 @@ datetime_date_replace_impl(PyDateTime_Date *self, int year, int month,
 static Py_hash_t
 generic_hash(unsigned char *data, int len)
 {
-    return _Py_HashBytes(data, len);
+    return Py_HashBuffer(data, len);
 }
 
 

Modules/_hashopenssl.c

@@ -25,7 +25,6 @@
 #include <stdbool.h>
 #include "Python.h"
 #include "pycore_hashtable.h"
-#include "pycore_pyhash.h"        // _Py_HashBytes()
 #include "pycore_strhex.h"        // _Py_strhex()
 #include "hashlib.h"
 
@@ -186,7 +185,7 @@ static const py_hashentry_t py_hashes[] = {
 
 static Py_uhash_t
 py_hashentry_t_hash_name(const void *key) {
-    return _Py_HashBytes(key, strlen((const char *)key));
+    return Py_HashBuffer(key, strlen((const char *)key));
 }
 
 static int

Modules/_sre/sre.c

@@ -2944,7 +2944,7 @@ pattern_hash(PatternObject *self)
         return -1;
     }
 
-    hash2 = _Py_HashBytes(self->code, sizeof(self->code[0]) * self->codesize);
+    hash2 = Py_HashBuffer(self->code, sizeof(self->code[0]) * self->codesize);
     hash ^= hash2;
 
     hash ^= self->flags;

Modules/_testcapi/hash.c

@@ -45,6 +45,14 @@ hash_getfuncdef(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
 }
 
 
+static PyObject *
+long_from_hash(Py_hash_t hash)
+{
+    Py_BUILD_ASSERT(sizeof(long long) >= sizeof(hash));
+    return PyLong_FromLongLong(hash);
+}
+
+
 static PyObject *
 hash_pointer(PyObject *Py_UNUSED(module), PyObject *arg)
 {
@@ -54,8 +62,21 @@ hash_pointer(PyObject *Py_UNUSED(module), PyObject *arg)
     }
 
     Py_hash_t hash = Py_HashPointer(ptr);
-    Py_BUILD_ASSERT(sizeof(long long) >= sizeof(hash));
-    return PyLong_FromLongLong(hash);
+    return long_from_hash(hash);
+}
+
+
+static PyObject *
+hash_buffer(PyObject *Py_UNUSED(module), PyObject *args)
+{
+    char *ptr;
+    Py_ssize_t len;
+    if (!PyArg_ParseTuple(args, "y#", &ptr, &len)) {
+        return NULL;
+    }
+
+    Py_hash_t hash = Py_HashBuffer(ptr, len);
+    return long_from_hash(hash);
 }
 
 
@@ -64,14 +85,14 @@ object_generichash(PyObject *Py_UNUSED(module), PyObject *arg)
 {
     NULLABLE(arg);
     Py_hash_t hash = PyObject_GenericHash(arg);
-    Py_BUILD_ASSERT(sizeof(long long) >= sizeof(hash));
-    return PyLong_FromLongLong(hash);
+    return long_from_hash(hash);
 }
 
 
 static PyMethodDef test_methods[] = {
     {"hash_getfuncdef", hash_getfuncdef, METH_NOARGS},
     {"hash_pointer", hash_pointer, METH_O},
+    {"hash_buffer", hash_buffer, METH_VARARGS},
     {"object_generichash", object_generichash, METH_O},
     {NULL},
 };