python-jose: improvements to jose.backends (#8294)

stubs/python-jose/METADATA.toml

@@ -1,5 +1,5 @@
 version = "3.3.*"
-requires = [] # excluding pyasn1 until typing is available
+requires = [] # excluding pyasn1, pyrsa, cryptography until typing is available
 
 [tool.stubtest]
 ignore_missing_stub = false

stubs/python-jose/jose/backends/base.pyi

@@ -1,17 +1,23 @@
+from _typeshed import Self
 from typing import Any
 
 class Key:
+    # Enable when we can use stubs from installed dependencies,
+    # as `key` can be of type cryptography.x509.base.Certificate:
+    # from cryptography.x509 import Certificate
     def __init__(self, key, algorithm) -> None: ...
-    def sign(self, msg) -> None: ...
-    def verify(self, msg, sig) -> None: ...
-    def public_key(self) -> None: ...
-    def to_pem(self) -> None: ...
-    def to_dict(self) -> None: ...
-    def encrypt(self, plain_text, aad: Any | None = ...) -> None: ...
-    def decrypt(self, cipher_text, iv: Any | None = ..., aad: Any | None = ..., tag: Any | None = ...) -> None: ...
-    def wrap_key(self, key_data) -> None: ...
-    def unwrap_key(self, wrapped_key) -> None: ...
+    def sign(self, msg: bytes) -> bytes: ...
+    def verify(self, msg: bytes, sig: bytes) -> bool: ...
+    def public_key(self: Self) -> Self: ...
+    def to_pem(self) -> bytes: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def encrypt(self, plain_text: str | bytes, aad: bytes | None = ...) -> tuple[bytes, bytes, bytes | None]: ...
+    def decrypt(
+        self, cipher_text: str | bytes, iv: str | bytes | None = ..., aad: bytes | None = ..., tag: bytes | None = ...
+    ) -> bytes: ...
+    def wrap_key(self, key_data: bytes) -> bytes: ...
+    def unwrap_key(self, wrapped_key: bytes) -> bytes: ...
 
 class DIRKey(Key):
-    def __init__(self, key_data, algorithm) -> None: ...
-    def to_dict(self): ...
+    def __init__(self, key_data: str | bytes, algorithm: str) -> None: ...
+    def to_dict(self) -> dict[str, Any]: ...

stubs/python-jose/jose/backends/cryptography_backend.pyi

@@ -1,11 +1,11 @@
 from typing import Any
 
-from .base import Key as Key
+from .base import Key
 
-def decode_dss_signature(signature: bytes) -> tuple[int, int]: ...
-def encode_dss_signature(r: int, s: int) -> bytes: ...
-def get_random_bytes(num_bytes): ...
+def get_random_bytes(num_bytes: int) -> bytes: ...
 
+# Enable when we can use stubs from installed dependencies:
+# from cryptography.hazmat import backends
 class CryptographyECKey(Key):
     SHA256: Any
     SHA384: Any

stubs/python-jose/jose/backends/ecdsa_backend.pyi

@@ -1,11 +1,16 @@
+from _typeshed import Self
+from collections.abc import Callable
+from hashlib import _Hash
 from typing import Any
 
-from .base import Key as Key
+from .base import Key
 
+# Enable when we can use stubs from installed dependencies:
+# from ecdsa.curves import Curve
 class ECDSAECKey(Key):
-    SHA256: Any
-    SHA384: Any
-    SHA512: Any
+    SHA256: Callable[[bytes], _Hash]
+    SHA384: Callable[[bytes], _Hash]
+    SHA512: Callable[[bytes], _Hash]
     CURVE_MAP: Any
     CURVE_NAMES: Any
     hash_alg: Any
@@ -14,7 +19,7 @@ class ECDSAECKey(Key):
     def __init__(self, key, algorithm) -> None: ...
     def sign(self, msg): ...
     def verify(self, msg, sig): ...
-    def is_public(self): ...
-    def public_key(self): ...
+    def is_public(self) -> bool: ...
+    def public_key(self: Self) -> Self: ...
     def to_pem(self): ...
-    def to_dict(self): ...
+    def to_dict(self) -> dict[str, Any]: ...

stubs/python-jose/jose/backends/native.pyi

@@ -1,13 +1,21 @@
+from _typeshed import ReadableBuffer
+from collections.abc import Callable
+from hashlib import _Hash
 from typing import Any
 
-from .base import Key as Key
+from .base import Key
 
-def get_random_bytes(num_bytes): ...
+def get_random_bytes(num_bytes: int) -> bytes: ...
 
 class HMACKey(Key):
-    HASHES: Any
-    prepared_key: Any
-    def __init__(self, key, algorithm) -> None: ...
-    def sign(self, msg): ...
-    def verify(self, msg, sig): ...
-    def to_dict(self): ...
+    HASHES: dict[str, Callable[[bytes], _Hash]]
+    prepared_key: bytes
+    def __init__(
+        self,
+        # explicitly checks for key_data as dict instance, instead of a Mapping
+        key: str | bytes | dict[str, Any],
+        algorithm: str,
+    ) -> None: ...
+    def sign(self, msg: ReadableBuffer | None) -> bytes: ...
+    def verify(self, msg: ReadableBuffer | None, sig: str | bytes) -> bool: ...
+    def to_dict(self) -> dict[str, Any]: ...

stubs/python-jose/jose/backends/rsa_backend.pyi

@@ -1,24 +1,27 @@
+from _typeshed import Self
 from typing import Any
 
-from .base import Key as Key
+from .base import Key
 
-LEGACY_INVALID_PKCS8_RSA_HEADER: Any
-ASN1_SEQUENCE_ID: Any
+LEGACY_INVALID_PKCS8_RSA_HEADER: bytes
+ASN1_SEQUENCE_ID: bytes
 RSA_ENCRYPTION_ASN1_OID: str
 
+# Enable when we can use stubs from installed dependencies:
+# from rsa import PublicKey
 def pem_to_spki(pem, fmt: str = ...): ...
 
 class RSAKey(Key):
     SHA256: str
     SHA384: str
     SHA512: str
-    hash_alg: Any
+    hash_alg: str
     def __init__(self, key, algorithm) -> None: ...
-    def sign(self, msg): ...
-    def verify(self, msg, sig): ...
-    def is_public(self): ...
-    def public_key(self): ...
-    def to_pem(self, pem_format: str = ...): ...
-    def to_dict(self): ...
-    def wrap_key(self, key_data): ...
-    def unwrap_key(self, wrapped_key): ...
+    def sign(self, msg: bytes) -> bytes: ...
+    def verify(self, msg: bytes, sig: bytes) -> bool: ...
+    def is_public(self) -> bool: ...
+    def public_key(self: Self) -> Self: ...
+    def to_pem(self, pem_format: str = ...) -> bytes: ...
+    def to_dict(self) -> dict[str, Any]: ...
+    def wrap_key(self, key_data: bytes) -> bytes: ...
+    def unwrap_key(self, wrapped_key: bytes) -> bytes: ...