xtr-dependency-injection 1.0.0__py3-none-any.whl

xtr_dependency_injection/__init__.py

@@ -0,0 +1,72 @@
+"""A Symfony-style bundle and kernel layer for the xtr libraries, built on wireup.
+
+Each library ships one bundle; installed bundles register themselves; an
+application is one ``Kernel("app")`` line plus decorators. What comes out is a
+plain wireup ``AsyncContainer``: this package decides *what* goes into it, in
+*which order*, *for which environment*, and runs the lifecycle around it.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from .builder import Definition, Origin, ServiceKey
+from .builder.container_builder import ContainerBuilder
+from .builder.service_configurator import ServiceConfigurator
+from .bundle import Bundle, BundleMetadata, NoConfig, as_bundle
+from .config import configure, env, parameters
+from .config.config_prepender import ConfigPrepender
+from .decorator import (
+    Inner,
+    as_decorator,
+    compiler_pass,
+    exclude,
+    on_boot,
+    on_shutdown,
+    when,
+    when_not,
+)
+from .diagnostics import KernelReport
+from .discovery import DiscoveredBundle, discover_bundles
+from .kernel import BootedKernel, CompiledKernel, Kernel, KernelInterface
+from .runtime import ServiceLocator, ServicesResetter, bind_callable
+from .scan import DEFAULT_EXCLUDES
+from .standalone import injectables
+
+__all__ = [
+    "DEFAULT_EXCLUDES",
+    "BootedKernel",
+    "Bundle",
+    "BundleMetadata",
+    "CompiledKernel",
+    "ConfigPrepender",
+    "ContainerBuilder",
+    "Definition",
+    "DiscoveredBundle",
+    "Inner",
+    "Kernel",
+    "KernelInterface",
+    "KernelReport",
+    "NoConfig",
+    "Origin",
+    "ServiceConfigurator",
+    "ServiceKey",
+    "ServiceLocator",
+    "ServicesResetter",
+    "as_bundle",
+    "as_decorator",
+    "bind_callable",
+    "compiler_pass",
+    "configure",
+    "discover_bundles",
+    "env",
+    "exclude",
+    "injectables",
+    "on_boot",
+    "on_shutdown",
+    "parameters",
+    "when",
+    "when_not",
+]
+
+__version__ = version("xtr-dependency-injection")

xtr_dependency_injection/builder/__init__.py

@@ -0,0 +1,7 @@
+"""Collecting service definitions: per bundle while loading, as a whole while processing."""
+
+from __future__ import annotations
+
+from .definition import Definition, Lifetime, Origin, ServiceKey
+
+__all__ = ["Definition", "Lifetime", "Origin", "ServiceKey"]

xtr_dependency_injection/builder/autoconfigurator.py

@@ -0,0 +1,71 @@
+"""Autoconfiguration: a bundle reacting to what the scan found.
+
+A bundle registers a *reader* — metadata found on a candidate, empty for no
+match — and an *apply*, called once per metadata item. The console bundle
+reads ``@as_command`` descriptors and registers each command; the scan never
+needs to know what a command is.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, TypeAlias
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Iterable, Sequence
+
+    from xtr_dependency_injection.scan.scanned_object import ScannedObject
+
+    from .service_configurator import ServiceConfigurator
+
+__all__ = ["Apply", "Autoconfigurator", "Reader", "run_autoconfigurators"]
+
+# What a reader finds is only meaningful to the bundle that reads it, so the
+# builder passes it through untyped.
+Reader: TypeAlias = "Callable[[object], Iterable[Any]]"  # pyright: ignore[reportExplicitAny]
+Apply: TypeAlias = "Callable[[object, Any, ServiceConfigurator], None]"  # pyright: ignore[reportExplicitAny]
+
+
+@dataclass(frozen=True, slots=True)
+class Autoconfigurator:
+    """One ``services.autoconfigure(reader, apply)`` call, and the bundle that made it."""
+
+    owner: str
+    reader: Reader
+    apply: Apply
+
+
+def run_autoconfigurators(
+    autoconfigurators: Sequence[Autoconfigurator],
+    candidates: Sequence[ScannedObject],
+    configurator_for: Callable[[str, ScannedObject], ServiceConfigurator],
+) -> None:
+    """Run every autoconfigurator over every candidate.
+
+    The outer loop is over autoconfigurators, in bundle order and then
+    registration order; the inner loop over candidates, in scan order.
+
+    Args:
+        autoconfigurators: What bundles registered while loading.
+        candidates: The service candidates of every scan.
+        configurator_for: The configurator ``apply`` receives, for a bundle
+            and the candidate it applies to.
+
+    Raises:
+        Exception: Whatever a reader raised — a reader failing is a bug —
+            with a note naming the reader and the candidate.
+    """
+    for autoconfigurator in autoconfigurators:
+        for candidate in candidates:
+            try:
+                found = tuple(autoconfigurator.reader(candidate.obj))
+            except Exception as error:
+                reader = getattr(autoconfigurator.reader, "__qualname__", "reader")
+                where = f"of bundle {autoconfigurator.owner} on {candidate.name}"
+                error.add_note(f"raised by autoconfigure reader {reader} {where}")
+                raise
+            if not found:
+                continue
+            services = configurator_for(autoconfigurator.owner, candidate)
+            for metadata in found:  # pyright: ignore[reportAny]
+                autoconfigurator.apply(candidate.obj, metadata, services)

xtr_dependency_injection/builder/conflict_policy.py

@@ -0,0 +1,94 @@
+"""Who wins when two definitions claim one key.
+
+Checked before wireup ever sees the definitions, so an error names both
+origins instead of a bare duplicate:
+
+- the application over a bundle: the application wins, silently, and the
+  report records the override (Symfony's parity);
+- bundle against bundle: an error, unless it goes through
+  ``builder.replace``;
+- application against application: an error.
+"""
+
+from __future__ import annotations
+
+from dataclasses import replace
+from typing import TYPE_CHECKING, final
+
+from xtr_dependency_injection.exception import DuplicateServiceError
+
+if TYPE_CHECKING:
+    from .definition import Definition, Origin, ServiceKey
+
+__all__ = ["DefinitionStore"]
+
+
+@final
+class DefinitionStore:
+    """Every definition of one build, by key, in declaration order."""
+
+    __slots__ = ("_counter", "_definitions", "_overrides", "_sequence")
+
+    def __init__(self) -> None:
+        """Start empty."""
+        self._definitions: dict[ServiceKey, Definition] = {}
+        self._overrides: dict[ServiceKey, list[Origin]] = {}
+        self._sequence: dict[ServiceKey, int] = {}
+        self._counter = 0
+
+    def add(self, definition: Definition) -> None:
+        """Add ``definition``, applying the conflict policy.
+
+        Raises:
+            DuplicateServiceError: If neither definition may override the
+                other.
+        """
+        key = definition.key
+        existing = self._definitions.get(key)
+        if existing is None:
+            self._insert(definition)
+            return
+        if definition.origin.kind == "app" and existing.origin.kind != "app":
+            self._overrides.setdefault(key, []).append(existing.origin)
+            self._insert(definition)
+        elif existing.origin.kind == "app" and definition.origin.kind != "app":
+            self._overrides.setdefault(key, []).append(definition.origin)
+        else:
+            raise DuplicateServiceError(key, existing.origin, definition.origin)
+
+    def replace(self, definition: Definition) -> None:
+        """Replace the definition of ``definition.key`` on purpose, keeping its position."""
+        existing = self._definitions[definition.key]
+        self._overrides.setdefault(definition.key, []).append(existing.origin)
+        self._definitions[definition.key] = definition
+
+    def update(self, key: ServiceKey, **changes: object) -> None:
+        """Change fields of the definition of ``key`` without it counting as an override."""
+        self._definitions[key] = replace(self._definitions[key], **changes)
+
+    def remove(self, key: ServiceKey) -> None:
+        """Forget the definition of ``key``."""
+        del self._definitions[key]
+        _ = self._sequence.pop(key, None)
+
+    def get(self, key: ServiceKey) -> Definition | None:
+        """Return the definition of ``key``, or ``None``."""
+        return self._definitions.get(key)
+
+    def has_provider(self, provider: object) -> bool:
+        """Return whether any definition is provided by this very object."""
+        return any(definition.provider is provider for definition in self._definitions.values())
+
+    def definitions(self) -> tuple[Definition, ...]:
+        """Return every definition, in declaration order."""
+        ordered = sorted(self._definitions.values(), key=lambda d: self._sequence[d.key])
+        return tuple(ordered)
+
+    def overrides_of(self, key: ServiceKey) -> tuple[Origin, ...]:
+        """Return the origins of the definitions ``key``'s replaced or outranked."""
+        return tuple(self._overrides.get(key, ()))
+
+    def _insert(self, definition: Definition) -> None:
+        self._counter += 1
+        self._definitions[definition.key] = definition
+        self._sequence[definition.key] = self._counter

xtr_dependency_injection/builder/container_builder.py

@@ -0,0 +1,125 @@
+"""What ``Bundle.process`` and ``@compiler_pass`` receive: every definition, still mutable.
+
+By now every bundle has loaded and autoconfiguration has run, so a pass sees
+the whole container — what exists, which config each bundle resolved — and
+may still add, replace, remove or decorate.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeVar, cast, final, overload
+
+from xtr_dependency_injection.exception import MissingBundleError, UnknownConfigTypeError
+
+from .definition import Definition, Lifetime
+from .service_configurator import DecorationRequest, Kind, ServiceConfigurator, kind_of
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Hashable
+
+__all__ = ["ContainerBuilder"]
+
+C = TypeVar("C")
+
+
+@final
+class ContainerBuilder(ServiceConfigurator):
+    """A whole-container view for processing, on behalf of one bundle or compiler pass.
+
+    ``scan`` and ``autoconfigure`` are refused here: both have already run.
+    """
+
+    def has(self, as_type: type, /, qualifier: Hashable | None = None) -> bool:
+        """Return whether a service is defined for ``(as_type, qualifier)``."""
+        return self._state.store.get((as_type, qualifier)) is not None
+
+    def definitions(self, as_type: type | None = None, /) -> tuple[Definition, ...]:
+        """Return every definition, or those provided under ``as_type``, in declaration order."""
+        every = self._state.store.definitions()
+        return every if as_type is None else tuple(d for d in every if d.key[0] is as_type)
+
+    @overload
+    def config_of(self, bundle: str, /) -> object: ...
+    @overload
+    def config_of(self, bundle: type[C], /) -> C: ...
+    def config_of(self, bundle: str | type[C], /) -> object:
+        """Return the resolved config of a bundle, by name or by config type.
+
+        Raises:
+            MissingBundleError: If no active bundle has that name.
+            UnknownConfigTypeError: If no active bundle has that config type.
+        """
+        configs = self._state.configs
+        if isinstance(bundle, str):
+            if bundle not in configs:
+                raise MissingBundleError(bundle, str(self._origin), "it is not active")
+            return configs[bundle]
+        for value in configs.values():
+            if type(value) is bundle:
+                return cast("C", value)
+        raise UnknownConfigTypeError(f"config_of by {self._origin}", bundle, None)
+
+    def replace(
+        self,
+        as_type: type,
+        provider: object,
+        /,
+        *,
+        qualifier: Hashable | None = None,
+        kind: Kind | None = None,
+        lifetime: Lifetime | None = None,
+    ) -> None:
+        """Replace the service ``(as_type, qualifier)`` with ``provider``, on purpose.
+
+        The kind is inferred from ``provider`` unless given; the lifetime, and
+        the position in collections, stay the replaced definition's.
+
+        Raises:
+            UnknownServiceError: If no such service is defined.
+        """
+        self._allow("replace", "process")
+        existing = self._require((as_type, qualifier), "replace")
+        self._state.store.replace(
+            Definition(
+                key=existing.key,
+                provider=provider,
+                kind=kind if kind is not None else kind_of(provider),
+                lifetime=lifetime if lifetime is not None else existing.lifetime,
+                origin=self._origin,
+                priority=existing.priority,
+                reset_method=existing.reset_method,
+            )
+        )
+
+    def remove(self, as_type: type, /, *, qualifier: Hashable | None = None) -> None:
+        """Remove the service ``(as_type, qualifier)``.
+
+        Raises:
+            UnknownServiceError: If no such service is defined.
+        """
+        self._allow("remove", "process")
+        definition = self._require((as_type, qualifier), "remove")
+        self._state.store.remove(definition.key)
+
+    def decorate(
+        self,
+        as_type: type,
+        decorator: type | Callable[..., object],
+        /,
+        *,
+        qualifier: Hashable | None = None,
+        priority: int = 0,
+    ) -> None:
+        """Decorate the service ``(as_type, qualifier)`` with ``decorator``.
+
+        The decorator takes the service's place, and receives it through its
+        one ``Inner[as_type]`` parameter.
+
+        Raises:
+            UnknownServiceError: If no such service is defined.
+        """
+        self._allow("decorate", "process")
+        key = self._require((as_type, qualifier), "decorate").key
+        name = f"{getattr(decorator, '__module__', '?')}:{getattr(decorator, '__qualname__', '?')}"
+        order = len(self._state.decorations)
+        self._state.decorations.append(DecorationRequest(key, decorator, priority, name, order))

xtr_dependency_injection/builder/definition.py

@@ -0,0 +1,67 @@
+"""What the builder holds: one definition per service key, and where each came from."""
+
+from __future__ import annotations
+
+from collections.abc import Hashable
+from dataclasses import dataclass
+from typing import Literal, TypeAlias
+
+from typing_extensions import override
+
+__all__ = ["Definition", "Lifetime", "Origin", "ServiceKey"]
+
+ServiceKey: TypeAlias = tuple[type, Hashable | None]
+"""``(provided type, qualifier)`` — the identity wireup registers a service under."""
+
+Lifetime: TypeAlias = Literal["singleton", "scoped", "transient"]
+"""How long wireup keeps what a definition builds."""
+
+
+@dataclass(frozen=True, slots=True)
+class Origin:
+    """Who contributed a definition: the kernel, a bundle, or the application.
+
+    Attributes:
+        kind: ``"kernel"``, ``"bundle"`` or ``"app"``.
+        name: The bundle's name, or ``module:qualname`` of the application
+            object.
+        note: How it got there, when not directly — e.g.
+            ``"via autoconfigure of app.x:Y"``.
+    """
+
+    kind: Literal["kernel", "bundle", "app"]
+    name: str
+    note: str | None = None
+
+    @override
+    def __str__(self) -> str:
+        described = f"{self.kind} {self.name}"
+        return described if self.note is None else f"{described} ({self.note})"
+
+
+@dataclass(frozen=True, slots=True)
+class Definition:
+    """One service as the builder knows it, before it is compiled for wireup.
+
+    Attributes:
+        key: The type and qualifier it is provided under.
+        provider: The class, factory function or instance that builds it.
+        kind: How ``provider`` is registered: ``"class"``, ``"factory"``,
+            ``"instance"``, or ``"declared"`` for an object already marked
+            with wireup's ``@injectable``.
+        lifetime: How long wireup keeps what it builds.
+        origin: Who contributed it.
+        priority: Its position among definitions of one origin group:
+            higher comes first in ``Sequence[T]`` and ``Mapping``
+            collections.
+        reset_method: The method ``ServicesResetter`` calls on it, when it is
+            resettable.
+    """
+
+    key: ServiceKey
+    provider: object
+    kind: Literal["class", "factory", "instance", "declared"]
+    lifetime: Lifetime
+    origin: Origin
+    priority: int = 0
+    reset_method: str | None = None

xtr_dependency_injection/builder/service_configurator.py

@@ -0,0 +1,232 @@
+"""What ``Bundle.load`` receives: a bundle's view of the services being defined.
+
+One configurator per bundle, so every definition knows its origin. Each
+operation belongs to phases: ``scan`` and ``autoconfigure`` only mean
+something while bundles load — scanning and autoconfiguration run right
+after — and nothing may change once the container is compiled.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Hashable, Mapping
+from dataclasses import dataclass, field
+from types import ModuleType
+from typing import Literal
+
+from xtr_dependency_injection.compiler._wireup_bridge import declaration_of, key_type
+from xtr_dependency_injection.exception import (
+    BuilderFrozenError,
+    BuilderPhaseError,
+    UnknownServiceError,
+)
+
+from .autoconfigurator import Apply, Autoconfigurator, Reader
+from .conflict_policy import DefinitionStore
+from .definition import Definition, Lifetime, Origin, ServiceKey
+
+__all__ = [
+    "BuildState",
+    "DecorationRequest",
+    "ResettableRequest",
+    "ServiceConfigurator",
+    "kind_of",
+]
+
+Phase = Literal["load", "autoconfigure", "process", "frozen"]
+Kind = Literal["class", "factory", "instance", "declared"]
+
+
+@dataclass(frozen=True, slots=True)
+class ResettableRequest:
+    """A ``resettable()`` call, resolved against the final definitions."""
+
+    key: ServiceKey
+    method: str
+
+
+@dataclass(frozen=True, slots=True)
+class DecorationRequest:
+    """A decoration asked for by ``builder.decorate`` or ``@as_decorator``."""
+
+    key: ServiceKey
+    decorator: type | Callable[..., object]
+    priority: int
+    name: str
+    order: int
+
+
+@dataclass(slots=True)
+class BuildState:
+    """Everything one build's configurators and builders share.
+
+    Attributes:
+        env: The environment being built.
+        debug: Whether the kernel runs in debug mode.
+        bundles: Active bundle names, in dependency order.
+        configs: Resolved config by bundle name.
+        phase: The current phase.
+        store: The definitions.
+        late_scans: Resources ``scan()`` asked for, with the asking bundle.
+        autoconfigurators: What ``autoconfigure()`` registered.
+        parameters: Parameters bundles contributed, with their source.
+        resettables: ``resettable()`` requests.
+        decorations: Decoration requests.
+    """
+
+    env: str
+    debug: bool
+    bundles: tuple[str, ...]
+    configs: Mapping[str, object]
+    phase: Phase = "load"
+    store: DefinitionStore = field(default_factory=DefinitionStore)
+    late_scans: list[tuple[str, tuple[str | ModuleType, ...]]] = field(default_factory=list)
+    autoconfigurators: list[Autoconfigurator] = field(default_factory=list)
+    parameters: list[tuple[str, Mapping[str, object]]] = field(default_factory=list)
+    resettables: list[ResettableRequest] = field(default_factory=list)
+    decorations: list[DecorationRequest] = field(default_factory=list)
+
+
+class ServiceConfigurator:
+    """Defines services on behalf of one bundle.
+
+    Attributes:
+        env: The environment being built.
+        debug: Whether the kernel runs in debug mode.
+    """
+
+    __slots__: tuple[str, ...] = ("_origin", "_state", "debug", "env")
+
+    env: str
+    debug: bool
+    _state: BuildState
+    _origin: Origin
+
+    def __init__(self, state: BuildState, origin: Origin) -> None:
+        """Define services into ``state``, as ``origin``."""
+        self._state = state
+        self._origin = origin
+        self.env = state.env
+        self.debug = state.debug
+
+    def has_bundle(self, name: str) -> bool:
+        """Return whether the bundle ``name`` is active in this build."""
+        return name in self._state.bundles
+
+    def instance(
+        self,
+        obj: object,
+        /,
+        *,
+        as_type: type | None = None,
+        qualifier: Hashable | None = None,
+        priority: int = 0,
+    ) -> None:
+        """Provide ``obj`` itself, under ``as_type`` (default: its own type)."""
+        self._allow("instance", "load", "autoconfigure", "process")
+        key = (as_type if as_type is not None else type(obj), qualifier)
+        self._add(key, obj, "instance", "singleton", priority)
+
+    def factory(
+        self,
+        fn: Callable[..., object],
+        /,
+        *,
+        lifetime: Lifetime = "singleton",
+        as_type: type | None = None,
+        qualifier: Hashable | None = None,
+        priority: int = 0,
+    ) -> None:
+        """Provide what ``fn`` returns — or yields, cleaned up after — under its return type.
+
+        Raises:
+            TypeError: If ``fn`` is not a plain function.
+            FactoryReturnTypeIsEmptyError: If ``fn`` has no return
+                annotation.
+        """
+        self._allow("factory", "load", "autoconfigure", "process")
+        if not inspect.isfunction(fn):
+            msg = f"factory() takes a function, not {fn!r}"
+            raise TypeError(msg)
+        self._add((key_type(fn, as_type), qualifier), fn, "factory", lifetime, priority)
+
+    def service(
+        self,
+        cls: type,
+        /,
+        *,
+        lifetime: Lifetime = "singleton",
+        as_type: type | None = None,
+        qualifier: Hashable | None = None,
+        priority: int = 0,
+    ) -> None:
+        """Provide ``cls``, built by the container from its constructor.
+
+        Does nothing when a definition for ``cls`` itself already exists — as
+        when the application marked it ``@injectable`` and a bundle's
+        autoconfiguration registers it again.
+        """
+        self._allow("service", "load", "autoconfigure", "process")
+        if self._state.store.has_provider(cls):
+            return
+        key = (as_type if as_type is not None else cls, qualifier)
+        self._add(key, cls, "class", lifetime, priority)
+
+    def scan(self, *resources: str | ModuleType) -> None:
+        """Scan ``resources`` too, once every bundle has loaded, as this bundle's.
+
+        This is how a bundle scans a module only when a peer is active.
+        """
+        self._allow("scan", "load")
+        self._state.late_scans.append((self._origin.name, resources))
+
+    def autoconfigure(self, reader: Reader, apply: Apply) -> None:
+        """Call ``apply`` for every metadata item ``reader`` finds on a scanned candidate."""
+        self._allow("autoconfigure", "load")
+        self._state.autoconfigurators.append(Autoconfigurator(self._origin.name, reader, apply))
+
+    def parameters(self, values: Mapping[str, object], /) -> None:
+        """Merge ``values`` into the parameters, read with ``Inject(config=...)``."""
+        self._allow("parameters", "load", "autoconfigure", "process")
+        self._state.parameters.append((str(self._origin), values))
+
+    def resettable(
+        self, as_type: type, /, *, qualifier: Hashable | None = None, method: str = "reset"
+    ) -> None:
+        """Have ``ServicesResetter`` call ``method`` on the service, once it is built.
+
+        Resolved after every definition is final, so the order relative to
+        the service's own definition does not matter.
+        """
+        self._allow("resettable", "load", "autoconfigure", "process")
+        self._state.resettables.append(ResettableRequest((as_type, qualifier), method))
+
+    def _add(
+        self, key: ServiceKey, provider: object, kind: Kind, lifetime: Lifetime, priority: int
+    ) -> None:
+        definition = Definition(key, provider, kind, lifetime, self._origin, priority)
+        self._state.store.add(definition)
+
+    def _allow(self, operation: str, *phases: Phase) -> None:
+        phase = self._state.phase
+        if phase == "frozen":
+            raise BuilderFrozenError(operation)
+        if phase not in phases:
+            raise BuilderPhaseError(operation, phase)
+
+    def _require(self, key: ServiceKey, operation: str) -> Definition:
+        definition = self._state.store.get(key)
+        if definition is None:
+            raise UnknownServiceError(key, operation)
+        return definition
+
+
+def kind_of(provider: object) -> Kind:
+    """Return how ``provider`` is registered, judged from what it is."""
+    if declaration_of(provider) is not None:
+        return "declared"
+    if isinstance(provider, type):
+        return "class"
+    if inspect.isfunction(provider):
+        return "factory"
+    return "instance"

xtr_dependency_injection/bundle/__init__.py

@@ -0,0 +1,9 @@
+"""Declaring bundles: the base class, its decorator, and what the decorator records."""
+
+from __future__ import annotations
+
+from .as_bundle import as_bundle
+from .bundle import Bundle, NoConfig
+from .bundle_metadata import BundleMetadata
+
+__all__ = ["Bundle", "BundleMetadata", "NoConfig", "as_bundle"]