Drop Python 3.9, lots of typing updates

Author: dcwatson

.github/workflows/test.yml

@@ -19,7 +19,7 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest"]
-        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

CHANGELOG.md

@@ -1,5 +1,8 @@
 # 1.0.0
 
 * Initial stable release
+* Dropped Python 3.9 support
 * Added type annotations throughout the code
-* Now always specify `cryptography` as a dependency. The `fernet` extra was removed.
+* Now always specify `cryptography` as a dependency (the `fernet` extra was removed)
+* Boolean casts now additionally accept `t`, `y`, `f`, and `n`
+* `cast`, `sensitive`, and `ttl` are now keyword-only arguments. This is technically a breaking change but all documented usage used keywords anyway.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "cconf"
-dynamic = ["version"]
+version = "1.0.0.dev"
 description = "Multi-sourced (and optionally encrypted) configuration management."
 authors = [
     { name = "Dan Watson", email = "watsond@imsweb.com" }
@@ -16,14 +16,13 @@ classifiers = [
     "License :: OSI Approved :: BSD License",
     "Operating System :: OS Independent",
     "Programming Language :: Python",
-    "Topic :: Software Development :: Libraries :: Python Modules",
-    "Programming Language :: Python",
     "Programming Language :: Python :: 3",
 ]
 
 [dependency-groups]
 dev = [
     "django>=4.2.18",
+    "python-tss-sdk",
 ]
 
 [project.optional-dependencies]
@@ -37,16 +36,8 @@ Homepage = "https://github.com/imsweb/cconf"
 cconf = "cconf.cli:main"
 
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
-
-[tool.uv]
-dev-dependencies = [
-    "python-tss-sdk",
-]
-
-[tool.hatch.version]
-path = "src/cconf/__init__.py"
+requires = ["uv_build>=0.8.3,<0.9.0"]
+build-backend = "uv_build"
 
 [tool.ruff.lint]
 extend-select = ["I"]

src/cconf/__init__.py

@@ -1,3 +1,4 @@
+import importlib.metadata
 import re
 
 from .base import Config, config, undefined
@@ -17,7 +18,7 @@
     Separated,
 )
 
-__version__ = "1.0.0"
+__version__ = importlib.metadata.version("cconf")
 __version_info__ = tuple(
     int(num) if num.isdigit() else str(num)
     for num in re.findall(r"([a-z]*\d+)", __version__)

src/cconf/base.py

@@ -1,7 +1,8 @@
 import datetime
 import os
 import warnings
-from typing import Any, Callable, Mapping, NamedTuple, Optional, Union
+from collections.abc import Callable, Mapping
+from typing import Any, NamedTuple, TypeVar, overload
 
 from .ciphers import DecryptError
 from .exceptions import ConfigError, ConfigWarning
@@ -10,32 +11,40 @@
 
 BOOLEAN_STRINGS = {
     "true": True,
+    "t": True,
     "yes": True,
+    "y": True,
     "1": True,
     "false": False,
+    "f": False,
     "no": False,
+    "n": False,
     "0": False,
 }
 
 
+SourceTypes = BaseSource | StrPath | Mapping[str, Any]
+
+T = TypeVar("T")
+
+
 class ConfigValue(NamedTuple):
     raw: Any
     value: Any
-    source: Optional[BaseSource]
+    source: BaseSource | None
     default: Any
     sensitive: bool
-    ttl: Optional[int]
-
-
-SourceTypes = Union[BaseSource, StrPath, Mapping[str, Any]]
-CastCallable = Callable[..., Any]
+    ttl: int | None
 
 
-class undefined:
+class Undefined:
     def __bool__(self):
         return False
 
 
+undefined = Undefined()
+
+
 class Config:
     _sources: list[BaseSource]
     _defined: dict[str, ConfigValue]
@@ -102,7 +111,7 @@ def dir(self, path: StrPath, **kwargs: Any):
         """
         return self.source(EnvDir(path, **kwargs))
 
-    def env(self, environ: Optional[Mapping[str, Any]] = None, **kwargs: Any):
+    def env(self, environ: Mapping[str, Any] | None = None, **kwargs: Any):
         """
         Adds either a `HostEnv` source, or a generic `Source` to the list of checked
         sources, based on whether `environ` is set.
@@ -117,13 +126,38 @@ def defined(self):
         """
         return {k: v.value for k, v in self._defined.items()}
 
+    # When default=None, the returned value may be None (any cast of None is None).
+    @overload
+    def __call__(
+        self,
+        key: str,
+        default: None,
+        *,
+        cast: Callable[..., T] = str,
+        sensitive: bool = ...,
+        ttl: int | datetime.timedelta | None = ...,
+    ) -> T | None: ...
+
+    # Otherwise, no matter what the default, the returned value is of type T.
+    @overload
+    def __call__(
+        self,
+        key: str,
+        default: Any = undefined,
+        *,
+        cast: Callable[..., T] = str,
+        sensitive: bool = ...,
+        ttl: int | datetime.timedelta | None = ...,
+    ) -> T: ...
+
     def __call__(
         self,
         key: str,
         default: Any = undefined,
-        cast: Optional[CastCallable] = None,
+        *,
+        cast: Callable = str,
         sensitive: bool = False,
-        ttl: Optional[Union[int, datetime.timedelta]] = None,
+        ttl: int | datetime.timedelta | None = None,
     ) -> Any:
         sources_checked: list[str] = []
         key = str(key)
@@ -175,16 +209,38 @@ def __call__(
                 ConfigWarning,
                 stacklevel=2,
             )
-        else:
-            raise KeyError(f"`{key}` not found in any of: {checked}")
-        return default
+            return default
+        raise KeyError(f"`{key}` not found in any of: {checked}")
 
-    def _perform_cast(self, value: Any, cast: Optional[CastCallable], key: str = ""):
-        if cast is None or value is None:
+    # None always casts to None.
+    @overload
+    def _perform_cast(
+        self,
+        value: None,
+        cast: Callable[..., T],
+        key: str = "",
+    ) -> None: ...
+
+    # Otherwise, this always returns the cast type.
+    @overload
+    def _perform_cast(
+        self,
+        value: Any,
+        cast: Callable[..., T],
+        key: str = "",
+    ) -> T: ...
+
+    def _perform_cast(
+        self,
+        value: Any,
+        cast: Callable,
+        key: str = "",
+    ) -> Any:
+        if value is None:
             return value
         elif cast is bool and isinstance(value, str):
             try:
-                return BOOLEAN_STRINGS[value.lower()]
+                return cast(BOOLEAN_STRINGS[value.lower()])
             except KeyError:
                 raise ValueError(f"Invalid boolean for `{key}`: `{value}`")
         try:

src/cconf/cacheurl.py

@@ -1,5 +1,5 @@
-from collections.abc import Iterable
-from typing import Any, Callable, NamedTuple, Optional, Union
+from collections.abc import Callable, Iterable
+from typing import Any, NamedTuple, Optional, Union
 from urllib.parse import ParseResult, parse_qs, urlparse
 
 Processor = Callable[[ParseResult, dict[str, Any]], Any]

src/cconf/ciphers.py

@@ -1,6 +1,7 @@
 import base64
 import binascii
-from typing import Iterable, Optional, TextIO, Union
+from collections.abc import Iterable
+from typing import ClassVar, TextIO
 
 from cryptography.fernet import Fernet, InvalidToken, MultiFernet
 
@@ -28,27 +29,27 @@ def read_keys(fileobj: TextIO) -> MultiFernet:
 
 
 class Cipher:
-    secure = False
+    secure: ClassVar[bool]
 
     def encrypt(self, value: str) -> str:
         raise NotImplementedError()
 
-    def decrypt(self, value: str, ttl: Optional[int] = None) -> str:
+    def decrypt(self, value: str, ttl: int | None = None) -> str:
         raise NotImplementedError()
 
 
 class Keys(Cipher):
     secure = True
 
-    def __init__(self, keyiter: Iterable[Union[str, bytes, Fernet]]):
+    def __init__(self, keyiter: Iterable[str | bytes | Fernet]):
         self._keys = MultiFernet(
             [k if isinstance(k, Fernet) else Fernet(k) for k in keyiter]
         )
 
     def encrypt(self, value: str) -> str:
         return self._keys.encrypt(value.encode()).decode()
 
-    def decrypt(self, value: str, ttl: Optional[int] = None) -> str:
+    def decrypt(self, value: str, ttl: int | None = None) -> str:
         try:
             return self._keys.decrypt(value.encode(), ttl=ttl).decode()
         except InvalidToken:
@@ -57,15 +58,15 @@ def decrypt(self, value: str, ttl: Optional[int] = None) -> str:
 
 class KeyFile(Cipher):
     secure = True
-    _keys: Optional[MultiFernet] = None
 
-    def __init__(self, filename: StrPath, policy: Optional[PolicyCallable] = UserOnly):
-        self.filename = filename
-        self.policy = policy
+    def __init__(self, filename: StrPath, policy: PolicyCallable | None = UserOnly):
+        self._filename = filename
+        self._policy = policy
+        self._keys = None
 
-    def _load_keys(self):
+    def _load_keys(self) -> MultiFernet:
         if self._keys is None:
-            with safe_open(self.filename, policy=self.policy) as fileobj:
+            with safe_open(self._filename, policy=self._policy) as fileobj:
                 self._keys = read_keys(fileobj)
         if not self._keys:
             raise ConfigError(f"No keys found for: {self}")
@@ -74,7 +75,7 @@ def _load_keys(self):
     def encrypt(self, value: str) -> str:
         return self._load_keys().encrypt(value.encode()).decode()
 
-    def decrypt(self, value: str, ttl: Optional[int] = None) -> str:
+    def decrypt(self, value: str, ttl: int | None = None) -> str:
         try:
             return self._load_keys().decrypt(value.encode(), ttl=ttl).decode()
         except InvalidToken:
@@ -87,18 +88,18 @@ class Base64(Cipher):
     def encrypt(self, value: str) -> str:
         return base64.b64encode(value.encode()).decode()
 
-    def decrypt(self, value: str, ttl: Optional[int] = None) -> str:
+    def decrypt(self, value: str, ttl: int | None = None) -> str:
         try:
             return base64.b64decode(value.encode()).decode()
         except binascii.Error:
             raise DecryptError
 
 
-class Identity:
+class Identity(Cipher):
     secure = False
 
     def encrypt(self, value: str) -> str:
         return value
 
-    def decrypt(self, value: str, ttl: Optional[int] = None) -> str:
+    def decrypt(self, value: str, ttl: int | None = None) -> str:
         return value

src/cconf/dburl.py

@@ -1,5 +1,5 @@
 from collections.abc import Iterable
-from typing import Any, NamedTuple, Optional, Union
+from typing import Any, NamedTuple
 from urllib.parse import parse_qs, unquote, unquote_plus, urlparse
 
 
@@ -14,9 +14,9 @@ class Engine(NamedTuple):
 
 def register(
     backend: str,
-    schemes: Optional[Iterable[str]] = None,
+    schemes: Iterable[str] | None = None,
     string_ports: bool = False,
-    options: Optional[dict[str, Any]] = None,
+    options: dict[str, Any] | None = None,
 ):
     if schemes is None:
         schemes = [backend.rsplit(".")[-1]]
@@ -40,8 +40,8 @@ def register(
 
 
 def parse(
-    url_or_config: Union[str, dict[str, Any]],
-    backend: Optional[str] = None,
+    url_or_config: str | dict[str, Any],
+    backend: str | None = None,
     **settings: Any,
 ) -> dict[str, Any]:
     if isinstance(url_or_config, dict):

src/cconf/policy.py

@@ -1,7 +1,8 @@
 import os
 import stat
 import warnings
-from typing import Any, Callable, Optional
+from collections.abc import Callable
+from typing import Any
 
 from .exceptions import ConfigWarning, PolicyError
 from .types import StrPath
@@ -38,7 +39,7 @@ def UserOrGroup(path: StrPath):
 def safe_open(
     path: StrPath,
     *,
-    policy: Optional[PolicyCallable] = None,
+    policy: PolicyCallable | None = None,
     **kwargs: Any,
 ):
     if policy: