python · picnixz · May 31, 2025 · May 26, 2025 · May 26, 2025 · May 27, 2025
@@ -141,18 +141,45 @@ def __get_openssl_constructor(name):
         return __get_builtin_constructor(name)
 
 
-def __py_new(name, data=b'', **kwargs):
+def __data_argument(funcname, data_sentinel, kwargs):
+    assert '__data_sentinel' not in kwargs
+    if 'data' in kwargs and 'string' in kwargs:
+        raise TypeError(f"{funcname}(): 'data' and 'string' are mutually exclusive "
+                        f"and support for 'string' keyword parameter is slated for "
+                        f"removal in a future version.")
+    if data_sentinel is None:
+        if 'data' in kwargs:
+            # new(name, data=...)
+            return kwargs.pop('data')
+        elif 'string' in kwargs:
+            # new(name, string=...)
+            return kwargs.pop('string')
+        return b''
+    else:
+        if 'data' in kwargs:
+            # new(name, data, data=...)
+            raise TypeError(f"{funcname}(): got multiple values for argument 'data'")
+        if 'string' in kwargs:
+            # new(name, data, string=...)
+            raise TypeError(f"{funcname}(): got multiple values for argument 'string'")
+        # new(name, data)
+        return data_sentinel
+
+
+def __py_new(name, __data_sentinel=None, **kwargs):
     """new(name, data=b'', **kwargs) - Return a new hashing object using the
     named algorithm; optionally initialized with data (which must be
     a bytes-like object).
     """
+    data = __data_argument('__py_new', __data_sentinel, kwargs)
     return __get_builtin_constructor(name)(data, **kwargs)
 
 
-def __hash_new(name, data=b'', **kwargs):
+def __hash_new(name, __data_sentinel=None, **kwargs):
     """new(name, data=b'') - Return a new hashing object using the named algorithm;
     optionally initialized with data (which must be a bytes-like object).
     """
+    data = __data_argument('__hash_new', __data_sentinel, kwargs)
     if name in __block_openssl_constructor:
         # Prefer our builtin blake2 implementation.
         return __get_builtin_constructor(name)(data, **kwargs)

@@ -12,6 +12,7 @@
 import itertools
 import logging
 import os
+import re
 import sys
 import sysconfig
 import tempfile
@@ -140,11 +141,12 @@ def __init__(self, *args, **kwargs):
         # of hashlib.new given the algorithm name.
         for algorithm, constructors in self.constructors_to_test.items():
             constructors.add(getattr(hashlib, algorithm))
-            def _test_algorithm_via_hashlib_new(data=None, _alg=algorithm, **kwargs):
-                if data is None:
+            def c(_data=None, _alg=algorithm, **kwargs):
+                if _data is None:
                     return hashlib.new(_alg, **kwargs)
-                return hashlib.new(_alg, data, **kwargs)
-            constructors.add(_test_algorithm_via_hashlib_new)
+                return hashlib.new(_alg, _data, **kwargs)
+            c.__name__ = f'do_test_algorithm_via_hashlib_new_{algorithm}'
+            constructors.add(c)
 
         _hashlib = self._conditional_import_module('_hashlib')
         self._hashlib = _hashlib
@@ -249,6 +251,28 @@ def test_usedforsecurity_false(self):
             self._hashlib.new("md5", usedforsecurity=False)
             self._hashlib.openssl_md5(usedforsecurity=False)
 
+    def test_clinic_signature(self):
+        for constructor in self.hash_constructors:
+            with self.subTest(constructor.__name__):
+                constructor(data=b'')
+                constructor(string=b'')  # should be deprecated in the future
+
+    def test_clinic_signature_errors(self):
+        conflicting_call = re.escape(
+            "'data' and 'string' are mutually exclusive "
+            "and support for 'string' keyword parameter "
+            "is slated for removal in a future version."
+        )
+        duplicated_param = re.escape("got multiple values for argument")
+        for constructor in self.hash_constructors:
+            with self.subTest(constructor.__name__):
+                with self.assertRaisesRegex(TypeError, conflicting_call):
+                    constructor(b'', string=b'')
+                with self.assertRaisesRegex(TypeError, conflicting_call):
+                    constructor(data=b'', string=b'')
+            with self.assertRaisesRegex(TypeError, duplicated_param):
+                constructor(b'', data=b'')
+
     def test_unknown_hash(self):
         self.assertRaises(ValueError, hashlib.new, '
BD3B
spam spam spam spam spam')
         self.assertRaises(TypeError, hashlib.new, 1)
@@ -718,8 +742,6 @@ def check_blake2(self, constructor, salt_size, person_size, key_size,
         self.assertRaises(ValueError, constructor, node_offset=-1)
         self.assertRaises(OverflowError, constructor, node_offset=max_offset+1)
 
-        self.assertRaises(TypeError, constructor, data=b'')
-        self.assertRaises(TypeError, constructor, string=b'')
         self.assertRaises(TypeError, constructor, '')
 
         constructor(

diff --git a/Misc/NEWS.d/next/Library/2025-05-26-14-04-39.gh-issue-134696.P04xUa.rst b/Misc/NEWS.d/next/Library/2025-05-26-14-04-39.gh-issue-134696.P04xUa.rst
@@ -0,0 +1,5 @@
+Built-in HACL* and OpenSSL implementations of hash function constructors
+now correctly accept the same *documented* named arguments. For instance,
+:func:`~hashlib.md5` could be previously invoked as ``md5(data=data)``
+or ``md5(string=string)`` depending on the underlying implementation
+but these calls were not compatible. Patch by Bénédikt Tran.