Add _hashlib module (#13030)

stdlib/hashlib.pyi

@@ -1,9 +1,19 @@
 import sys
 from _blake2 import blake2b as blake2b, blake2s as blake2s
+from _hashlib import (
+    HASH,
+    openssl_md5 as md5,
+    openssl_sha1 as sha1,
+    openssl_sha224 as sha224,
+    openssl_sha256 as sha256,
+    openssl_sha384 as sha384,
+    openssl_sha512 as sha512,
+    pbkdf2_hmac as pbkdf2_hmac,
+    scrypt as scrypt,
+)
 from _typeshed import ReadableBuffer
 from collections.abc import Callable, Set as AbstractSet
-from typing import Protocol
-from typing_extensions import Self
+from typing import Protocol, type_check_only
 
 if sys.version_info >= (3, 11):
     __all__ = (
@@ -49,67 +59,35 @@ else:
         "pbkdf2_hmac",
     )
 
-class _Hash:
-    @property
-    def digest_size(self) -> int: ...
-    @property
-    def block_size(self) -> int: ...
-    @property
-    def name(self) -> str: ...
-    def copy(self) -> Self: ...
-    def digest(self) -> bytes: ...
-    def hexdigest(self) -> str: ...
-    def update(self, data: ReadableBuffer, /) -> None: ...
-
-class _VarLenHash:
-    digest_size: int
-    block_size: int
-    name: str
-    def copy(self) -> _VarLenHash: ...
-    def digest(self, length: int, /) -> bytes: ...
-    def hexdigest(self, length: int, /) -> str: ...
-    def update(self, data: ReadableBuffer, /) -> None: ...
-
 if sys.version_info >= (3, 9):
-    def new(name: str, data: ReadableBuffer = b"", *, usedforsecurity: bool = ...) -> _Hash: ...
-    def md5(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha1(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha224(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha256(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha384(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha512(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha3_224(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha3_256(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha3_384(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def sha3_512(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _Hash: ...
-    def shake_128(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _VarLenHash: ...
-    def shake_256(string: ReadableBuffer = b"", *, usedforsecurity: bool = True) -> _VarLenHash: ...
+    def new(name: str, data: ReadableBuffer = b"", *, usedforsecurity: bool = ...) -> HASH: ...
+    from _hashlib import (
+        openssl_sha3_224 as sha3_224,
+        openssl_sha3_256 as sha3_256,
+        openssl_sha3_384 as sha3_384,
+        openssl_sha3_512 as sha3_512,
+        openssl_shake_128 as shake_128,
+        openssl_shake_256 as shake_256,
+    )
 
 else:
-    def new(name: str, data: ReadableBuffer = b"") -> _Hash: ...
-    def md5(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha1(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha224(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha256(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha384(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha512(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha3_224(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha3_256(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha3_384(string: ReadableBuffer = b"") -> _Hash: ...
-    def sha3_512(string: ReadableBuffer = b"") -> _Hash: ...
+    @type_check_only
+    class _VarLenHash(HASH):
+        def digest(self, length: int) -> bytes: ...  # type: ignore[override]
+        def hexdigest(self, length: int) -> str: ...  # type: ignore[override]
+
+    def new(name: str, data: ReadableBuffer = b"") -> HASH: ...
+    # At runtime these aren't functions but classes imported from _sha3
+    def sha3_224(string: ReadableBuffer = b"") -> HASH: ...
+    def sha3_256(string: ReadableBuffer = b"") -> HASH: ...
+    def sha3_384(string: ReadableBuffer = b"") -> HASH: ...
+    def sha3_512(string: ReadableBuffer = b"") -> HASH: ...
     def shake_128(string: ReadableBuffer = b"") -> _VarLenHash: ...
     def shake_256(string: ReadableBuffer = b"") -> _VarLenHash: ...
 
 algorithms_guaranteed: AbstractSet[str]
 algorithms_available: AbstractSet[str]
 
-def pbkdf2_hmac(
-    hash_name: str, password: ReadableBuffer, salt: ReadableBuffer, iterations: int, dklen: int | None = None
-) -> bytes: ...
-def scrypt(
-    password: ReadableBuffer, *, salt: ReadableBuffer, n: int, r: int, p: int, maxmem: int = 0, dklen: int = 64
-) -> bytes: ...
-
 if sys.version_info >= (3, 11):
     class _BytesIOLike(Protocol):
         def getbuffer(self) -> ReadableBuffer: ...
@@ -119,5 +97,8 @@ if sys.version_info >= (3, 11):
         def readable(self) -> bool: ...
 
     def file_digest(
-        fileobj: _BytesIOLike | _FileDigestFileObj, digest: str | Callable[[], _Hash], /, *, _bufsize: int = 262144
-    ) -> _Hash: ...
+        fileobj: _BytesIOLike | _FileDigestFileObj, digest: str | Callable[[], HASH], /, *, _bufsize: int = 262144
+    ) -> HASH: ...
+
+# Legacy typing-only alias
+_Hash = HASH