Add PyUnstable_Unicode_GET_CACHED_HASH() function (#155)

Author: vstinner

docs/api.rst

@@ -64,6 +64,12 @@ Python 3.15
 
    See `PyTuple_FromArray() documentation  <https://docs.python.org/dev/c-api/tuple.html#c.PyTuple_FromArray>`__.
 
+.. c:function:: Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *op)
+
+   See `PyUnstable_Unicode_GET_CACHED_HASH() documentation  <https://docs.python.org/dev/c-api/unicode.html#c.PyUnstable_Unicode_GET_CACHED_HASH>`__.
+
+   Not available on PyPy.
+
 
 Python 3.14
 -----------

docs/changelog.rst

@@ -1,7 +1,11 @@
 Changelog
 =========
 
-* 2025-10-14: Add ``PyTuple_FromArray()`` function.
+* 2025-10-14: Add functions:
+
+  * ``PyTuple_FromArray()``
+  * ``PyUnstable_Unicode_GET_CACHED_HASH()``
+
 * 2025-09-18: Add PEP 782 functions:
 
   * ``PyBytesWriter_Create()``

pythoncapi_compat.h

@@ -2570,6 +2570,19 @@ PyTuple_FromArray(PyObject *const *array, Py_ssize_t size)
 #endif
 
 
+#if PY_VERSION_HEX < 0x030F00A1 && !defined(PYPY_VERSION)
+static inline Py_hash_t
+PyUnstable_Unicode_GET_CACHED_HASH(PyObject *op)
+{
+#if PY_VERSION_HEX >= 0x03000000
+    return ((PyASCIIObject*)op)->hash;
+#else
+    return ((PyUnicodeObject*)op)->hash;
+#endif
+}
+#endif
+
+
 #ifdef __cplusplus
 }
 #endif

tests/test_pythoncapi_compat_cext.c

@@ -1611,6 +1611,13 @@ test_unicode(PyObject *Py_UNUSED(module), PyObject *Py_UNUSED(args))
     assert(PyErr_ExceptionMatches(PyExc_TypeError));
     PyErr_Clear();
 
+#ifndef PYPY_VERSION
+    // Test PyUnstable_Unicode_GET_CACHED_HASH()
+    Py_hash_t hash = PyObject_Hash(abc);
+    assert(hash != -1);
+    assert(PyUnstable_Unicode_GET_CACHED_HASH(abc) == hash);
+#endif
+
     Py_DECREF(abc);
     Py_DECREF(abc0def);
     Py_RETURN_NONE;