domainkit 0.1.0__py3-none-any.whl

domainkit/conf/env.py

@@ -0,0 +1,260 @@
+"""Typed environment reader for settings modules (django-environ style).
+
+Every variable of a project shares one prefix, derived from the project name
+in ``pyproject.toml`` (``billingAPI`` reads ``BILLING_API_DEBUG``); see
+``project_prefix``. The framework's own variables use it too:
+``<PREFIX>SETTINGS_MODULE`` selects the settings, like Django's
+``DJANGO_SETTINGS_MODULE``.
+
+The process environment wins over the project ``.env`` file. Set
+``<PREFIX>ENV_FILE`` to another path, or to an empty value to skip the file;
+relative paths are resolved from the project root.
+
+Any variable can instead be given as ``<NAME>_FILE`` pointing to a file that
+holds the value (Docker and Kubernetes secrets). Prefer files for secrets in
+production: environment variables leak through process listings, crash
+reports, and ``docker inspect``. ``.env`` values are taken literally; ``${...}``
+is not expanded.
+"""
+
+import builtins
+import os
+import re
+import tomllib
+from collections.abc import Callable
+from functools import cache, cached_property
+from pathlib import Path
+from typing import Any, Final
+
+from dotenv import dotenv_values
+
+from domainkit.exceptions import ImproperlyConfigured
+from domainkit.utils.text import snake_case
+
+PROJECT_ROOT_VARIABLE: Final = "DOMAINKIT_PROJECT_ROOT"
+"""Set it when the working directory is not inside the project."""
+ENV_PREFIX_VARIABLE: Final = "DOMAINKIT_ENV_PREFIX"
+"""Set it when the project's ``pyproject.toml`` is not shipped (e.g. wheels)."""
+ENV_FILE_VARIABLE: Final = "ENV_FILE"
+_PREFIX: Final = re.compile(r"(?:[A-Z][A-Z0-9_]*_)?")
+_TRUE: Final = frozenset({"1", "true", "yes", "on"})
+_FALSE: Final = frozenset({"0", "false", "no", "off"})
+
+
+class _Missing:
+    """Sentinel type for settings that have no default and must be provided."""
+
+
+MISSING: Final = _Missing()
+
+
+@cache
+def project_root() -> Path:
+    """Return the directory of the project being run (not of domainkit).
+
+    ``DOMAINKIT_PROJECT_ROOT`` wins; otherwise the nearest directory, from the
+    working directory upwards, that holds a ``pyproject.toml``; otherwise the
+    working directory itself. ``manage.py``, uvicorn, and the Docker image all
+    run from the project directory.
+    """
+    configured = os.environ.get(PROJECT_ROOT_VARIABLE)
+    if configured:
+        return Path(configured).expanduser().resolve()
+    cwd = Path.cwd().resolve()
+    return next(
+        (path for path in (cwd, *cwd.parents) if (path / "pyproject.toml").is_file()),
+        cwd,
+    )
+
+
+def prefix_for(name: str) -> str:
+    """Turn a project name into a prefix (``billingAPI``: ``BILLING_API_``)."""
+    words = re.sub(r"[^A-Za-z0-9]+", "_", snake_case(name)).strip("_").upper()
+    return f"{words}_" if words else ""
+
+
+@cache
+def project_prefix() -> str:
+    """Return the prefix shared by this project's environment variables.
+
+    In order: ``DOMAINKIT_ENV_PREFIX``; ``[tool.domainkit] env-prefix`` in the
+    project's ``pyproject.toml`` (an empty string means no prefix); the
+    project name, ``[project].name``. Renaming the project renames its
+    variables.
+    """
+    explicit = os.environ.get(ENV_PREFIX_VARIABLE)
+    if explicit is None:
+        pyproject = _read_pyproject()
+        options: dict[str, Any] = pyproject.get("tool", {}).get("domainkit", {})
+        explicit = options.get("env-prefix")
+        if explicit is None:
+            name = pyproject.get("project", {}).get("name")
+            if not name:
+                raise ImproperlyConfigured(
+                    f"Cannot derive the environment prefix: set [project].name in "
+                    f"{project_root() / 'pyproject.toml'} or {ENV_PREFIX_VARIABLE}."
+                )
+            explicit = prefix_for(name)
+    prefix = str(explicit).upper()
+    if prefix and not prefix.endswith("_"):
+        prefix = f"{prefix}_"
+    if not _PREFIX.fullmatch(prefix):
+        raise ImproperlyConfigured(
+            f"Environment prefix {prefix!r} must start with a letter and use only "
+            "A-Z, 0-9, and underscores."
+        )
+    return prefix
+
+
+def _read_pyproject() -> dict[str, Any]:
+    """Parse the project's ``pyproject.toml``; a missing file yields ``{}``."""
+    path = project_root() / "pyproject.toml"
+    if not path.is_file():
+        return {}
+    try:
+        return tomllib.loads(path.read_text(encoding="utf-8"))
+    except tomllib.TOMLDecodeError as exc:
+        raise ImproperlyConfigured(f"{path} is not valid TOML: {exc}") from exc
+
+
+class Env:
+    """Read prefixed variables and convert them, failing with the variable name.
+
+    ``Env().int("WORKERS")`` reads ``<project prefix>WORKERS``; pass
+    ``prefix`` to read another family of variables (``""`` for none).
+    """
+
+    def __init__(
+        self, prefix: builtins.str | None = None, env_file: Path | None = None
+    ) -> None:
+        """Use ``env_file`` instead of ``<PREFIX>ENV_FILE`` or the project ``.env``."""
+        self._prefix = prefix
+        self._env_file = env_file
+
+    @property
+    def prefix(self) -> builtins.str:
+        """The prefix in use; the project prefix unless one was given."""
+        return project_prefix() if self._prefix is None else self._prefix
+
+    @cached_property
+    def file_values(self) -> dict[builtins.str, builtins.str]:
+        """Load the ``.env`` file once; a missing file contributes nothing."""
+        path = self._env_file
+        if path is None:
+            configured = os.environ.get(f"{self.prefix}{ENV_FILE_VARIABLE}")
+            if configured == "":
+                return {}
+            path = _from_root(Path(configured or ".env"))
+        if not path.is_file():
+            return {}
+        values = dotenv_values(path, interpolate=False)
+        return {key: value for key, value in values.items() if value is not None}
+
+    def raw(self, name: builtins.str) -> builtins.str | None:
+        """Return the unconverted value of ``prefix + name``, or None when unset."""
+        key = f"{self.prefix}{name}"
+        value = self._lookup(key)
+        secret_file = self._lookup(f"{key}_FILE")
+        if secret_file is None:
+            return value
+        if value is not None:
+            raise ImproperlyConfigured(f"Set either {key} or {key}_FILE, not both.")
+        path = _from_root(Path(secret_file))
+        try:
+            return path.read_text(encoding="utf-8").rstrip("\r\n")
+        except OSError as exc:
+            raise ImproperlyConfigured(f"{key}_FILE: cannot read {path}.") from exc
+
+    def str[D](
+        self, name: builtins.str, default: D | _Missing = MISSING
+    ) -> builtins.str | D:
+        """Read text."""
+        text = self.raw(name)
+        return self._default(name, default) if text is None else text
+
+    def int[D](
+        self, name: builtins.str, default: D | _Missing = MISSING
+    ) -> builtins.int | D:
+        """Read an integer."""
+        text = self.raw(name)
+        if text is None:
+            return self._default(name, default)
+        return self._convert(name, text, builtins.int, "an integer")
+
+    def float[D](
+        self, name: builtins.str, default: D | _Missing = MISSING
+    ) -> builtins.float | D:
+        """Read a number."""
+        text = self.raw(name)
+        if text is None:
+            return self._default(name, default)
+        return self._convert(name, text, builtins.float, "a number")
+
+    def bool[D](
+        self, name: builtins.str, default: D | _Missing = MISSING
+    ) -> builtins.bool | D:
+        """Read 1/0, true/false, yes/no, or on/off (any case)."""
+        text = self.raw(name)
+        if text is None:
+            return self._default(name, default)
+        normalized = text.strip().lower()
+        if normalized in _TRUE:
+            return True
+        if normalized in _FALSE:
+            return False
+        raise self._invalid(name, text, "a boolean (true/false)")
+
+    def list[D](
+        self, name: builtins.str, default: D | _Missing = MISSING
+    ) -> builtins.list[builtins.str] | D:
+        """Read comma-separated text; blank items are dropped."""
+        text = self.raw(name)
+        if text is None:
+            return self._default(name, default)
+        return [item.strip() for item in text.split(",") if item.strip()]
+
+    def path[D](self, name: builtins.str, default: D | _Missing = MISSING) -> Path | D:
+        """Read a file system path; relative paths start at the project root."""
+        text = self.raw(name)
+        if text is None:
+            return self._default(name, default)
+        return _from_root(Path(text).expanduser())
+
+    def _lookup(self, key: builtins.str) -> builtins.str | None:
+        """Return ``key`` from the process environment, else from ``.env``."""
+        value = os.environ.get(key)
+        return value if value is not None else self.file_values.get(key)
+
+    def _default[D](self, name: builtins.str, default: D | _Missing) -> D:
+        """Return the caller's default, or fail when the variable is required."""
+        if isinstance(default, _Missing):
+            raise ImproperlyConfigured(
+                f"Set the {self.prefix}{name} environment variable."
+            )
+        return default
+
+    def _convert[T](
+        self,
+        name: builtins.str,
+        text: builtins.str,
+        cast: Callable[[builtins.str], T],
+        expected: builtins.str,
+    ) -> T:
+        """Convert with ``cast`` or explain which variable is invalid."""
+        try:
+            return cast(text)
+        except ValueError as exc:
+            raise self._invalid(name, text, expected) from exc
+
+    def _invalid(
+        self, name: builtins.str, text: builtins.str, expected: builtins.str
+    ) -> ImproperlyConfigured:
+        """Build the error for a value that cannot be converted."""
+        return ImproperlyConfigured(
+            f"{self.prefix}{name} must be {expected}, got {text!r}."
+        )
+
+
+def _from_root(path: Path) -> Path:
+    """Resolve relative paths against the project root."""
+    return path if path.is_absolute() else project_root() / path

domainkit/conf/global_settings.py

@@ -0,0 +1,205 @@
+"""Framework settings and their defaults (Django's ``global_settings``).
+
+Every UPPERCASE name in the selected settings module is validated here. A name
+the framework does not declare must belong to an installed domain (see
+``DomainConfig.settings_class``) or to the project's own ``SETTINGS_CLASS``,
+so a misspelled setting fails at startup instead of being silently ignored.
+"""
+
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any, Final, Literal, Self
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    IPvAnyNetwork,
+    SecretStr,
+    model_validator,
+)
+
+from domainkit.conf.env import project_root
+from domainkit.utils.rates import parse_rate
+
+DEFAULT_DB_ALIAS: Final = "default"
+
+Environment = Literal["local", "test", "staging", "production"]
+DEPLOYED_ENVIRONMENTS: Final = frozenset({"staging", "production"})
+"""Environments held to the deployment checks in ``Settings``."""
+
+DEFAULT_MIDDLEWARE: Final = (
+    "domainkit.http.middleware.ProxyHeadersMiddleware",
+    "domainkit.http.middleware.SecurityHeadersMiddleware",
+    "domainkit.http.middleware.RequestContextMiddleware",
+    "domainkit.http.middleware.AllowedHostsMiddleware",
+    "domainkit.http.middleware.RequestBodyLimitMiddleware",
+)
+
+
+def _minimal_logging() -> dict[str, Any]:
+    """Leave existing logging untouched when a module does not define LOGGING."""
+    return {"version": 1, "disable_existing_loggers": False}
+
+
+SSLMode = Literal["disable", "require", "verify-ca", "verify-full"]
+"""libpq TLS modes, minus ``allow`` and ``prefer`` (they fall back to plaintext)."""
+
+
+def is_network_database(url: str) -> bool:
+    """Report whether ``url`` reaches a server over the network (not SQLite)."""
+    return not url.split(":", 1)[0].split("+", 1)[0].startswith("sqlite")
+
+
+class DatabaseConfig(BaseModel):
+    """One ``DATABASES`` entry: an SQLAlchemy async URL plus connection options."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    URL: SecretStr
+    """``dialect+driver://user:password@host/name``; hidden in reprs and errors."""
+    MIGRATION_URL: SecretStr | None = None
+    """Schema-owner credentials used by ``migrate``; defaults to ``URL``."""
+    ECHO: bool = False
+    """Log every statement (development only)."""
+    LOG_PARAMETERS: bool = False
+    """Show bound values in SQL logs and error messages; they may hold secrets."""
+
+    SSLMODE: SSLMode | None = None
+    """TLS mode; None keeps the driver default. Deployments need ``verify-full``."""
+    SSLROOTCERT: Path | None = None
+    """CA bundle that signed the server certificate; None uses the system CAs."""
+    SSLCERT: Path | None = None
+    """Client certificate for mutual TLS; requires ``SSLKEY``."""
+    SSLKEY: Path | None = None
+
+    STATEMENT_TIMEOUT: float | None = Field(default=30.0, gt=0)
+    """Seconds before PostgreSQL cancels a statement; migrations are exempt."""
+    LOCK_TIMEOUT: float | None = Field(default=10.0, gt=0)
+    """Seconds a statement may wait for a lock."""
+    IDLE_IN_TRANSACTION_TIMEOUT: float | None = Field(default=60.0, gt=0)
+    """Seconds an open transaction may sit idle before the server ends it."""
+
+    POOL_SIZE: int | None = Field(default=None, ge=1)
+    MAX_OVERFLOW: int | None = Field(default=None, ge=0)
+    POOL_TIMEOUT: float | None = Field(default=None, gt=0)
+    POOL_RECYCLE: int | None = Field(default=None, gt=0)
+    POOL_PRE_PING: bool = True
+    CONNECT_ARGS: dict[str, Any] = Field(default_factory=dict)
+    """Extra driver arguments; they override the ones derived from the settings."""
+
+    @model_validator(mode="after")
+    def check_client_certificate(self) -> Self:
+        """Keep the client certificate and key paired."""
+        if (self.SSLCERT is None) != (self.SSLKEY is None):
+            raise ValueError("SSLCERT and SSLKEY must be set together")
+        return self
+
+
+class Settings(BaseModel):
+    """Validated, read-only settings; extra names are checked at ``setup()``."""
+
+    model_config = ConfigDict(frozen=True, extra="allow")
+
+    SETTINGS_MODULE: str = ""
+    """Set by the loader to the module that produced these settings."""
+    BASE_DIR: Path = Field(default_factory=project_root)
+    ENVIRONMENT: Environment = "local"
+    """Staging and production get the deployment checks below."""
+    DEBUG: bool = False
+    PROJECT_NAME: str = "API"
+    VERSION: str = "0.1.0"
+
+    INSTALLED_DOMAINS: tuple[str, ...] = ()
+    """Domain packages, started in order and stopped in reverse order."""
+    MIDDLEWARE: tuple[str, ...] = DEFAULT_MIDDLEWARE
+    """ASGI middleware classes by dotted path; the first one is outermost."""
+    ROOT_ROUTER: str | None = None
+    """Dotted path to the ``APIRouter`` that mounts every route (``ROOT_URLCONF``)."""
+    ASGI_APPLICATION: str | None = None
+    """``module:attribute`` that ``runserver`` serves."""
+
+    DATABASES: dict[str, DatabaseConfig] = Field(default_factory=dict)
+    MIGRATIONS_DIR: Path = Field(default_factory=lambda: project_root() / "migrations")
+    """Where ``makemigrations`` writes revision files."""
+    LOGGING: dict[str, Any] = Field(default_factory=_minimal_logging)
+    """``logging.config.dictConfig`` mapping applied by ``setup()``."""
+
+    ALLOWED_HOSTS: tuple[str, ...] = ("localhost", "127.0.0.1", "[::1]")
+    """Accepted ``Host`` header values; ``*.example.com`` matches subdomains."""
+    API_DOCS: bool = True
+    """Serve ``/docs``, ``/redoc``, and ``/openapi.json``."""
+    MAX_REQUEST_BODY_SIZE: int = Field(default=1_048_576, ge=1)
+    """Largest accepted request body in bytes; larger requests get 413."""
+    READINESS_TIMEOUT: float = Field(default=5.0, gt=0)
+    """Seconds each readiness check may take before it counts as failed."""
+    READINESS_CACHE_SECONDS: float = Field(default=1.0, ge=0)
+    """Reuse a readiness result this long, so probe floods cannot load the database."""
+    READINESS_DETAILS: bool = False
+    """Name failing components in ``/ready`` responses; they are always logged."""
+    ACCESS_LOG_QUIET_PATHS: tuple[str, ...] = ("/health", "/ready")
+    """Successful requests to these paths are logged at DEBUG, not INFO."""
+    TRUSTED_PROXIES: tuple[IPvAnyNetwork, ...] = ()
+    """Load balancers whose ``X-Forwarded-For``/``-Proto`` headers are believed."""
+    RATE_LIMIT: str | None = None
+    """Requests per caller, e.g. ``"300/minute"``; None disables the limit."""
+    RATE_LIMIT_EXEMPT_PATHS: tuple[str, ...] = ("/health", "/ready", "/metrics")
+    """Exact paths never counted, so probes and scrapers are not refused."""
+    RATE_LIMIT_BACKEND: str = "domainkit.http.ratelimit.MemoryBackend"
+    """Dotted path to a ``Backend`` class; the default counts per process."""
+    METRICS_TOKEN: SecretStr | None = None
+    """Bearer token for ``/metrics``; without it staging and production refuse."""
+    ERROR_REPORTERS: tuple[str, ...] = ()
+    """Callables ``(exc, context) -> None`` by dotted path, e.g. a Sentry adapter."""
+
+    SECURE_HSTS_SECONDS: int = Field(default=0, ge=0)
+    """``Strict-Transport-Security`` max-age; 0 omits the header."""
+    SECURE_HSTS_INCLUDE_SUBDOMAINS: bool = False
+    SECURE_CONTENT_TYPE_NOSNIFF: bool = True
+    SECURE_REFERRER_POLICY: str | None = "no-referrer"
+    X_FRAME_OPTIONS: Literal["DENY", "SAMEORIGIN"] = "DENY"
+
+    CORS_ALLOWED_ORIGINS: tuple[str, ...] = ()
+    CORS_ALLOWED_METHODS: tuple[str, ...] = ("GET", "POST", "PUT", "PATCH", "DELETE")
+    CORS_ALLOWED_HEADERS: tuple[str, ...] = (
+        "Authorization",
+        "Content-Type",
+        "X-Request-ID",
+    )
+    CORS_ALLOW_CREDENTIALS: bool = False
+
+    @model_validator(mode="after")
+    def check_consistency(self) -> Self:
+        """Reject combinations that are unsafe or would fail later at runtime."""
+        if self.DATABASES and DEFAULT_DB_ALIAS not in self.DATABASES:
+            raise ValueError(f"DATABASES must define the {DEFAULT_DB_ALIAS!r} alias")
+        if len(set(self.INSTALLED_DOMAINS)) != len(self.INSTALLED_DOMAINS):
+            raise ValueError("INSTALLED_DOMAINS contains duplicates")
+        if self.CORS_ALLOW_CREDENTIALS and "*" in self.CORS_ALLOWED_ORIGINS:
+            raise ValueError("CORS_ALLOW_CREDENTIALS cannot be used with origin '*'")
+        if self.RATE_LIMIT is not None:
+            parse_rate(self.RATE_LIMIT)
+        if self.ENVIRONMENT in DEPLOYED_ENVIRONMENTS:
+            self._check_deployment()
+        return self
+
+    def _check_deployment(self) -> None:
+        """Enforce the security baseline for staging and production."""
+        where = f"in {self.ENVIRONMENT}"
+        if self.DEBUG:
+            raise ValueError(f"DEBUG must be False {where}")
+        if "*" in self.ALLOWED_HOSTS:
+            raise ValueError(f"ALLOWED_HOSTS must list real host names {where}")
+        rules: dict[str, Callable[[DatabaseConfig], bool]] = {
+            "ECHO logs every statement; disable it": lambda db: db.ECHO,
+            "LOG_PARAMETERS exposes bound values; disable it": lambda db: (
+                db.LOG_PARAMETERS
+            ),
+            "SSLMODE must be 'verify-full'": lambda db: (
+                is_network_database(db.URL.get_secret_value())
+                and db.SSLMODE != "verify-full"
+            ),
+        }
+        for message, violates in rules.items():
+            if aliases := sorted(a for a, db in self.DATABASES.items() if violates(db)):
+                raise ValueError(f"{message} {where} for {aliases}")

domainkit/conf/lazy.py

@@ -0,0 +1,165 @@
+"""Lazy settings proxy that imports and validates the selected settings module."""
+
+import importlib
+from collections.abc import Iterator
+from contextlib import contextmanager
+from typing import Any, Final
+
+from pydantic import ValidationError
+
+from domainkit.conf.env import Env
+from domainkit.conf.global_settings import Settings
+from domainkit.exceptions import ImproperlyConfigured
+from domainkit.utils.module_loading import import_string
+
+SETTINGS_MODULE_VARIABLE: Final = "SETTINGS_MODULE"
+SETTINGS_CLASS_NAME: Final = "SETTINGS_CLASS"
+
+
+class _Unset:
+    """Sentinel type for ``override_settings(NAME=UNSET)``."""
+
+    def __repr__(self) -> str:
+        """Name the sentinel in reprs."""
+        return "UNSET"
+
+
+UNSET: Final = _Unset()
+"""Pass to ``override_settings`` to remove a setting (Django's ``del settings.X``)."""
+
+
+def describe_errors(exc: ValidationError) -> str:
+    """List failing setting paths and reasons, never the submitted values.
+
+    Pydantic's own message embeds the input (a database URL with its password,
+    for example), so it must not reach logs or the console.
+    """
+    lines = []
+    for error in exc.errors(
+        include_url=False, include_input=False, include_context=False
+    ):
+        location = ".".join(str(part) for part in error["loc"]) or "settings"
+        lines.append(f"  {location}: {error['msg']}")
+    return "\n".join(lines)
+
+
+def load_settings(module_name: str) -> Settings:
+    """Validate every public UPPERCASE name of ``module_name``.
+
+    The module may name its own schema with ``SETTINGS_CLASS`` (a ``Settings``
+    subclass or a dotted path to one) to declare project-wide settings.
+    """
+    try:
+        module = importlib.import_module(module_name)
+    except ModuleNotFoundError as exc:
+        missing = exc.name or ""
+        if module_name == missing or module_name.startswith(f"{missing}."):
+            raise ImproperlyConfigured(
+                f"Settings module {module_name!r} does not exist."
+            ) from exc
+        raise
+    values = {
+        name: getattr(module, name)
+        for name in dir(module)
+        if name.isupper() and not name.startswith("_")
+    }
+    schema = _schema(values.pop(SETTINGS_CLASS_NAME, Settings))
+    values["SETTINGS_MODULE"] = module_name
+    try:
+        return schema.model_validate(values)
+    except ValidationError as exc:
+        # "from None": the chained ValidationError would print the inputs.
+        raise ImproperlyConfigured(
+            f"Invalid settings in {module_name!r}:\n{describe_errors(exc)}"
+        ) from None
+
+
+def _schema(value: object) -> type[Settings]:
+    """Resolve ``SETTINGS_CLASS`` to a ``Settings`` subclass."""
+    if isinstance(value, str):
+        try:
+            value = import_string(value)
+        except ImportError as exc:
+            raise ImproperlyConfigured(f"{SETTINGS_CLASS_NAME}: {exc}") from exc
+    if isinstance(value, type) and issubclass(value, Settings):
+        return value
+    raise ImproperlyConfigured(
+        f"{SETTINGS_CLASS_NAME} must be a subclass of domainkit.conf.Settings."
+    )
+
+
+class LazySettings:
+    """Load settings on first access, like ``django.conf.settings``."""
+
+    def __init__(self, env: Env) -> None:
+        """Read the module name from ``<PREFIX>SETTINGS_MODULE`` through ``env``."""
+        self._env = env
+        self._wrapped: Settings | None = None
+
+    @property
+    def configured(self) -> bool:
+        """Report whether a settings module has been loaded."""
+        return self._wrapped is not None
+
+    def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - proxies any setting.
+        """Load settings on first use, then delegate attribute access."""
+        if name.startswith("_"):
+            raise AttributeError(name)
+        return getattr(self._setup(), name)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        """Settings are read-only at runtime; tests use ``override_settings``."""
+        if not name.startswith("_"):
+            raise AttributeError(
+                "Settings are read-only; use override_settings() in tests."
+            )
+        super().__setattr__(name, value)
+
+    def unwrap(self) -> Settings:
+        """Return the loaded ``Settings`` object itself (loading it if needed)."""
+        return self._setup()
+
+    def configure(self, module_name: str) -> None:
+        """Load ``module_name`` now instead of ``<PREFIX>SETTINGS_MODULE``."""
+        self._wrapped = load_settings(module_name)
+
+    def reset(self) -> None:
+        """Forget loaded settings; the next access loads them again."""
+        self._wrapped = None
+
+    @contextmanager
+    def override(self, **changes: object) -> Iterator[None]:
+        """Temporarily replace settings, re-running schema validation.
+
+        A value of ``UNSET`` removes the setting, restoring its default.
+        """
+        current = self._setup()
+        values = {**dict(current), **changes}
+        values = {name: value for name, value in values.items() if value is not UNSET}
+        try:
+            replacement = type(current).model_validate(values)
+        except ValidationError as exc:
+            raise ImproperlyConfigured(
+                f"Invalid settings override:\n{describe_errors(exc)}"
+            ) from None
+        self._wrapped = replacement
+        try:
+            yield
+        finally:
+            self._wrapped = current
+
+    @contextmanager
+    def use(self, module_name: str) -> Iterator[None]:
+        """Temporarily load another settings module, then restore the current one."""
+        previous = self._wrapped
+        self._wrapped = load_settings(module_name)
+        try:
+            yield
+        finally:
+            self._wrapped = previous
+
+    def _setup(self) -> Settings:
+        """Return loaded settings, importing the configured module once."""
+        if self._wrapped is None:
+            self._wrapped = load_settings(self._env.str(SETTINGS_MODULE_VARIABLE))
+        return self._wrapped

domainkit/context.py

@@ -0,0 +1,43 @@
+"""Per-request context shared by logging and error responses.
+
+The context lives in a ``ContextVar``, so concurrent requests never see each
+other's values, and tasks started inside a request inherit them.
+"""
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class RequestContext:
+    """Facts about the request or job being served; no personal data.
+
+    ``actor`` names who is acting. Authentication sets it; None means an
+    anonymous caller, and background work carries the actor that queued it.
+    """
+
+    request_id: str
+    client_ip: str | None
+    method: str
+    path: str
+    actor: str | None = None
+
+
+_current: ContextVar[RequestContext | None] = ContextVar("request", default=None)
+
+
+def current_request() -> RequestContext | None:
+    """Return the request being served, or None outside a request."""
+    return _current.get()
+
+
+@contextmanager
+def bind_request(context: RequestContext) -> Iterator[None]:
+    """Make ``context`` current for the duration of the block."""
+    token = _current.set(context)
+    try:
+        yield
+    finally:
+        _current.reset(token)

domainkit/contrib/__init__.py

@@ -0,0 +1,7 @@
+"""Optional domains that ship with domainkit; install them in INSTALLED_DOMAINS.
+
+- ``domainkit.contrib.messaging``: transactional outbox, durable event
+  handlers, background and periodic tasks, and the ``runworker`` command.
+- ``domainkit.contrib.audit``: an append-only audit trail of committed events.
+- ``domainkit.contrib.idempotency``: replay-safe ``Idempotency-Key`` requests.
+"""