fix: use python>=3.11, improve type hints

Author: lepture

.github/workflows/test.yml

@@ -52,7 +52,6 @@ jobs:
       max-parallel: 3
       matrix:
         python-version:
-          - "3.10"
           - "3.11"
           - "3.12"
           - "3.13"

docs/changelog.rst

@@ -12,6 +12,14 @@ Changelog
 .. module:: joserfc
     :noindex:
 
+Unreleased
+----------
+
+- Drop Python 3.10 support; Python 3.11 or newer is required.
+- Preserve key subclasses in factory return types with ``typing.Self``.
+- Improve claim validation type narrowing with ``typing.TypeGuard`` and refine
+  password, native key, and equality annotations.
+
 1.7.7
 -----
 

pyproject.toml

@@ -6,7 +6,7 @@ dependencies = [
     "cryptography>=45.0.1",
 ]
 license = {text = "BSD-3-Clause"}
-requires-python = ">=3.10"
+requires-python = ">=3.11"
 dynamic = ["version"]
 readme = "README.rst"
 classifiers = [
@@ -18,7 +18,6 @@ classifiers = [
     "Operating System :: OS Independent",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
-    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
@@ -75,6 +74,7 @@ docs = [
 
 [tool.ruff]
 line-length = 120
+target-version = "py311"
 
 [tool.pytest.ini_options]
 pythonpath = ["src", "."]
@@ -105,7 +105,7 @@ exclude_lines = [
 
 [tool.mypy]
 strict = true
-python_version = "3.10"
+python_version = "3.11"
 files = ["src/joserfc"]
 show_error_codes = true
 pretty = true
@@ -114,7 +114,6 @@ pretty = true
 requires = ["tox>=4.19"]
 env_list = [
     "style",
-    "py310",
     "py311",
     "py312",
     "py313",

requirements-dev.lock

@@ -8,7 +8,6 @@ colorama==0.4.6 ; sys_platform == 'win32'
 coverage==7.15.0
 cryptography==49.0.0
 distlib==0.4.3
-exceptiongroup==1.3.1 ; python_full_version < '3.11'
 filelock==3.29.7
 identify==2.6.19
 iniconfig==2.3.0

requirements-docs.lock

@@ -13,25 +13,21 @@ colorama==0.4.6 ; sys_platform == 'win32'
 coverage==7.15.0
 cryptography==49.0.0
 distlib==0.4.3
-docutils==0.21.2 ; python_full_version < '3.11'
-docutils==0.22.4 ; python_full_version >= '3.11'
-exceptiongroup==1.3.1 ; python_full_version < '3.11'
+docutils==0.22.4
 filelock==3.29.7
 identify==2.6.19
 idna==3.18
 imagesize==2.0.0
 iniconfig==2.3.0
 jinja2==3.1.6
 librt==0.13.0 ; platform_python_implementation != 'PyPy'
-markdown-it-py==3.0.0 ; python_full_version < '3.11'
-markdown-it-py==4.2.0 ; python_full_version >= '3.11'
+markdown-it-py==4.2.0
 markupsafe==3.0.3
 mdit-py-plugins==0.6.1
 mdurl==0.1.2
 mypy==2.2.0
 mypy-extensions==1.1.0
-myst-parser==4.0.1 ; python_full_version < '3.11'
-myst-parser==5.1.0 ; python_full_version >= '3.11'
+myst-parser==5.1.0
 nodeenv==1.10.0
 packaging==26.2
 pathspec==1.1.1
@@ -47,17 +43,15 @@ pytest-cov==7.1.0
 python-discovery==1.4.3
 pyyaml==6.0.3
 requests==2.34.2
-roman-numerals==4.1.0 ; python_full_version >= '3.11'
+roman-numerals==4.1.0
 ruff==0.15.20
 shibuya==2026.7.8
 snowballstemmer==3.1.1
-sphinx==8.1.3 ; python_full_version < '3.11'
 sphinx==9.0.4 ; python_full_version == '3.11.*'
 sphinx==9.1.0 ; python_full_version >= '3.12'
 sphinx-contributors==0.3.0
 sphinx-copybutton==0.5.2
-sphinx-design==0.6.1 ; python_full_version < '3.11'
-sphinx-design==0.7.0 ; python_full_version >= '3.11'
+sphinx-design==0.7.0
 sphinx-iconify==0.3.0
 sphinx-intl==2.3.2
 sphinx-last-updated-by-git==0.3.8

sonar-project.properties

@@ -5,5 +5,5 @@ sonar.sources=src
 sonar.sourceEncoding=UTF-8
 sonar.test.inclusions=tests/**/test_*.py
 
-sonar.python.version=3.10, 3.11, 3.12, 3.13, 3.14
+sonar.python.version=3.11, 3.12, 3.13, 3.14
 sonar.python.coverage.reportPaths=coverage.xml

src/joserfc/_keys.py

@@ -123,7 +123,7 @@ def __iter__(self) -> t.Iterator[Key]:
     def __bool__(self) -> bool:
         return bool(self.keys)
 
-    def __eq__(self, other: t.Any) -> bool:
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, KeySet):
             return False
         return self.keys == other.keys
@@ -164,7 +164,7 @@ def pick_random_key(self, algorithm: str | None = None, parameters: KeyParameter
         return None
 
     @classmethod
-    def import_key_set(cls, value: KeySetSerialization, parameters: KeyParameters | None = None) -> "KeySet":
+    def import_key_set(cls, value: KeySetSerialization, parameters: KeyParameters | None = None) -> t.Self:
         keys: list[Key] = []
 
         for data in value["keys"]:
@@ -189,7 +189,7 @@ def generate_key_set(
         parameters: KeyParameters | None = None,
         private: bool = True,
         count: int = 4,
-    ) -> "KeySet":
+    ) -> t.Self:
         keys: list[Key] = []
         for _ in range(count):
             key = cls.registry_cls.generate_key(key_type, crv_or_size, parameters, private)

src/joserfc/_rfc7517/models.py

@@ -42,7 +42,7 @@ def import_from_dict(cls, value: DictKey) -> t.Any:
 
     @classmethod
     @abstractmethod
-    def import_from_bytes(cls, value: bytes, password: t.Any = None) -> t.Any:
+    def import_from_bytes(cls, value: bytes, password: str | bytes | None = None) -> t.Any:
         pass
 
     @staticmethod
@@ -102,7 +102,7 @@ def __init__(
             self.validate_dict_key(data)
             self._dict_value = data
 
-    def __eq__(self, other: t.Any) -> bool:
+    def __eq__(self, other: object) -> bool:
         if not isinstance(other, self.__class__):
             return False
         return self.dict_value == other.dict_value
@@ -134,7 +134,7 @@ def alg(self) -> str | None:
         return t.cast(str | None, self.get("alg"))
 
     @property
-    def raw_value(self) -> t.Any:
+    def raw_value(self) -> NativePrivateKey | NativePublicKey:
         raise NotImplementedError()
 
     @property
@@ -268,11 +268,11 @@ def validate_dict_key(cls, data: DictKey) -> None:
 
     @classmethod
     def import_key(
-        cls: type[GenericKey],
+        cls,
         value: AnyKey,
         parameters: KeyParameters | None = None,
-        password: t.Any = None,
-    ) -> GenericKey:
+        password: str | bytes | None = None,
+    ) -> t.Self:
         if isinstance(value, dict):
             cls.validate_dict_key(value)
             raw_key = cls.binding.import_from_dict(value)
@@ -283,12 +283,12 @@ def import_key(
 
     @classmethod
     def generate_key(
-        cls: type[GenericKey],
+        cls,
         *,
         parameters: KeyParameters | None = None,
         private: bool = True,
         auto_kid: bool = False,
-    ) -> GenericKey:
+    ) -> t.Self:
         raise NotImplementedError()
 
 

src/joserfc/_rfc7517/pem.py

@@ -53,7 +53,7 @@ def dump_pem_key(
     key: Any,
     encoding: Literal["PEM", "DER"] | None = None,
     private: bool | None = False,
-    password: Any | None = None,
+    password: str | bytes | None = None,
 ) -> bytes:
     """Export key into PEM/DER format bytes.
 
@@ -118,7 +118,7 @@ def import_from_dict(cls, value: DictKey) -> Any:
         return cls.import_public_key(value)
 
     @classmethod
-    def import_from_bytes(cls, value: bytes, password: Any | None = None) -> Any:
+    def import_from_bytes(cls, value: bytes, password: str | bytes | None = None) -> Any:
         if cls.check_ssh_type(value):
             return import_from_ssh_key(value)
 

src/joserfc/_rfc7518/ec_key.py

@@ -153,26 +153,26 @@ def curve_key_size(self) -> int:
 
     @classmethod
     def import_key(
-        cls: t.Any,
+        cls,
         value: AnyKey | EllipticCurvePrivateKey | EllipticCurvePublicKey,
         parameters: KeyParameters | None = None,
-        password: t.Any = None,
-    ) -> "ECKey":
-        key: ECKey
+        password: str | bytes | None = None,
+    ) -> t.Self:
+        key: t.Self
         if isinstance(value, (EllipticCurvePrivateKey, EllipticCurvePublicKey)):
             key = cls(value, value, parameters)
         else:
-            key = super(ECKey, cls).import_key(value, parameters, password)
+            key = super().import_key(value, parameters, password)
         return key
 
     @classmethod
     def generate_key(
-        cls: type["ECKey"],
+        cls,
         crv: str | None = "P-256",
         parameters: KeyParameters | None = None,
         private: bool = True,
         auto_kid: bool = False,
-    ) -> "ECKey":
+    ) -> t.Self:
         """Generate a ``ECKey`` with the given "crv" value.
 
         :param crv: ECKey curve name
@@ -187,15 +187,15 @@ def generate_key(
 
     @classmethod
     def derive_key(
-        cls: type["ECKey"],
+        cls,
         secret: bytes | str,
         crv: str = "P-256",
         parameters: KeyParameters | None = None,
         private: bool = True,
         auto_kid: bool = False,
         kdf_name: t.Literal["HKDF", "PBKDF2"] = "HKDF",
         kdf_options: dict[str, t.Any] | None = None,
-    ) -> "ECKey":
+    ) -> t.Self:
         """
         Generate an elliptic curve cryptographic key derived from a secret input using a key
         derivation function (KDF). This allows the creation of deterministic elliptic curve
@@ -249,13 +249,16 @@ def derive_key(
         return _wrap_key(cls, raw_key, private, auto_kid, parameters)
 
 
+ECKeyType = t.TypeVar("ECKeyType", bound=ECKey)
+
+
 def _wrap_key(
-    cls: type["ECKey"],
+    cls: type[ECKeyType],
     raw_key: EllipticCurvePrivateKey,
     private: bool,
     auto_kid: bool,
     parameters: KeyParameters | None = None,
-) -> ECKey:
+) -> ECKeyType:
     if private:
         key = cls(raw_key, raw_key, parameters)
     else: