domainkit 0.1.0__py3-none-any.whl

domainkit/__init__.py

@@ -0,0 +1,40 @@
+"""domainkit: a Django-style framework for domain-driven FastAPI services.
+
+Layers, lowest first; a module may import only from its own layer or below:
+
+1. ``exceptions``, ``utils``, ``ddd``: no settings, no I/O. ``ddd`` holds the
+   domain building blocks (entities, value objects, events, repositories).
+2. ``conf``: settings loading and validation.
+3. ``apps``, ``context``, ``log``, ``reporting``: the domain registry and
+   observability.
+4. ``db``, ``http``: SQLAlchemy and FastAPI integration.
+5. ``management``: the ``manage.py`` commands.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("domainkit")
+except PackageNotFoundError:  # pragma: no cover - running from a source tree
+    __version__ = "0.0.0+unknown"
+
+
+def setup() -> None:
+    """Configure logging and load the installed domains (``django.setup()``).
+
+    Safe to call more than once; later calls do nothing.
+    """
+    from domainkit.apps import registry
+    from domainkit.conf import settings
+    from domainkit.ddd import event_bus
+    from domainkit.log import configure_logging
+    from domainkit.reporting import report_error, reporters
+
+    if registry.ready:
+        return
+    configure_logging(settings.LOGGING)
+    reporters()
+    event_bus.error_hook = lambda exc, event: report_error(
+        exc, event=type(event).__qualname__, event_id=str(event.event_id)
+    )
+    registry.populate(settings.INSTALLED_DOMAINS)

domainkit/apps/__init__.py

@@ -0,0 +1,6 @@
+"""Installed domains (``django.apps``): configuration classes and the registry."""
+
+from domainkit.apps.config import DomainConfig
+from domainkit.apps.registry import DomainRegistry, registry
+
+__all__ = ["DomainConfig", "DomainRegistry", "registry"]

domainkit/apps/config.py

@@ -0,0 +1,118 @@
+"""``DomainConfig``: Django's ``AppConfig`` for a bounded context."""
+
+from collections.abc import Sequence
+from importlib import import_module
+from pathlib import Path
+from types import ModuleType
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel
+
+from domainkit.exceptions import ImproperlyConfigured
+
+if TYPE_CHECKING:
+    from domainkit.ddd import DeferredTask, DomainEvent, UnitOfWork
+
+CONFIG_MODULE = "apps"
+
+
+class DomainConfig:
+    """Describe one installed domain and its lifecycle hooks.
+
+    Each domain package may define exactly one subclass in its ``apps``
+    module; a package without one gets this base class. Override only the
+    hooks the domain needs.
+    """
+
+    label: str = ""
+    """Unique short name; defaults to the last part of the package path."""
+    verbose_name: str = ""
+    settings_class: type[BaseModel] | None = None
+    """Schema for this domain's settings, read from ``settings_name``."""
+
+    def __init__(self, name: str, module: ModuleType) -> None:
+        """Bind the config to the domain package ``name``."""
+        self.name = name
+        self.module = module
+        self.label = self.label or name.rpartition(".")[2]
+        if not self.label.isidentifier():
+            raise ImproperlyConfigured(
+                f"Domain label {self.label!r} is not a valid Python identifier."
+            )
+        self.verbose_name = self.verbose_name or self.label.replace("_", " ").title()
+
+    def __repr__(self) -> str:
+        """Show the class and the domain label."""
+        return f"<{type(self).__name__}: {self.label}>"
+
+    @property
+    def settings_name(self) -> str:
+        """Settings-module name holding this domain's settings, e.g. ``BILLING``."""
+        return self.label.upper()
+
+    @property
+    def path(self) -> Path:
+        """Directory of the domain package."""
+        return Path(next(iter(self.module.__path__)))
+
+    @classmethod
+    def create(cls, name: str) -> "DomainConfig":
+        """Import package ``name`` and instantiate its ``DomainConfig``."""
+        module = _import_domain(name)
+        config_module_name = f"{name}.{CONFIG_MODULE}"
+        try:
+            config_module = import_module(config_module_name)
+        except ModuleNotFoundError as exc:
+            if exc.name != config_module_name:
+                raise
+            return cls(name, module)
+        configs = [
+            value
+            for value in vars(config_module).values()
+            if isinstance(value, type)
+            and issubclass(value, DomainConfig)
+            and value.__module__ == config_module_name
+        ]
+        if len(configs) != 1:
+            raise ImproperlyConfigured(
+                f"{config_module_name!r} must define exactly one DomainConfig "
+                f"subclass, found {len(configs)}."
+            )
+        return configs[0](name, module)
+
+    def ready(self) -> None:
+        """Wire the domain once settings are loaded: ORM mappers, event handlers."""
+
+    async def startup(self) -> None:
+        """Open process resources such as clients and pools."""
+
+    async def shutdown(self) -> None:
+        """Release resources opened by ``startup``."""
+
+    async def check(self) -> None:
+        """Raise when the domain cannot serve traffic (readiness probe)."""
+
+    async def stage(
+        self,
+        uow: "UnitOfWork",
+        events: Sequence["DomainEvent"],
+        tasks: Sequence["DeferredTask"],
+    ) -> None:
+        """Add rows to a committing SQL unit of work (outbox, audit trail)."""
+
+
+def _import_domain(name: str) -> ModuleType:
+    """Import a domain package, explaining a missing one."""
+    try:
+        module = import_module(name)
+    except ModuleNotFoundError as exc:
+        if exc.name is not None and (
+            name == exc.name or name.startswith(f"{exc.name}.")
+        ):
+            raise ImproperlyConfigured(
+                f"Installed domain {name!r} cannot be imported."
+            ) from exc
+        raise
+    if not hasattr(module, "__path__"):
+        raise ImproperlyConfigured(f"Installed domain {name!r} must be a package.")
+    return module

domainkit/apps/registry.py

@@ -0,0 +1,135 @@
+"""The registry of installed domains (``django.apps.apps``)."""
+
+import difflib
+from collections.abc import AsyncIterator, Iterable, Iterator
+from contextlib import AsyncExitStack, asynccontextmanager
+from typing import Final, cast
+
+from pydantic import BaseModel, ValidationError
+
+from domainkit.apps.config import DomainConfig
+from domainkit.conf import describe_errors, settings, unwrap_settings
+from domainkit.exceptions import ImproperlyConfigured
+from domainkit.utils.readiness import failing_checks
+
+
+class DomainRegistry:
+    """Installed domains in ``INSTALLED_DOMAINS`` order."""
+
+    def __init__(self) -> None:
+        """Start empty; ``populate`` loads the domains."""
+        self._configs: dict[str, DomainConfig] = {}
+        self._settings_cache: dict[type[BaseModel], tuple[object, BaseModel]] = {}
+        self.ready = False
+
+    def populate(self, installed: Iterable[str]) -> None:
+        """Load every domain, validate its settings, then call ``ready()``.
+
+        Does nothing once the registry is ready; ``clear()`` starts over.
+        """
+        if self.ready:
+            return
+        configs: dict[str, DomainConfig] = {}
+        for name in installed:
+            config = DomainConfig.create(name)
+            if config.label in configs:
+                raise ImproperlyConfigured(
+                    f"Domain label {config.label!r} is not unique "
+                    f"({configs[config.label].name!r} and {name!r})."
+                )
+            configs[config.label] = config
+        self._configs = configs
+        self._settings_cache.clear()
+        self._check_settings()
+        for config in configs.values():
+            config.ready()
+        self.ready = True
+
+    def clear(self) -> None:
+        """Forget every domain (tests); the next ``populate`` loads them again."""
+        self._configs = {}
+        self._settings_cache.clear()
+        self.ready = False
+
+    def __iter__(self) -> Iterator[DomainConfig]:
+        """Iterate in ``INSTALLED_DOMAINS`` order."""
+        return iter(self._configs.values())
+
+    def __len__(self) -> int:
+        """Return the number of installed domains."""
+        return len(self._configs)
+
+    def get_domain_config(self, label: str) -> DomainConfig:
+        """Return the domain with ``label``."""
+        try:
+            return self._configs[label]
+        except KeyError:
+            raise LookupError(f"No installed domain with label {label!r}.") from None
+
+    def is_installed(self, name: str) -> bool:
+        """Report whether the package ``name`` is an installed domain."""
+        return any(config.name == name for config in self)
+
+    def settings[S: BaseModel](self, settings_class: type[S]) -> S:
+        """Return the validated settings of the domain that declares ``settings_class``.
+
+        Values are re-validated when ``override_settings`` replaces them.
+        """
+        config = next((c for c in self if c.settings_class is settings_class), None)
+        if config is None:
+            raise ImproperlyConfigured(
+                f"No installed domain declares {settings_class.__qualname__}."
+            )
+        raw = getattr(settings, config.settings_name, None)
+        cached = self._settings_cache.get(settings_class)
+        if cached is not None and cached[0] is raw:
+            return cast(S, cached[1])
+        try:
+            value = settings_class.model_validate({} if raw is None else raw)
+        except ValidationError as exc:
+            raise ImproperlyConfigured(
+                f"Invalid {config.settings_name} settings:\n{describe_errors(exc)}"
+            ) from None
+        self._settings_cache[settings_class] = (raw, value)
+        return value
+
+    @asynccontextmanager
+    async def lifespan(self) -> AsyncIterator[None]:
+        """Start domains in order and stop started ones in reverse, even on failure."""
+        async with AsyncExitStack() as stack:
+            for config in self:
+                await config.startup()
+                stack.push_async_callback(config.shutdown)
+            yield
+
+    async def check(self, seconds: float) -> list[str]:
+        """Run every domain's readiness check; return the labels that failed."""
+        return await failing_checks(
+            {config.label: config.check for config in self}, seconds
+        )
+
+    def _check_settings(self) -> None:
+        """Validate domain settings and reject names nothing declares."""
+        claimed = set()
+        for config in self:
+            if config.settings_class is not None:
+                claimed.add(config.settings_name)
+                self.settings(config.settings_class)
+        current = unwrap_settings()
+        if unknown := sorted(set(current.model_extra or {}) - claimed):
+            known = [*type(current).model_fields, *claimed]
+            raise ImproperlyConfigured(
+                f"Unknown settings in {current.SETTINGS_MODULE!r}: "
+                + ", ".join(_describe_unknown(name, known) for name in unknown)
+                + ". Declare them in a domain's settings_class or SETTINGS_CLASS."
+            )
+
+
+def _describe_unknown(name: str, known: list[str]) -> str:
+    """Name an unknown setting and suggest the closest known one."""
+    matches = difflib.get_close_matches(name, known, n=1)
+    return f"{name} (did you mean {matches[0]}?)" if matches else name
+
+
+registry: Final = DomainRegistry()
+"""The process-wide registry populated by ``domainkit.setup()``."""

domainkit/architecture.py

@@ -0,0 +1,193 @@
+"""Enforce the dependency rules of a domain-driven package layout.
+
+Each domain package has four layers; dependencies point inward only::
+
+    api  ->  infrastructure  ->  application  ->  domain
+
+- ``domain``: the standard library, ``domainkit.ddd``, and its own domain layer.
+  No frameworks, no I/O, no settings.
+- ``application``: no ``infrastructure`` or ``api`` code, and no web or
+  database libraries; it reaches storage through repository ports.
+- ``infrastructure``: no ``api`` code and no web libraries.
+- Another domain may be used only through its ``application`` layer or its
+  ``domain.events`` (bounded contexts stay decoupled).
+
+``python manage.py check`` and the test suite run these rules for every
+installed domain. Adjust the tables below to change the policy project-wide.
+"""
+
+import ast
+import sys
+from collections.abc import Iterable, Iterator, Sequence
+from dataclasses import dataclass
+from importlib.util import find_spec
+from pathlib import Path
+from typing import Final
+
+LAYERS: Final = ("domain", "application", "infrastructure", "api")
+
+DOMAIN_ALLOWED_PREFIXES: Final = ("domainkit.ddd",)
+"""Non-stdlib modules a domain layer may import (besides its own layer)."""
+
+FORBIDDEN_LIBRARIES: Final = {
+    "application": (
+        "fastapi",
+        "starlette",
+        "sqlalchemy",
+        "alembic",
+        "domainkit.db",
+        "domainkit.http",
+    ),
+    "infrastructure": ("fastapi", "starlette", "domainkit.http"),
+}
+"""Libraries each layer must not import."""
+
+FORBIDDEN_LAYERS: Final = {
+    "application": ("infrastructure", "api"),
+    "infrastructure": ("api",),
+}
+"""Layers of the same domain that each layer must not import."""
+
+PUBLIC_SURFACE: Final = ("application", "domain.events")
+"""Parts of a domain that other domains may import."""
+
+FRAMEWORK_PACKAGES: Final = ("domainkit",)
+"""Installed framework apps (``domainkit.contrib.*``) are services, not domains:
+they are neither checked nor protected by the cross-domain rule."""
+
+
+@dataclass(frozen=True, slots=True)
+class Violation:
+    """One import that breaks a rule."""
+
+    module: str
+    imported: str
+    rule: str
+
+    def __str__(self) -> str:
+        """Render as ``module imports name: rule``."""
+        return f"{self.module} imports {self.imported}: {self.rule}"
+
+
+def iter_imports(package: str) -> Iterator[tuple[str, str]]:
+    """Yield ``(module, imported)`` for every import in ``package``'s files.
+
+    Relative imports are resolved, and ``from x import y`` yields both ``x``
+    and ``x.y`` because ``y`` may be a submodule. Imports under
+    ``TYPE_CHECKING`` count: they are dependencies too.
+    """
+    for path, module in _modules(package):
+        tree = ast.parse(path.read_text(encoding="utf-8"), filename=str(path))
+        is_package = path.name == "__init__.py"
+        for node in ast.walk(tree):
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    yield module, alias.name
+            elif isinstance(node, ast.ImportFrom):
+                base = _resolve(module, is_package, node.level, node.module)
+                yield module, base
+                for alias in node.names:
+                    if alias.name != "*":
+                        yield module, f"{base}.{alias.name}"
+
+
+def check_domain(package: str, installed: Sequence[str] = ()) -> list[Violation]:
+    """Return the rule violations in domain ``package``.
+
+    ``installed`` lists the other domain packages, for the cross-domain rule.
+    """
+    others = [
+        name
+        for name in installed
+        if name != package and not _within(name, FRAMEWORK_PACKAGES)
+    ]
+    violations = []
+    for module, imported in iter_imports(package):
+        layer = _layer(package, module)
+        rule = _cross_domain_rule(imported, others) or _layer_rule(
+            package, layer, imported
+        )
+        if rule:
+            violations.append(Violation(module, imported, rule))
+    return list(dict.fromkeys(violations))
+
+
+def check_domains(installed: Iterable[str]) -> list[Violation]:
+    """Check every domain in ``installed``."""
+    names = [name for name in installed if not _within(name, FRAMEWORK_PACKAGES)]
+    return [violation for name in names for violation in check_domain(name, names)]
+
+
+def _layer_rule(package: str, layer: str | None, imported: str) -> str | None:
+    """Return the broken layer rule, if any."""
+    if layer == "domain":
+        own = f"{package}.domain"
+        allowed = (own, *DOMAIN_ALLOWED_PREFIXES)
+        if not _is_stdlib(imported) and not _within(imported, allowed):
+            return (
+                "the domain layer may import only the standard library, "
+                "domainkit.ddd, and its own domain layer"
+            )
+        return None
+    if layer is None:
+        return None
+    forbidden = [f"{package}.{name}" for name in FORBIDDEN_LAYERS.get(layer, ())]
+    if _within(imported, forbidden):
+        return f"the {layer} layer must not depend on outer layers"
+    if _within(imported, FORBIDDEN_LIBRARIES.get(layer, ())):
+        return f"the {layer} layer must not use {imported.partition('.')[0]}"
+    return None
+
+
+def _cross_domain_rule(imported: str, others: Sequence[str]) -> str | None:
+    """Return the broken cross-domain rule, if any."""
+    for other in others:
+        if _within(imported, (other,)) and imported != other:
+            public = tuple(f"{other}.{part}" for part in PUBLIC_SURFACE)
+            if not _within(imported, public):
+                return (
+                    f"use another domain only through {other}.application "
+                    f"or {other}.domain.events"
+                )
+    return None
+
+
+def _modules(package: str) -> Iterator[tuple[Path, str]]:
+    """Yield ``(path, dotted name)`` for each Python file of ``package``."""
+    spec = find_spec(package)
+    if spec is None or not spec.submodule_search_locations:
+        raise ValueError(f"{package!r} is not an importable package.")
+    for location in spec.submodule_search_locations:
+        root = Path(location)
+        for path in sorted(root.rglob("*.py")):
+            parts = path.relative_to(root).with_suffix("").parts
+            if parts[-1] == "__init__":
+                parts = parts[:-1]
+            yield path, ".".join((package, *parts))
+
+
+def _resolve(module: str, is_package: bool, level: int, target: str | None) -> str:
+    """Turn a possibly relative ``from`` import into an absolute module name."""
+    if level == 0:
+        return target or ""
+    base = module.split(".")
+    if not is_package:
+        base = base[:-1]
+    base = base[: len(base) - (level - 1)]
+    return ".".join([*base, target] if target else base)
+
+
+def _layer(package: str, module: str) -> str | None:
+    """Return the layer ``module`` belongs to, or None for top-level modules."""
+    first = module.removeprefix(f"{package}.").partition(".")[0]
+    return first if module != package and first in LAYERS else None
+
+
+def _within(name: str, prefixes: Iterable[str]) -> bool:
+    """Report whether ``name`` is one of ``prefixes`` or inside one."""
+    return any(name == prefix or name.startswith(f"{prefix}.") for prefix in prefixes)
+
+
+def _is_stdlib(name: str) -> bool:
+    """Report whether ``name`` belongs to the standard library."""
+    return name.partition(".")[0] in sys.stdlib_module_names

domainkit/conf/__init__.py

@@ -0,0 +1,58 @@
+"""Django-style settings access.
+
+Select a module with ``<PREFIX>SETTINGS_MODULE`` (for example
+``BILLING_API_SETTINGS_MODULE=config.settings.local``; the prefix comes
+from the project name), in the environment or the ``.env`` file, then read
+values anywhere::
+
+    from domainkit.conf import settings
+
+    settings.DEBUG
+    settings.DATABASES["default"].ECHO
+
+Settings are loaded on first access, so importing this module has no side
+effects.
+"""
+
+from typing import Final, cast
+
+from domainkit.conf.env import Env
+from domainkit.conf.global_settings import (
+    DEFAULT_DB_ALIAS,
+    DatabaseConfig,
+    Settings,
+)
+from domainkit.conf.lazy import (
+    SETTINGS_MODULE_VARIABLE,
+    UNSET,
+    LazySettings,
+    describe_errors,
+    load_settings,
+)
+
+_lazy: Final = LazySettings(Env())
+
+settings: Final = cast(Settings, _lazy)
+"""Typed, lazily loaded settings for the selected module."""
+
+configure: Final = _lazy.configure
+override_settings: Final = _lazy.override
+reset_settings: Final = _lazy.reset
+unwrap_settings: Final = _lazy.unwrap
+use_settings: Final = _lazy.use
+
+__all__ = [
+    "DEFAULT_DB_ALIAS",
+    "SETTINGS_MODULE_VARIABLE",
+    "UNSET",
+    "DatabaseConfig",
+    "Settings",
+    "configure",
+    "describe_errors",
+    "load_settings",
+    "override_settings",
+    "reset_settings",
+    "settings",
+    "unwrap_settings",
+    "use_settings",
+]