Type annotations! Housekeeping before 1.0

Author: dcwatson

.gitignore

@@ -6,3 +6,4 @@ dist
 .vscode
 .DS_Store
 .nova
+.python-version

CHANGELOG.md

@@ -0,0 +1,5 @@
+# 1.0.0
+
+* Initial stable release
+* Added type annotations throughout the code
+* Now always specify `cryptography` as a dependency. The `fernet` extra was removed.

README.md

@@ -11,11 +11,6 @@ crypography and the ability to specify a maximum valid lifetime (`ttl`).
 
 `pip install cconf`
 
-To use `Fernet` keys for encrypting sensitive settings, `cconf` requires the
-[cryptography](https://cryptography.io/) module, which can be installed as an extra:
-
-`pip install cconf[fernet]`
-
 
 ## Usage
 

pyproject.toml

@@ -5,10 +5,12 @@ description = "Multi-sourced (and optionally encrypted) configuration management
 authors = [
     { name = "Dan Watson", email = "watsond@imsweb.com" }
 ]
-dependencies = []
 readme = "README.md"
 requires-python = ">=3.9"
 license = { text = "BSD" }
+dependencies = [
+    "cryptography",
+]
 classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: BSD License",
@@ -19,10 +21,14 @@ classifiers = [
     "Programming Language :: Python :: 3",
 ]
 
+[dependency-groups]
+dev = [
+    "django>=4.2.18",
+]
+
 [project.optional-dependencies]
-fernet = ["cryptography"]
 secretserver = ["python-tss-sdk"]
-all = ["cryptography", "python-tss-sdk"]
+all = ["python-tss-sdk"]
 
 [project.urls]
 Homepage = "https://github.com/imsweb/cconf"
@@ -36,7 +42,6 @@ build-backend = "hatchling.build"
 
 [tool.uv]
 dev-dependencies = [
-    "cryptography",
     "python-tss-sdk",
 ]
 
@@ -46,3 +51,7 @@ path = "src/cconf/__init__.py"
 [tool.ruff.lint]
 extend-select = ["I"]
 isort.known-first-party = ["cconf"]
+
+[tool.pyright]
+reportPrivateUsage = false
+reportMissingModuleSource = false

src/cconf/__init__.py

@@ -14,11 +14,12 @@
     DatabaseDict,
     Duration,
     Secret,
+    Separated,
 )
 
-__version__ = "0.9.9"
+__version__ = "1.0.0"
 __version_info__ = tuple(
-    int(num) if num.isdigit() else num
+    int(num) if num.isdigit() else str(num)
     for num in re.findall(r"([a-z]*\d+)", __version__)
 )
 
@@ -46,4 +47,5 @@
     "UserOnly",
     "UserOrGroup",
     "Secret",
+    "Separated",
 ]

src/cconf/base.py

@@ -1,12 +1,12 @@
-import collections
 import datetime
 import os
 import warnings
-from pathlib import Path
+from typing import Any, Callable, Mapping, NamedTuple, Optional, Union
 
 from .ciphers import DecryptError
 from .exceptions import ConfigError, ConfigWarning
 from .sources import BaseSource, EnvDir, EnvFile, HostEnv, Source
+from .types import StrPath
 
 BOOLEAN_STRINGS = {
     "true": True,
@@ -17,9 +17,18 @@
     "0": False,
 }
 
-ConfigValue = collections.namedtuple(
-    "ConfigValue", ["raw", "value", "source", "default", "sensitive", "ttl"]
-)
+
+class ConfigValue(NamedTuple):
+    raw: Any
+    value: Any
+    source: Optional[BaseSource]
+    default: Any
+    sensitive: bool
+    ttl: Optional[int]
+
+
+SourceTypes = Union[BaseSource, StrPath, Mapping[str, Any]]
+CastCallable = Callable[..., Any]
 
 
 class undefined:
@@ -28,32 +37,35 @@ def __bool__(self):
 
 
 class Config:
-    def __init__(self, *sources, **kwargs):
+    _sources: list[BaseSource]
+    _defined: dict[str, ConfigValue]
+
+    def __init__(self, *sources: SourceTypes, **kwargs: Any):
         self._debug = False
         self._previous_debug = False
         self.setup(*sources, **kwargs)
 
     def __enter__(self):
         return self
 
-    def __exit__(self, *exc_details):
+    def __exit__(self, *exc_details: Any):
         self._debug = self._previous_debug
 
-    def setup(self, *sources, **kwargs):
+    def setup(self, *sources: SourceTypes, **kwargs: Any):
         self._debug = kwargs.pop("debug", self._debug)
         self._previous_debug = self._debug
         self.reset()
         for source in sources:
             if isinstance(source, BaseSource):
                 self.source(source)
-            elif isinstance(source, (str, Path)):
+            elif isinstance(source, (str, os.PathLike)):
                 if not os.path.exists(source):
                     raise ConfigError(f"File or directory not found: `{source}`")
                 if os.path.isdir(source):
                     self.dir(source, **kwargs)
                 else:
                     self.file(source, **kwargs)
-            elif hasattr(source, "__getitem__"):
+            elif isinstance(source, Mapping):  # type: ignore
                 self.env(source, **kwargs)
             else:
                 raise ConfigError(f"Unknown configuration source: {source}")
@@ -66,31 +78,31 @@ def reset(self):
         self._defined = {}
         return self
 
-    def debug(self, value=True):
+    def debug(self, value: bool = True):
         self._previous_debug = self._debug
         self._debug = value
         return self
 
-    def source(self, source):
+    def source(self, source: BaseSource):
         """
         Adds a configuration source to the list of checked sources.
         """
         self._sources.append(source)
         return self
 
-    def file(self, path, **kwargs):
+    def file(self, path: StrPath, **kwargs: Any):
         """
         Adds an `EnvFile` source to the list of checked sources.
         """
         return self.source(EnvFile(path, **kwargs))
 
-    def dir(self, path, **kwargs):
+    def dir(self, path: StrPath, **kwargs: Any):
         """
         Adds an `EnvDir` source to the list of checked sources.
         """
         return self.source(EnvDir(path, **kwargs))
 
-    def env(self, environ=None, **kwargs):
+    def env(self, environ: Optional[Mapping[str, Any]] = None, **kwargs: Any):
         """
         Adds either a `HostEnv` source, or a generic `Source` to the list of checked
         sources, based on whether `environ` is set.
@@ -105,16 +117,23 @@ def defined(self):
         """
         return {k: v.value for k, v in self._defined.items()}
 
-    def __call__(self, key, default=undefined, cast=None, sensitive=False, ttl=None):
-        sources_checked = []
+    def __call__(
+        self,
+        key: str,
+        default: Any = undefined,
+        cast: Optional[CastCallable] = None,
+        sensitive: bool = False,
+        ttl: Optional[Union[int, datetime.timedelta]] = None,
+    ) -> Any:
+        sources_checked: list[str] = []
         key = str(key)
+        if isinstance(ttl, datetime.timedelta):
+            ttl = int(ttl.total_seconds())
         for source in self._sources:
             sources_checked.append(str(source))
             try:
                 raw = source[key]
                 if sensitive:
-                    if isinstance(ttl, datetime.timedelta):
-                        ttl = int(ttl.total_seconds())
                     raw = source.decrypt(raw, ttl=ttl)
                 value = self._perform_cast(raw, cast, key=key)
                 self._defined[key] = ConfigValue(
@@ -160,7 +179,7 @@ def __call__(self, key, default=undefined, cast=None, sensitive=False, ttl=None)
             raise KeyError(f"`{key}` not found in any of: {checked}")
         return default
 
-    def _perform_cast(self, value, cast, key=""):
+    def _perform_cast(self, value: Any, cast: Optional[CastCallable], key: str = ""):
         if cast is None or value is None:
             return value
         elif cast is bool and isinstance(value, str):

src/cconf/cacheurl.py

@@ -1,26 +1,28 @@
-import urllib.parse as urlparse
+from collections.abc import Iterable
+from typing import Any, Callable, NamedTuple, Optional, Union
+from urllib.parse import ParseResult, parse_qs, urlparse
 
-CACHE_SCHEMES = {}
+Processor = Callable[[ParseResult, dict[str, Any]], Any]
 
 
-class Engine:
-    def __init__(self, backend, process):
-        self.backend = backend
-        self.process = process
+class Engine(NamedTuple):
+    backend: str
+    process: Processor
 
 
-def register(backend, schemes=None, process=None):
+CACHE_SCHEMES: dict[str, Engine] = {}
+
+
+def register(backend: str, schemes: Optional[Iterable[str]] = None):
     if schemes is None:
         schemes = [backend.rsplit(".")[-1]]
     elif isinstance(schemes, str):
         schemes = [schemes]
 
-    engine = Engine(backend, process)
-    for scheme in schemes:
-        CACHE_SCHEMES[scheme] = engine
-
-    def wrapper(func):
-        engine.process = func
+    def wrapper(func: Processor):
+        engine = Engine(backend, func)
+        for scheme in schemes:
+            CACHE_SCHEMES[scheme] = engine
         return func
 
     return wrapper
@@ -29,18 +31,18 @@ def wrapper(func):
 # Support all the first-party Django backends out of the box.
 @register("django.core.cache.backends.locmem.LocMemCache", ("local", "locmem"))
 @register("django.core.cache.backends.db.DatabaseCache", ("db", "database"))
-def hostname_location(url, options):
+def hostname_location(url: ParseResult, options: dict[str, Any]):
     return url.hostname
 
 
 @register("django.core.cache.backends.filebased.FileBasedCache", "file")
-def path_location(url, options):
+def path_location(url: ParseResult, options: dict[str, Any]):
     return url.path
 
 
 @register("django.core.cache.backends.memcached.PyMemcacheCache", "pymemcache")
 @register("django.core.cache.backends.memcached.PyLibMCCache", "pylibmc")
-def memcached_location(url, options):
+def memcached_location(url: ParseResult, options: dict[str, Any]):
     addresses = url.netloc.split(",")
     if len(addresses) == 1:
         return addresses[0]
@@ -49,31 +51,35 @@ def memcached_location(url, options):
 
 
 @register("django.core.cache.backends.dummy.DummyCache", "dummy")
-def null_location(url, options):
+def null_location(url: ParseResult, options: dict[str, Any]):
     return None
 
 
 @register("django.core.cache.backends.redis.RedisCache", "redis")
-def redis_location(url, options):
+def redis_location(url: ParseResult, options: dict[str, Any]):
     path = url.path.lstrip("/")
     if path.isdigit() and "db" not in options:
         options["db"] = path
     return "{}://{}".format(url.scheme, url.netloc)
 
 
-def parse(url, backend=None, **settings):
-    if isinstance(url, dict):
-        return {**url, **settings}
+def parse(
+    url_or_config: Union[str, dict[str, Any]],
+    backend: Optional[str] = None,
+    **settings: Any,
+):
+    if isinstance(url_or_config, dict):
+        return {**url_or_config, **settings}
 
-    url = urlparse.urlparse(url)
+    url = urlparse(url_or_config)
     if url.scheme not in CACHE_SCHEMES:
         raise ValueError(f"Unknown cache scheme: {url.scheme}")
     engine = CACHE_SCHEMES[url.scheme]
-    options = {}
+    options: dict[str, Any] = {}
 
     # Pass the query string into OPTIONS.
     if url.query:
-        for key, values in urlparse.parse_qs(url.query).items():
+        for key, values in parse_qs(url.query).items():
             if values:
                 if len(values) == 1:
                     options[key] = values[0]
@@ -84,7 +90,7 @@ def parse(url, backend=None, **settings):
     options.update(settings.pop("OPTIONS", {}))
 
     # Update with environment configuration.
-    config = {"BACKEND": backend or engine.backend}
+    config: dict[str, Any] = {"BACKEND": backend or engine.backend}
 
     # Allow Django's cache settings to be specified as querystring options.
     for name in ("timeout", "key_prefix", "key_function", "version"):