From 34f4fa8425afed341e44921033b130ba7d099337 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?B=C3=A9n=C3=A9dikt=20Tran?=
 <10796600+picnixz@users.noreply.github.com>
Date: Sat, 21 Feb 2026 12:42:13 +0100
Subject: [PATCH] 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
---
 Doc/deprecations/c-api-pending-removal-in-3.19.rst     |  4 ++++
 Doc/deprecations/index.rst                             |  4 ++++
 Doc/whatsnew/3.15.rst                                  | 10 ++++++++++
 .../2025-11-09-15-44-58.gh-issue-141226.KTb_3F.rst     |  3 +++
 Python/pyhash.c                                        |  2 +-
 5 files changed, 22 insertions(+), 1 deletion(-)
 create mode 100644 Doc/deprecations/c-api-pending-removal-in-3.19.rst
 create mode 100644 Misc/NEWS.d/next/Core_and_Builtins/2025-11-09-15-44-58.gh-issue-141226.KTb_3F.rst

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
index 00000000000..ac9dcb8b424
--- /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 c91c64a1092..bb8bfb5c227 100644
--- 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 feccc496fad..4aac6c453f5 100644
--- 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
index 00000000000..3f7ce732618
--- /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 157312a936b..1eb890794a7 100644
--- 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