https://github.com/python/cpython/commit/ee65ebdb50005655d75aca1618d3994a7b7ed869
commit: ee65ebdb50005655d75aca1618d3994a7b7ed869
branch: main
author: Bénédikt Tran <10796600+picn...@users.noreply.github.com>
committer: picnixz <10796600+picn...@users.noreply.github.com>
date: 2025-06-02T10:25:50+02:00
summary:
gh-134978: deprecate `string` keyword parameter for hash function constructors
(#134979)
files:
A Misc/NEWS.d/next/Library/2025-05-31-15-49-46.gh-issue-134978.mXXuvW.rst
M Doc/deprecations/pending-removal-in-3.19.rst
M Doc/library/hashlib.rst
M Doc/whatsnew/3.15.rst
M Lib/test/test_hashlib.py
M Modules/hashlib.h
diff --git a/Doc/deprecations/pending-removal-in-3.19.rst
b/Doc/deprecations/pending-removal-in-3.19.rst
index 3936f63ca5b5af..25f9cba390de68 100644
--- 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 4818a4944a512a..8bba6700930bf4 100644
--- 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 244ce327763f57..b342939f70577f 100644
--- 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 8244f7c7553a37..b83ae181718b7a 100644
--- 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
new file mode 100644
index 00000000000000..e75ce1622d6396
--- /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 a80b195a765792..e82ec92be25c57 100644
--- 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;
}
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: arch...@mail-archive.com
