From 1e68c4b87633b17da1b602b86f5d23bbe106398f Mon Sep 17 00:00:00 2001
From: Sergey B Kirpichev <skirpichev@gmail.com>
Date: Sat, 9 Mar 2024 23:32:05 +0300
Subject: [PATCH] gh-111389: expose PyHASH_INF/BITS/MODULUS/IMAG macros as
 public (#111418)

Co-authored-by: Victor Stinner <vstinner@python.org>
---
 Doc/c-api/hash.rst                            | 25 ++++++++++++++++++-
 Include/cpython/pyhash.h                      | 16 ++++++++----
 ...-11-15-09-24-51.gh-issue-111418.FYYetY.rst |  2 ++
 3 files changed, 37 insertions(+), 6 deletions(-)
 create mode 100644 Misc/NEWS.d/next/C API/2023-11-15-09-24-51.gh-issue-111418.FYYetY.rst

diff --git a/Doc/c-api/hash.rst b/Doc/c-api/hash.rst
index 91d88ae27bc9f4..1cf094cfcdca24 100644
--- a/Doc/c-api/hash.rst
+++ b/Doc/c-api/hash.rst
@@ -3,7 +3,7 @@
 PyHash API
 ----------
 
-See also the :c:member:`PyTypeObject.tp_hash` member.
+See also the :c:member:`PyTypeObject.tp_hash` member and :ref:`numeric-hash`.
 
 .. c:type:: Py_hash_t
 
@@ -17,6 +17,29 @@ See also the :c:member:`PyTypeObject.tp_hash` member.
 
    .. versionadded:: 3.2
 
+.. c:macro:: PyHASH_MODULUS
+
+   The `Mersenne prime <https://en.wikipedia.org/wiki/Mersenne_prime>`_ ``P = 2**n -1``, used for numeric hash scheme.
+
+   .. versionadded:: 3.13
+
+.. c:macro:: PyHASH_BITS
+
+   The exponent ``n`` of ``P`` in :c:macro:`PyHASH_MODULUS`.
+
+   .. versionadded:: 3.13
+
+.. c:macro:: PyHASH_INF
+
+   The hash value returned for a positive infinity.
+
+   .. versionadded:: 3.13
+
+.. c:macro:: PyHASH_IMAG
+
+   The multiplier used for the imaginary part of a complex number.
+
+   .. versionadded:: 3.13
 
 .. c:type:: PyHash_FuncDef
 
diff --git a/Include/cpython/pyhash.h b/Include/cpython/pyhash.h
index 396c208e1b106a..b476c3f357de92 100644
--- a/Include/cpython/pyhash.h
+++ b/Include/cpython/pyhash.h
@@ -10,14 +10,20 @@
    reduction modulo the prime 2**_PyHASH_BITS - 1. */
 
 #if SIZEOF_VOID_P >= 8
-#  define _PyHASH_BITS 61
+#  define PyHASH_BITS 61
 #else
-#  define _PyHASH_BITS 31
+#  define PyHASH_BITS 31
 #endif
 
-#define _PyHASH_MODULUS (((size_t)1 << _PyHASH_BITS) - 1)
-#define _PyHASH_INF 314159
-#define _PyHASH_IMAG _PyHASH_MULTIPLIER
+#define PyHASH_MODULUS (((size_t)1 << _PyHASH_BITS) - 1)
+#define PyHASH_INF 314159
+#define PyHASH_IMAG _PyHASH_MULTIPLIER
+
+/* Aliases kept for backward compatibility with Python 3.12 */
+#define _PyHASH_BITS PyHASH_BITS
+#define _PyHASH_MODULUS PyHASH_MODULUS
+#define _PyHASH_INF PyHASH_INF
+#define _PyHASH_IMAG PyHASH_IMAG
 
 /* Helpers for hash functions */
 PyAPI_FUNC(Py_hash_t) _Py_HashDouble(PyObject *, double);
diff --git a/Misc/NEWS.d/next/C API/2023-11-15-09-24-51.gh-issue-111418.FYYetY.rst b/Misc/NEWS.d/next/C API/2023-11-15-09-24-51.gh-issue-111418.FYYetY.rst
new file mode 100644
index 00000000000000..5f76ec1443fb44
--- /dev/null
+++ b/Misc/NEWS.d/next/C API/2023-11-15-09-24-51.gh-issue-111418.FYYetY.rst	
@@ -0,0 +1,2 @@
+Add :c:macro:`PyHASH_MODULUS`, :c:macro:`PyHASH_BITS`, :c:macro:`PyHASH_INF`
+and :c:macro:`PyHASH_IMAG` C macros.  Patch by Sergey B Kirpichev.