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

Author: picnixz

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.

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

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

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.

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