gh-134978: deprecate string keyword parameter for hash function constructors (#134979)

picnixz · web-flow · commit ee65ebdb5000 · 2025-06-02T10:25:50.000+02:00
diff --git 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
@@ -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
@@ -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
@@ -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 @@ def test_clinic_signature(self):
             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
@@ -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
@@ -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;
     }
