gh-141226: Deprecate PEP-456 support for embedders (#141287)

Deprecate PEP-456 [1] support for providing an external definition
of the string hashing scheme. Removal is scheduled for Python 3.19.

Previously, embedders could define the ``Py_HASH_ALGORITHM`` macro to be
``Py_HASH_EXTERNAL`` [2] to indicate that the hashing scheme was provided
externally but this feature was undocumented, untested and most likely
unused.

[1]: https://peps.python.org/pep-0456/
[2]: https://peps.python.org/pep-0456/#hash-function-selection

diff --git a/Doc/deprecations/c-api-pending-removal-in-3.19.rst b/Doc/deprecations/c-api-pending-removal-in-3.19.rst
new file mode 100644 (file)
index 0000000..ac9dcb8
--- /dev/null
+++ b/Doc/deprecations/c-api-pending-removal-in-3.19.rst
@@ -0,0 +1,4 @@
+Pending removal in Python 3.19
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+* :pep:`456` embedders support for the string hashing scheme definition.

diff --git a/Doc/deprecations/index.rst b/Doc/deprecations/index.rst
index c91c64a109245728c1eb19ef74ec75af1f17bc72..bb8bfb5c227c2d0a564d2c489504a14dca4b633d 100644 (file)
--- a/Doc/deprecations/index.rst
+++ b/Doc/deprecations/index.rst
@@ -20,8 +20,12 @@ C API deprecations
 
 .. include:: c-api-pending-removal-in-3.15.rst
 
+.. include:: c-api-pending-removal-in-3.16.rst
+
 .. include:: c-api-pending-removal-in-3.18.rst
 
+.. include:: c-api-pending-removal-in-3.19.rst
+
 .. include:: c-api-pending-removal-in-3.20.rst
 
 .. include:: c-api-pending-removal-in-future.rst

diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
index feccc496fad0e014ea446ae6c499953868d5860c..4aac6c453f533d02bdfaed8e9f777347ce3cb86a 100644 (file)
--- a/Doc/whatsnew/3.15.rst
+++ b/Doc/whatsnew/3.15.rst
@@ -1723,6 +1723,16 @@ on Python 3.13 and older.
 Deprecated C APIs
 -----------------
 
+* Deprecate :pep:`456` support for providing an external definition
+  of the string hashing scheme. Removal is scheduled for Python 3.19.
+
+  Previously, embedders could define :c:macro:`Py_HASH_ALGORITHM` to be
+  ``Py_HASH_EXTERNAL`` to indicate that the hashing scheme was provided
+  externally but this feature was undocumented, untested and most likely
+  unused.
+
+  (Contributed by Bénédikt Tran in :gh:`141226`.)
+
 * For unsigned integer formats in :c:func:`PyArg_ParseTuple`,
   accepting Python integers with value that is larger than the maximal value
   for the C type or less than the minimal value for the corresponding

diff --git a/Misc/NEWS.d/next/Core_and_Builtins/2025-11-09-15-44-58.gh-issue-141226.KTb_3F.rst b/Misc/NEWS.d/next/Core_and_Builtins/2025-11-09-15-44-58.gh-issue-141226.KTb_3F.rst
new file mode 100644 (file)
index 0000000..3f7ce73
--- /dev/null
+++ b/Misc/NEWS.d/next/Core_and_Builtins/2025-11-09-15-44-58.gh-issue-141226.KTb_3F.rst
@@ -0,0 +1,3 @@
+Deprecate :pep:`456` support for providing an external definition
+of the string hashing scheme. Removal is scheduled for Python 3.19.
+Patch by Bénédikt Tran.

diff --git a/Python/pyhash.c b/Python/pyhash.c
index 157312a936bbcc867a5d2ce6644e40abacd1d927..1eb890794a754442731842eba56040b219bfae5b 100644 (file)
--- a/Python/pyhash.c
+++ b/Python/pyhash.c
@@ -17,7 +17,7 @@
 _Py_HashSecret_t _Py_HashSecret = {{0}};
 
 #if Py_HASH_ALGORITHM == Py_HASH_EXTERNAL
-extern PyHash_FuncDef PyHash_Func;
+Py_DEPRECATED(3.15) extern PyHash_FuncDef PyHash_Func;
 #else
 static PyHash_FuncDef PyHash_Func;
 #endif