deprecate string keyword parameter for hash function constructors

picnixz · picnixz · commit 996992d74b1c · 2025-05-31T16:09:17.000+02:00
diff --git a/Doc/deprecations/pending-removal-in-3.17.rst b/Doc/deprecations/pending-removal-in-3.17.rst
@@ -1,6 +1,17 @@
 Pending removal in Python 3.17
 ------------------------------
 
+* :mod:`hashlib`:
+
+  - Supporting the undocumented ``string`` keyword parameter in :func:`~hashlib.new`
+    and hash function constructors such as :func:`~hashlib.md5` is deprecated.
+    Use the ``data`` keyword parameter instead, or simply pass the data to hash
+    as a positional argument.
+
+    Before Python 3.13, the ``string`` keyword parameter was not correctly
+    supported depending on the backend implementation of hash functions, and
+    users should prefer passing the data to hash as a positional argument.
+
 * :mod:`typing`:
 
   - Before Python 3.14, old-style unions were implemented using the private class
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.17
+   The *undocumented* ``string`` keyword parameter in :func:`new` and hash
+   function constructors such as :func:`md5` is deprecated.
+   Use the ``data`` keyword parameter instead, or simply pass the data to hash
+   as a positional argument.
+
+
 Usage
 -----
 
diff --git a/Doc/whatsnew/3.15.rst b/Doc/whatsnew/3.15.rst
@@ -129,8 +129,15 @@ module_name
 Deprecated
 ==========
 
-* module_name:
-  TODO
+hashlib
+-------
+
+* Supporting the undocumented ``string`` keyword parameter in
+  :func:`~hashlib.new` and hash function constructors such as
+  :func:`~hashlib.md5` is deprecated and slated for removal in Python 3.17.
+  Use the ``data`` keyword parameter instead, or simply pass the data to hash
+  as a positional argument.
+  (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.17; "
+    "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,5 @@
+Supporting the undocumented ``string`` keyword parameter in :func:`hashlib.new`
+and hash function constructors such as :func:`hashlib.md5` is deprecated and
+slated for removal in Python 3.17. Use the ``data`` keyword parameter instead,
+or simply pass the data to hash as a positional argument.
+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.17; "
+                         "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;
     }
