Test PyUnstable_Unicode_GET_CACHED_HASH

Author: encukou

Doc/c-api/unicode.rst

@@ -1867,7 +1867,7 @@ The following API is deprecated.
         * :c:func:`PyUnicode_GET_LENGTH`
         * :c:func:`PyObject_Length`
       * * ``hash``
-        * N/A
+        * :c:func:`PyUnstable_Unicode_GET_CACHED_HASH`
         * :c:func:`PyObject_Hash`
       * * ``interned``
         * :c:func:`PyUnicode_CHECK_INTERNED`
@@ -1971,3 +1971,17 @@ Unstable API
    of Python (such as 3.16.0).
    Users are encouraged to test with CPython pre-releases and use CPython
    development channels to discuss replacement APIs.
+
+
+.. c:function:: Py_hash_t PyUnstable_Unicode_GET_CACHED_HASH(PyObject *str)
+
+   Return the hash of *str*, as with :c:func:`PyObject_Hash`, if the hash
+   has been cached and is immediately available.
+   Otherwise, return ``-1`` *without* setting an exception.
+
+   The *str* argument must be a string (:c:expr:`PyUnicode_Check(obj)`
+   must be true). This is not checked.
+
+   This function never fails with an exception.
+
+   Note that there are no guarantees on when a Unicode object's hash is cached.

Include/cpython/unicodeobject.h

@@ -312,6 +312,12 @@ static inline Py_ssize_t PyUnicode_GET_LENGTH(PyObject *op) {
 }
 #define PyUnicode_GET_LENGTH(op) PyUnicode_GET_LENGTH(_PyObject_CAST(op))
 
+/* Returns the cached hash, or -1 if not cached yet. */
+static inline Py_hash_t
+PyUnstable_Unicode_GET_CACHED_HASH(PyObject *op) {
+    return _PyASCIIObject_CAST(op)->hash;
+}
+
 /* Write into the canonical representation, this function does not do any sanity
    checks and is intended for usage in loops.  The caller should cache the
    kind and data pointers obtained from other function calls.

Lib/test/test_capi/test_unicode.py

@@ -1739,6 +1739,20 @@ def test_pep393_utf8_caching_bug(self):
                 # Check that the second call returns the same result
                 self.assertEqual(getargs_s_hash(s), chr(k).encode() * (i + 1))
 
+    @support.cpython_only
+    @unittest.skipIf(_testcapi is None, 'need _testcapi module')
+    def test_GET_CACHED_HASH(self):
+        from _testcapi import unicode_GET_CACHED_HASH
+        content_bytes = b'some new string'
+        # avoid parser interning & constant folding
+        obj = str(content_bytes, 'ascii')
+        # impl detail: fresh strings do not have cached hash
+        self.assertEqual(unicode_GET_CACHED_HASH(obj), -1)
+        # impl detail: adding string to a dict caches its hash
+        {obj: obj}
+        # impl detail: ASCII string hashes are equal to bytes ones
+        self.assertEqual(unicode_GET_CACHED_HASH(obj), hash(content_bytes))
+
 
 class PyUnicodeWriterTest(unittest.TestCase):
     def create_writer(self, size):

Modules/_testcapi/unicode.c

@@ -220,6 +220,12 @@ unicode_copycharacters(PyObject *self, PyObject *args)
     return Py_BuildValue("(Nn)", to_copy, copied);
 }
 
+static PyObject*
+unicode_GET_CACHED_HASH(PyObject *self, PyObject *arg)
+{
+    return PyLong_FromLong((long)PyUnstable_Unicode_GET_CACHED_HASH(arg));
+}
+
 
 // --- PyUnicodeWriter type -------------------------------------------------
 
@@ -548,6 +554,7 @@ static PyMethodDef TestMethods[] = {
     {"unicode_asucs4copy",       unicode_asucs4copy,             METH_VARARGS},
     {"unicode_asutf8",           unicode_asutf8,                 METH_VARARGS},
     {"unicode_copycharacters",   unicode_copycharacters,         METH_VARARGS},
+    {"unicode_GET_CACHED_HASH",  unicode_GET_CACHED_HASH,        METH_O},
     {NULL},
 };