gh-134978: deprecate `string` keyword parameter for hash function constructors (...

diff --git a/Doc/deprecations/pending-removal-in-3.19.rst b/Doc/deprecations/pending-removal-in-3.19.rst
index 3936f63ca5b5af083a3f5159570c75faa7850796..25f9cba390de68ee5d1f1b9d853bf0337ac3a10c 100644 (file)
--- a/Doc/deprecations/pending-removal-in-3.19.rst
+++ b/Doc/deprecations/pending-removal-in-3.19.rst
@@ -6,3 +6,19 @@ Pending removal in Python 3.19
   * Implicitly switching to the MSVC-compatible struct layout by setting
     :attr:`~ctypes.Structure._pack_` but not :attr:`~ctypes.Structure._layout_`
     on non-Windows platforms.
+
+* :mod:`hashlib`:
+
+  - In hash function constructors such as :func:`~hashlib.new` or the
+    direct hash-named constructors such as :func:`~hashlib.md5` and
+    :func:`~hashlib.sha256`, their optional initial data parameter could
+    also be passed a keyword argument named ``data=`` or ``string=`` in
+    various :mod:`!hashlib` implementations.
+
+    Support for the ``string`` keyword argument name is now deprecated
+    and slated for removal in Python 3.19.
+
+    Before Python 3.13, the ``string`` keyword parameter was not correctly
+    supported depending on the backend implementation of hash functions.
+    Prefer passing the initial data as a positional argument for maximum
+    backwards compatibility.

diff --git a/Doc/library/hashlib.rst b/Doc/library/hashlib.rst
index 4818a4944a512a43bff061831af071edaa8f0acb..8bba6700930bf4ec65bf9bdbe5ae152107eac711 100644 (file)
--- a/Doc/library/hashlib.rst
+++ b/Doc/library/hashlib.rst
@@ -94,6 +94,13 @@ accessible by name via :func:`new`.  See :data:`algorithms_available`.
    OpenSSL does not provide we fall back to a verified implementation from
    the `HACL\* project`_.
 
+.. deprecated-removed:: 3.15 3.19
+   The undocumented ``string`` keyword parameter in :func:`!_hashlib.new`
+   and hash-named constructors such as :func:`!_md5.md5` is deprecated.
+   Prefer passing the initial data as a positional argument for maximum
+   backwards compatibility.
+
+
 Usage
 -----
 

diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
index 244ce327763f574e62b6a50db4dddae046d9c1b4..b342939f70577facdc17cbcd6f0a17dc121c2dc6 100644 (file)
--- a/Doc/whatsnew/3.15.rst
+++ b/Doc/whatsnew/3.15.rst
@@ -146,8 +146,20 @@ module_name
 Deprecated
 ==========
 
-* module_name:
-  TODO
+hashlib
+-------
+
+* In hash function constructors such as :func:`~hashlib.new` or the
+  direct hash-named constructors such as :func:`~hashlib.md5` and
+  :func:`~hashlib.sha256`, their optional initial data parameter could
+  also be passed a keyword argument named ``data=`` or ``string=`` in
+  various :mod:`hashlib` implementations.
+
+  Support for the ``string`` keyword argument name is now deprecated and
+  is slated for removal in Python 3.19. Prefer passing the initial data as
+  a positional argument for maximum backwards compatibility.
+
+  (Contributed by Bénédikt Tran in :gh:`134978`.)
 
 
 .. Add deprecations above alphabetically, not here at the end.

diff --git a/Lib/test/test_hashlib.py b/Lib/test/test_hashlib.py
index 8244f7c7553a37fad0c66ee45f79ab4180c3c6b6..b83ae181718b7a7ce74ebdbc34d5a447820c2607 100644 (file)
--- a/Lib/test/test_hashlib.py
+++ b/Lib/test/test_hashlib.py
@@ -98,6 +98,14 @@ def read_vectors(hash_name):
             yield parts
 
 
+DEPRECATED_STRING_PARAMETER = re.escape(
+    "the 'string' keyword parameter is deprecated since "
+    "Python 3.15 and slated for removal in Python 3.19; "
+    "use the 'data' keyword parameter or pass the data "
+    "to hash as a positional argument instead"
+)
+
+
 class HashLibTestCase(unittest.TestCase):
     supported_hash_names = ( 'md5', 'MD5', 'sha1', 'SHA1',
                              'sha224', 'SHA224', 'sha256', 'SHA256',
@@ -255,17 +263,23 @@ class HashLibTestCase(unittest.TestCase):
             with self.subTest(constructor.__name__):
                 constructor(b'')
                 constructor(data=b'')
-                constructor(string=b'')  # should be deprecated in the future
+                with self.assertWarnsRegex(DeprecationWarning,
+                                           DEPRECATED_STRING_PARAMETER):
+                    constructor(string=b'')
 
             digest_name = constructor(b'').name
             with self.subTest(digest_name):
                 hashlib.new(digest_name, b'')
                 hashlib.new(digest_name, data=b'')
-                hashlib.new(digest_name, string=b'')
+                with self.assertWarnsRegex(DeprecationWarning,
+                                           DEPRECATED_STRING_PARAMETER):
+                    hashlib.new(digest_name, string=b'')
                 if self._hashlib:
                     self._hashlib.new(digest_name, b'')
                     self._hashlib.new(digest_name, data=b'')
-                    self._hashlib.new(digest_name, string=b'')
+                    with self.assertWarnsRegex(DeprecationWarning,
+                                               DEPRECATED_STRING_PARAMETER):
+                        self._hashlib.new(digest_name, string=b'')
 
     @unittest.skipIf(get_fips_mode(), "skip in FIPS mode")
     def test_clinic_signature_errors(self):

diff --git a/Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst b/Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst
new file mode 100644 (file)
index 0000000..e75ce16
--- /dev/null
+++ b/Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst
@@ -0,0 +1,7 @@
+:mod:`hashlib`: Supporting the ``string`` keyword parameter in hash function
+constructors such as :func:`~hashlib.new` or the direct hash-named constructors
+such as :func:`~hashlib.md5` and :func:`~hashlib.sha256` is now deprecated and
+slated for removal in Python 3.19.
+Prefer passing the initial data as a positional argument for maximum backwards
+compatibility.
+Patch by Bénédikt Tran.

diff --git a/Modules/hashlib.h b/Modules/hashlib.h
index a80b195a7657927827d752644dbe9f87c08408d0..e82ec92be25c57462d9597085647428268204bfd 100644 (file)
--- a/Modules/hashlib.h
+++ b/Modules/hashlib.h
@@ -86,6 +86,15 @@ _Py_hashlib_data_argument(PyObject **res, PyObject *data, PyObject *string)
     }
     else if (data == NULL && string != NULL) {
         // called as H(string=...)
+        if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                         "the 'string' keyword parameter is deprecated since "
+                         "Python 3.15 and slated for removal in Python 3.19; "
+                         "use the 'data' keyword parameter or pass the data "
+                         "to hash as a positional argument instead", 1) < 0)
+        {
+            *res = NULL;
+            return -1;
+        }
         *res = string;
         return 1;
     }