idunn 0.0.1__py3-none-any.whl

idunn/__init__.py

@@ -0,0 +1,34 @@
+"""Idunn: tiny constructor-time dependency inversion for Python.
+
+The entire public surface lives here: the three decorators (:func:`Port`,
+:func:`Adapter`, :func:`Invert`), the :class:`Idunn` container, the
+:class:`LifecycleEnum` you hand to ``@Adapter``, and the :class:`IdunnError`
+exception hierarchy you catch. Everything else is internal plumbing.
+"""
+
+from .app import Adapter, Idunn, Invert, Port
+from .domain import (
+  AdapterNotFoundError,
+  DiscoveryError,
+  IdunnError,
+  InjectionCycleError,
+  InvalidAdapterError,
+  InvalidPortError,
+  LifecycleEnum,
+  MissingTypeHintError,
+)
+
+__all__ = [
+  'Adapter',
+  'AdapterNotFoundError',
+  'DiscoveryError',
+  'Idunn',
+  'IdunnError',
+  'InjectionCycleError',
+  'InvalidAdapterError',
+  'InvalidPortError',
+  'Invert',
+  'LifecycleEnum',
+  'MissingTypeHintError',
+  'Port',
+]

idunn/app/__init__.py

@@ -0,0 +1,6 @@
+"""Application layer: the @Port/@Adapter/@Invert decorators and the Idunn singleton."""
+
+from .decorators import Adapter, Invert, Port
+from .idunn import Idunn
+
+__all__ = ['Adapter', 'Idunn', 'Invert', 'Port']

idunn/app/decorators.py

@@ -0,0 +1,137 @@
+"""The @Port, @Adapter, and @Invert decorators."""
+
+import functools
+import inspect
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any, TypeVar, get_type_hints, overload, runtime_checkable
+
+from idunn.domain import AdapterDeclaration, InvalidAdapterError, InvalidPortError, LifecycleEnum
+from idunn.internal import DecoratorSupport
+
+from .idunn import Idunn
+
+T = TypeVar('T', bound=type[Any])
+Init = Callable[..., None]
+
+
+def Port(cls: T) -> T:
+  """Mark a Protocol as an Idunn port."""
+  if not getattr(cls, '_is_protocol', False):
+    message = f'@Port can only be applied to Protocol classes: {cls.__qualname__}'
+    raise InvalidPortError(message)
+
+  cls.__idunn_port__ = True
+  return runtime_checkable(cls)
+
+
+def Adapter(
+  port: type[Any],
+  *,
+  key: str | None = None,
+  lifecycle: LifecycleEnum | str = LifecycleEnum.TRANSIENT,
+  envs: Iterable[str] | str | None = None,
+) -> Callable[[T], T]:
+  """Declare a concrete class as an adapter for a port.
+
+  Without ``key`` the adapter is *unkeyed*: it answers plain ``@Invert`` injection
+  — exactly one unkeyed adapter may be active per port in any environment.
+
+  With ``key`` the adapter is *opt-in*: it answers only ``@Invert(keys={...})`` and
+  is ignored by unkeyed resolution, so it never competes with the plain
+  implementation.
+  """
+  if not getattr(port, '__idunn_port__', False):
+    message = f'Adapter port is not marked with @Port: {port.__qualname__}'
+    raise InvalidPortError(message)
+
+  lifecycle_value = LifecycleEnum(lifecycle)
+  env_values = DecoratorSupport.normalize_envs(envs)
+
+  def decorate(cls: T) -> T:
+    if not isinstance(cls, type):
+      message = f'@Adapter can only be applied to classes: {cls!r}'
+      raise InvalidAdapterError(message)
+    declaration = AdapterDeclaration(
+      port=port,
+      key=key,
+      lifecycle=lifecycle_value,
+      envs=env_values,
+    )
+    cls.__idunn_adapter__ = True
+    cls.__idunn_adapter_declaration__ = declaration
+    return cls
+
+  return decorate
+
+
+@overload
+def Invert(init: Init) -> Init: ...
+
+
+@overload
+def Invert(
+  init: Mapping[str, type[Any]] | None = ...,
+  *,
+  keys: Mapping[str, str] | None = ...,
+) -> Callable[[Init], Init]: ...
+
+
+def Invert(
+  init: Init | Mapping[str, type[Any]] | None = None,
+  *,
+  keys: Mapping[str, str] | None = None,
+) -> Init | Callable[[Init], Init]:
+  """Auto-inject registered adapters for ``@Port``-typed constructor parameters.
+
+  Decorate a constructor; every parameter whose type hint is a ``@Port`` is
+  resolved from the process-wide :class:`Idunn` container at construction time
+  and assigned to ``self.<name>`` (the body may override; a caller-supplied
+  argument always wins). Constructing the decorated object is the sanctioned way
+  to start an object graph — there is no public ``resolve``.
+
+  A parameter typed ``Port | None`` (or any ``@Port`` parameter with a default) is
+  *optional*: if no adapter is active it falls back to the default / ``None``
+  instead of raising. Pick a *keyed* adapter with ``@Invert(keys={'param': 'name'})``,
+  choosing right at the point of use.
+
+  Forms::
+
+    @Invert                                # infer ports from the type hints
+    @Invert(keys={'basket': 'golden'})     # pick keyed adapters
+    @Invert({'basket': AppleBasketPort})   # explicit param -> port (no annotation)
+  """
+  explicit_ports: dict[str, type[Any]] = {}
+  if isinstance(init, Mapping):
+    explicit_ports = dict(init)
+    init = None
+  key_map: dict[str, str] = dict(keys) if keys is not None else {}
+
+  def decorate(func: Init) -> Init:
+    signature = inspect.signature(func)
+    hints = get_type_hints(func)
+    discovered, optional_params = DecoratorSupport.extract_port_parameters(hints)
+    port_params: dict[str, type[Any]] = {**explicit_ports, **discovered}
+
+    @functools.wraps(func)
+    def wrapper(self: Any, *args: Any, **kwargs: Any) -> None:
+      supplied = signature.bind_partial(self, *args, **kwargs).arguments
+      container = Idunn()
+      for name, port in port_params.items():
+        key = key_map.get(name)
+        parameter = signature.parameters[name]
+        optional = name in optional_params or parameter.default is not inspect.Parameter.empty
+        if name in supplied:
+          value = supplied[name]  # a caller-supplied argument always wins
+        elif optional and not container._has(port, key):
+          # optional dep with no active adapter: fall back to the default (or None)
+          value = None if parameter.default is inspect.Parameter.empty else parameter.default
+          kwargs[name] = value
+        else:
+          value = container._inject(port, key)  # required, or an adapter is available
+          kwargs[name] = value
+        setattr(self, name, value)  # the port always lands on self.<name>
+      func(self, *args, **kwargs)
+
+    return wrapper
+
+  return decorate if init is None else decorate(init)

idunn/app/idunn.py

@@ -0,0 +1,85 @@
+"""Idunn: the process-wide facade over the inversion engine."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import Any
+
+from idunn.domain import AdapterMetadata, LifecycleEnum, PortBinding, ReportMap
+from idunn.internal import AutoDiscovery, InversionMapper, InversionResolver
+from idunn.util import Environment, MetaSingleton, QualifiedName
+
+
+class Idunn(metaclass=MetaSingleton):
+  """Process-wide singleton facade: discover a graph, then let ``@Invert`` wire it.
+
+  ``Idunn()`` always returns the same instance. Application code touches it exactly
+  once — ``autodiscover()`` at startup (plus ``reset()`` for test isolation); everything
+  else (registration, selection, construction) lives behind it in
+  :class:`~idunn.internal.InversionMapper` / :class:`~idunn.internal.InversionResolver`.
+  """
+
+  def __init__(self, *, environment: str | None = None) -> None:
+    """Bind to the resolved environment and create an empty engine."""
+    self._environment: str = Environment.current(environment).name
+    self._mapper: InversionMapper = InversionMapper()
+    self._resolver: InversionResolver = InversionResolver(self._mapper)
+
+  @property
+  def environment(self) -> str:
+    """Active environment used for adapter filtering."""
+    return self._environment
+
+  def autodiscover(
+    self,
+    root_package: str,
+    *,
+    port_package_names: Iterable[str] | None = None,
+    adapter_package_names: Iterable[str] | None = None,
+    strict: bool = True,
+  ) -> ReportMap:
+    """Import bounded port/adapter modules under ``root_package`` and register them."""
+    return AutoDiscovery().autodiscover(
+      mapper=self._mapper,
+      root_package=root_package,
+      port_package_names=frozenset(port_package_names) if port_package_names is not None else None,
+      adapter_package_names=(
+        frozenset(adapter_package_names) if adapter_package_names is not None else None
+      ),
+      strict=strict,
+    )
+
+  def reset(self, *, environment: str | None = None) -> Idunn:
+    """Clear all registrations and instances and rebind the environment; returns self."""
+    self._environment = Environment.current(environment).name
+    self._mapper.clear()
+    self._resolver.clear()
+    return self
+
+  def describe(self) -> str:
+    """Return a readable snapshot of the active port→adapter bindings."""
+    lines = [f'Environment: {self._environment}']
+    for binding in self._mapper.bindings(environment=self._environment):
+      lines.extend(self._describe_binding(binding=binding))
+    return '\n'.join(lines)
+
+  def _inject(self, port: type[Any], key: str | None = None) -> Any:
+    """Resolve a port for ``@Invert`` (the only sanctioned construction trigger)."""
+    return self._resolver.resolve(port=port, key=key, environment=self._environment)
+
+  def _has(self, port: type[Any], key: str | None = None) -> bool:
+    """Whether an active adapter exists for ``port`` (drives ``@Invert`` optional deps)."""
+    return self._mapper.find(port=port, key=key, environment=self._environment) is not None
+
+  def _describe_binding(self, *, binding: PortBinding) -> list[str]:
+    selected = QualifiedName.of(binding.selected.adapter) if binding.selected else '<none>'
+    lines = ['', QualifiedName.of(binding.port), f'  selected: {selected}']
+    lines.extend(self._describe_adapter(metadata=metadata) for metadata in binding.adapters)
+    return lines
+
+  def _describe_adapter(self, *, metadata: AdapterMetadata) -> str:
+    flag = ' singleton' if metadata.lifecycle == LifecycleEnum.SINGLETON else ''
+    return (
+      f'  - {QualifiedName.of(metadata.adapter)} '
+      f'key={metadata.key!r} envs={metadata.environment_label()}{flag}'
+    )

idunn/domain/__init__.py

@@ -0,0 +1,33 @@
+"""Domain layer: declarations, metadata, errors, lifecycle, and value types."""
+
+from .adapter_declaration import AdapterDeclaration
+from .adapter_metadata import AdapterMetadata
+from .errors import (
+  AdapterNotFoundError,
+  DiscoveryError,
+  IdunnError,
+  InjectionCycleError,
+  InvalidAdapterError,
+  InvalidPortError,
+  MissingTypeHintError,
+)
+from .lifecycle_enum import LifecycleEnum
+from .port_binding import PortBinding
+from .registration_key import RegistrationKey
+from .report import ReportMap
+
+__all__ = (
+  'AdapterDeclaration',
+  'AdapterMetadata',
+  'AdapterNotFoundError',
+  'DiscoveryError',
+  'IdunnError',
+  'InjectionCycleError',
+  'InvalidAdapterError',
+  'InvalidPortError',
+  'LifecycleEnum',
+  'MissingTypeHintError',
+  'PortBinding',
+  'RegistrationKey',
+  'ReportMap',
+)

idunn/domain/adapter_declaration.py

@@ -0,0 +1,18 @@
+"""Declaration captured by the @Adapter decorator."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .lifecycle_enum import LifecycleEnum
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterDeclaration:
+  """Configuration captured by the @Adapter decorator."""
+
+  port: type[Any]
+  key: str | None
+  lifecycle: LifecycleEnum
+  envs: frozenset[str] | None

idunn/domain/adapter_metadata.py

@@ -0,0 +1,28 @@
+"""Metadata stored for adapter declarations and registrations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .lifecycle_enum import LifecycleEnum
+
+
+@dataclass(frozen=True, slots=True)
+class AdapterMetadata:
+  """Describes one registered adapter."""
+
+  adapter: type[Any]
+  port: type[Any]
+  key: str | None
+  lifecycle: LifecycleEnum
+  envs: frozenset[str] | None
+  order: int
+
+  def is_available_in(self, environment: str) -> bool:
+    """Return whether this adapter is active in an environment."""
+    return self.envs is None or environment in self.envs
+
+  def environment_label(self) -> str:
+    """Return a readable environment label."""
+    return ','.join(sorted(self.envs)) if self.envs is not None else '*'

idunn/domain/errors.py

@@ -0,0 +1,29 @@
+"""Idunn exception hierarchy."""
+
+
+class IdunnError(Exception):
+  """Base error for Idunn."""
+
+
+class InvalidPortError(IdunnError):
+  """Raised when @Port is applied to a non-Protocol class."""
+
+
+class InvalidAdapterError(IdunnError):
+  """Raised when an adapter registration is invalid."""
+
+
+class AdapterNotFoundError(IdunnError):
+  """Raised when no active adapter is registered for a requested port."""
+
+
+class DiscoveryError(IdunnError):
+  """Raised when Idunn autodiscovery fails."""
+
+
+class MissingTypeHintError(IdunnError):
+  """Raised when constructor injection needs a type hint that is missing."""
+
+
+class InjectionCycleError(IdunnError):
+  """Raised when constructor dependency resolution loops back on itself."""

idunn/domain/lifecycle_enum.py

@@ -0,0 +1,10 @@
+"""Adapter lifecycle choices."""
+
+from enum import StrEnum, auto
+
+
+class LifecycleEnum(StrEnum):
+  """Supported adapter lifecycles."""
+
+  SINGLETON = auto()
+  TRANSIENT = auto()

idunn/domain/port_binding.py

@@ -0,0 +1,23 @@
+"""Structured snapshot of one port's adapter bindings."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .adapter_metadata import AdapterMetadata
+
+
+@dataclass(frozen=True, slots=True)
+class PortBinding:
+  """One port, every adapter registered for it, and the one active in an environment.
+
+  Built by :class:`~idunn.internal.InversionMapper` as the single source of truth
+  for introspection (it backs ``Idunn().describe()``). ``selected`` is the adapter an
+  unkeyed resolve would return in the snapshot environment, or ``None`` when every
+  adapter for the port is keyed.
+  """
+
+  port: type[Any]
+  selected: AdapterMetadata | None
+  adapters: tuple[AdapterMetadata, ...]

idunn/domain/registration_key.py

@@ -0,0 +1,12 @@
+"""Hashable key used by the inversion table."""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class RegistrationKey:
+  """Identifies one adapter binding for one port and optional key."""
+
+  port: type[Any]
+  key: str | None = None

idunn/domain/report.py

@@ -0,0 +1,21 @@
+"""Typed structure returned by Idunn autodiscovery."""
+
+from __future__ import annotations
+
+from typing import TypedDict
+
+
+class ReportMap(TypedDict):
+  """Summary of one autodiscovery run: modules imported and classes registered.
+
+  ``registered_ports`` / ``registered_adapters`` hold fully-qualified class
+  names (``module.QualName``), not class objects, so the report stays a plain
+  serialisable dict of strings.
+  """
+
+  root_package: str
+  imported_port_modules: tuple[str, ...]
+  imported_adapter_modules: tuple[str, ...]
+  imported_modules: tuple[str, ...]
+  registered_ports: tuple[str, ...]
+  registered_adapters: tuple[str, ...]

idunn/internal/__init__.py

@@ -0,0 +1,21 @@
+"""Internal layer: discovery, the inversion engine, and decorator-support helpers.
+
+These power the :class:`~idunn.app.Idunn` facade — the catalog (``InversionMapper``),
+the construction engine (``InversionResolver``), bounded autodiscovery (``AutoDiscovery``),
+and the ``DecoratorSupport`` helpers. The classes reached across the package boundary are
+re-exported here (e.g. for ``idunn.app``); the stateless ``InversionValidator`` is used
+only via sibling imports within ``idunn.internal`` and is **not** re-exported. None of
+these are part of Idunn's public API — ``idunn/__init__`` deliberately does not expose them.
+"""
+
+from .auto_discovery import AutoDiscovery
+from .decorator_support import DecoratorSupport
+from .inversion_mapper import InversionMapper
+from .inversion_resolver import InversionResolver
+
+__all__ = [
+  'AutoDiscovery',
+  'DecoratorSupport',
+  'InversionMapper',
+  'InversionResolver',
+]

idunn/internal/auto_discovery.py

@@ -0,0 +1,202 @@
+"""Bounded discovery for decorated Idunn ports and adapters."""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from pathlib import Path
+from types import ModuleType
+from typing import Any
+
+from idunn.domain import DiscoveryError, ReportMap
+from idunn.util import QualifiedName
+
+from .inversion_mapper import InversionMapper
+
+
+class AutoDiscovery:
+  """Imports bounded port/adapter modules and registers decorated classes."""
+
+  DEFAULT_PORT_PACKAGE_NAMES = frozenset({'port', 'ports'})
+  DEFAULT_ADAPTER_PACKAGE_NAMES = frozenset({'adapter', 'adapters'})
+
+  def autodiscover(
+    self,
+    *,
+    mapper: InversionMapper,
+    root_package: str | ModuleType,
+    port_package_names: frozenset[str] | None = None,
+    adapter_package_names: frozenset[str] | None = None,
+    strict: bool = True,
+  ) -> ReportMap:
+    """Discover decorated ports first, then decorated adapters."""
+    normalized_port_names = self._normalized_names(
+      names=port_package_names,
+      fallback=self.DEFAULT_PORT_PACKAGE_NAMES,
+    )
+    normalized_adapter_names = self._normalized_names(
+      names=adapter_package_names,
+      fallback=self.DEFAULT_ADAPTER_PACKAGE_NAMES,
+    )
+    root_module = self._import_root(root_package=root_package)
+    port_module_names = self._candidate_module_names(
+      root_module=root_module,
+      package_names=normalized_port_names,
+    )
+    adapter_module_names = self._candidate_module_names(
+      root_module=root_module,
+      package_names=normalized_adapter_names,
+    )
+    port_modules = self._import_modules(
+      module_names=port_module_names,
+      strict=strict,
+      module_kind='port',
+    )
+    registered_ports = self._register_decorated_ports(mapper=mapper, modules=port_modules)
+    adapter_modules = self._import_modules(
+      module_names=adapter_module_names,
+      strict=strict,
+      module_kind='adapter',
+    )
+    additional_ports = self._register_decorated_ports(mapper=mapper, modules=adapter_modules)
+    registered_adapters = self._register_decorated_adapters(
+      mapper=mapper,
+      modules=adapter_modules,
+    )
+    imported_port_modules = tuple(module.__name__ for module in port_modules)
+    imported_adapter_modules = tuple(module.__name__ for module in adapter_modules)
+    return {
+      'root_package': root_module.__name__,
+      'imported_port_modules': imported_port_modules,
+      'imported_adapter_modules': imported_adapter_modules,
+      'imported_modules': (*imported_port_modules, *imported_adapter_modules),
+      'registered_ports': tuple(
+        QualifiedName.of(cls) for cls in (*registered_ports, *additional_ports)
+      ),
+      'registered_adapters': tuple(QualifiedName.of(cls) for cls in registered_adapters),
+    }
+
+  def _normalized_names(
+    self,
+    *,
+    names: frozenset[str] | None,
+    fallback: frozenset[str],
+  ) -> frozenset[str]:
+    source = names if names is not None else fallback
+    return frozenset(item.lower() for item in source)
+
+  def _import_root(self, *, root_package: str | ModuleType) -> ModuleType:
+    return importlib.import_module(root_package) if isinstance(root_package, str) else root_package
+
+  def _candidate_module_names(
+    self,
+    *,
+    root_module: ModuleType,
+    package_names: frozenset[str],
+  ) -> tuple[str, ...]:
+    names: list[str] = []
+    if self._has_named_part(module_name=root_module.__name__, package_names=package_names):
+      names.append(root_module.__name__)
+
+    root_path = getattr(root_module, '__path__', None)
+    if root_path is not None:
+      for path_entry in root_path:
+        names.extend(
+          self._candidate_module_names_from_path(
+            root_module=root_module,
+            root_path=Path(path_entry),
+            package_names=package_names,
+          )
+        )
+
+    return tuple(dict.fromkeys(sorted(names)))
+
+  def _candidate_module_names_from_path(
+    self,
+    *,
+    root_module: ModuleType,
+    root_path: Path,
+    package_names: frozenset[str],
+  ) -> tuple[str, ...]:
+    names: list[str] = []
+    if root_path.exists():
+      for python_file in root_path.rglob('*.py'):
+        module_name = self._module_name_for_file(
+          root_module=root_module,
+          root_path=root_path,
+          python_file=python_file,
+        )
+        if self._has_named_part(module_name=module_name, package_names=package_names):
+          names.append(module_name)
+    return tuple(names)
+
+  def _module_name_for_file(
+    self,
+    *,
+    root_module: ModuleType,
+    root_path: Path,
+    python_file: Path,
+  ) -> str:
+    relative_path = python_file.relative_to(root_path)
+    parts = list(relative_path.with_suffix('').parts)
+    if parts[-1] == '__init__':
+      parts = parts[:-1]
+    dotted_suffix = '.'.join(parts)
+    return f'{root_module.__name__}.{dotted_suffix}' if dotted_suffix else root_module.__name__
+
+  def _has_named_part(self, *, module_name: str, package_names: frozenset[str]) -> bool:
+    parts = module_name.split('.')
+    return bool(set(parts).intersection(package_names))
+
+  def _import_modules(
+    self,
+    *,
+    module_names: tuple[str, ...],
+    strict: bool,
+    module_kind: str,
+  ) -> tuple[ModuleType, ...]:
+    modules: list[ModuleType] = []
+    for module_name in module_names:
+      try:
+        modules.append(importlib.import_module(module_name))
+      except Exception as exc:  # noqa: BLE001
+        if strict:
+          message = f'Idunn failed to import {module_kind} module {module_name!r}: {exc}'
+          raise DiscoveryError(message) from exc
+        # non-strict: skip the unimportable module and continue discovery
+    return tuple(modules)
+
+  def _register_decorated_ports(
+    self,
+    *,
+    mapper: InversionMapper,
+    modules: tuple[ModuleType, ...],
+  ) -> tuple[type[Any], ...]:
+    registered: list[type[Any]] = []
+    for module in modules:
+      for candidate in self._decorated_classes(module=module, marker='__idunn_port__'):
+        if mapper.register_port(candidate):
+          registered.append(candidate)
+    return tuple(registered)
+
+  def _register_decorated_adapters(
+    self,
+    *,
+    mapper: InversionMapper,
+    modules: tuple[ModuleType, ...],
+  ) -> tuple[type[Any], ...]:
+    registered: list[type[Any]] = []
+    for module in modules:
+      for candidate in self._decorated_classes(module=module, marker='__idunn_adapter__'):
+        if mapper.register_adapter(candidate):
+          registered.append(candidate)
+    return tuple(registered)
+
+  def _decorated_classes(self, *, module: ModuleType, marker: str) -> tuple[type[Any], ...]:
+    # Own-__dict__ check: an adapter subclassing its port *inherits* __idunn_port__,
+    # so getattr would mis-detect adapters as ports. The flag lives on the decorated class only.
+    return tuple(
+      candidate
+      for _, candidate in inspect.getmembers(module, inspect.isclass)
+      if candidate.__module__ == module.__name__ and marker in candidate.__dict__
+    )