miniject 0.1.0__py3-none-any.whl

miniject/__init__.py

@@ -0,0 +1,11 @@
+"""Lightweight dependency injection container.
+
+Provides constructor-based auto-wiring, singleton/transient scopes, and scoped
+child containers for testing and experiment overrides. Only composition roots
+should call ``.resolve()``; all other code receives dependencies via constructor
+injection.
+"""
+
+from miniject._container import Container, ResolutionError
+
+__all__ = ["Container", "ResolutionError"]

miniject/_container.py

@@ -0,0 +1,354 @@
+"""Lightweight dependency injection container.
+
+Provides constructor-based auto-wiring, singleton/transient scopes, and scoped
+child containers for testing and experiment overrides.  Only composition roots
+should call ``.resolve()``; all other code receives dependencies via constructor
+injection.
+"""
+
+from __future__ import annotations
+
+import inspect
+import types
+import typing
+from collections.abc import Callable
+from dataclasses import dataclass
+from threading import RLock
+from typing import Any, TypeVar, cast
+
+_T = TypeVar("_T")
+
+_EMPTY: object = object()
+_DISALLOWED_AUTO_INJECT_TYPES: frozenset[type] = frozenset({bool, bytes, float, int, str})
+_NONE_TYPE: type[None] = type(None)
+_UNION_TYPES: tuple[object, ...] = (typing.Union, types.UnionType)
+
+
+class ResolutionError(Exception):
+    """Raised when a dependency cannot be resolved."""
+
+
+@dataclass(frozen=True, slots=True)
+class _ResolvedParamType:
+    """Normalized parameter type metadata used during dependency resolution."""
+
+    binding_key: type | None
+    display_name: str
+
+
+class _Binding:
+    """Internal registration record."""
+
+    __slots__ = ("factory", "instance", "singleton")
+
+    def __init__(
+        self,
+        *,
+        factory: Callable[..., Any] | None = None,
+        instance: object = _EMPTY,
+        singleton: bool = False,
+    ) -> None:
+        self.factory = factory
+        self.instance = instance
+        self.singleton = singleton
+
+
+class Container:
+    """Minimal DI container with auto-wiring and scoped child containers.
+
+    API::
+
+        container = Container()
+        container.bind(Database, instance=db)      # singleton by instance
+        container.bind(TradeRepository)             # auto-wired transient
+        container.bind(BalanceTracker, factory=fn, singleton=True)
+
+        db = container.resolve(Database)
+
+        scoped = container.scope()                  # child container
+        scoped.bind(FooParams, instance=modified)   # override in child
+        strat = scoped.resolve(MyStrategy)          # parent unaffected
+    """
+
+    def __init__(self, *, _parent: Container | None = None) -> None:
+        self._bindings: dict[type, _Binding] = {}
+        self._singletons: dict[type, object] = {}
+        self._parent = _parent
+        self._lock = RLock()
+
+    def bind(
+        self,
+        service: type[_T],
+        *,
+        factory: Callable[..., _T] | None = None,
+        instance: _T | object = _EMPTY,
+        singleton: bool = False,
+    ) -> None:
+        """Register a service type.
+
+        * ``bind(SomeType)`` — auto-wire from ``__init__`` type hints (transient)
+        * ``bind(SomeType, instance=obj)`` — singleton by instance
+        * ``bind(SomeType, factory=fn)`` — custom factory (transient by default)
+        * ``bind(SomeType, factory=fn, singleton=True)`` — factory singleton
+        """
+        _validate_service_type(service)
+        if instance is not _EMPTY:
+            self._bindings[service] = _Binding(instance=instance)
+            self._singletons[service] = instance
+        elif factory is not None:
+            self._bindings[service] = _Binding(factory=factory, singleton=singleton)
+        else:
+            self._bindings[service] = _Binding(factory=service, singleton=singleton)
+
+    def resolve(self, service: type[_T], **overrides: Any) -> _T:
+        """Resolve a service, auto-wiring constructor dependencies.
+
+        Raises :class:`ResolutionError` on missing bindings or circular deps.
+        """
+        return self._resolve(service, _stack=(), **overrides)
+
+    def scope(self) -> Container:
+        """Create a child container inheriting all parent bindings.
+
+        Overrides in the child do **not** affect the parent.
+        """
+        return Container(_parent=self)
+
+    # ── internals ────────────────────────────────────────────────────
+
+    def _resolve(self, service: type[_T], *, _stack: tuple[type, ...], **overrides: Any) -> _T:
+        # Check for circular dependency
+        if service in _stack:
+            chain = " -> ".join(t.__name__ for t in (*_stack, service))
+            raise ResolutionError(f"Circular dependency: {chain}")
+
+        # Find binding owner (local then parent chain)
+        binding_owner_and_binding = self._find_binding_owner(service)
+        if binding_owner_and_binding is None:
+            chain = " -> ".join(t.__name__ for t in (*_stack, service))
+            raise ResolutionError(f"Cannot resolve {service.__name__}: no binding ({chain})")
+        binding_owner, binding = binding_owner_and_binding
+
+        # Singleton factories should be shared and initialized safely where the
+        # binding is defined.
+        if binding.singleton:
+            return cast(
+                "_T",
+                binding_owner._resolve_singleton(
+                    service,
+                    binding,
+                    requester=self,
+                    stack=(*_stack, service),
+                    overrides=overrides,
+                ),
+            )
+
+        # Instance binding (already stored)
+        if binding.instance is not _EMPTY:
+            return cast("_T", binding.instance)
+
+        # Factory binding
+        factory = _require_factory(binding)
+        instance = self._invoke_factory(factory, _stack=(*_stack, service), **overrides)
+
+        return cast("_T", instance)
+
+    def _find_binding(self, service: type) -> _Binding | None:
+        binding_owner_and_binding = self._find_binding_owner(service)
+        if binding_owner_and_binding is None:
+            return None
+        _, binding = binding_owner_and_binding
+        return binding
+
+    def _find_binding_owner(self, service: type) -> tuple[Container, _Binding] | None:
+        if service in self._bindings:
+            return self, self._bindings[service]
+        if self._parent is not None:
+            return self._parent._find_binding_owner(service)
+        return None
+
+    def _resolve_singleton(
+        self,
+        service: type,
+        binding: _Binding,
+        *,
+        requester: Container,
+        stack: tuple[type, ...],
+        overrides: dict[str, Any],
+    ) -> object:
+        with self._lock:
+            existing = self._singletons.get(service, _EMPTY)
+            if existing is not _EMPTY:
+                return existing
+
+            if binding.instance is not _EMPTY:
+                self._singletons[service] = binding.instance
+                return binding.instance
+
+            factory = _require_factory(binding)
+            instance = requester._invoke_factory(
+                factory,
+                _stack=stack,
+                **overrides,
+            )
+            self._singletons[service] = instance
+            return instance
+
+    def _invoke_factory(
+        self, factory: Callable[..., Any], *, _stack: tuple[type, ...], **overrides: Any,
+    ) -> Any:
+        """Call a factory, resolving its parameters from the container."""
+        sig_and_hints = _introspect_factory(factory)
+        if sig_and_hints is None:
+            return factory()
+        sig, hints = sig_and_hints
+
+        kwargs: dict[str, Any] = {}
+        for param_name, param in sig.parameters.items():
+            if param_name == "self":
+                continue
+            if param_name in overrides:
+                kwargs[param_name] = overrides[param_name]
+                continue
+
+            param_type = hints.get(param_name)
+            resolved_type = _resolve_param_type(
+                param_type,
+                factory_name=_callable_name(factory),
+                param_name=param_name,
+            )
+            if resolved_type.binding_key is not None:
+                binding = self._find_binding(resolved_type.binding_key)
+                if binding is not None:
+                    kwargs[param_name] = self._resolve(resolved_type.binding_key, _stack=_stack)
+                    continue
+
+            # No binding found — use default if available
+            if param.default is not inspect.Parameter.empty:
+                continue  # let Python's default apply
+            if param.kind in (
+                inspect.Parameter.VAR_POSITIONAL,
+                inspect.Parameter.VAR_KEYWORD,
+            ):
+                continue
+
+            # Required param with no binding and no default
+            chain = " -> ".join(t.__name__ for t in _stack)
+            raise ResolutionError(
+                f"Cannot resolve {factory.__name__}: "
+                f"missing binding for parameter '{param_name}' "
+                f"(type={resolved_type.display_name}) "
+                f"({chain})",
+            )
+
+        return factory(**kwargs)
+
+
+def _introspect_factory(
+    factory: Callable[..., Any],
+) -> tuple[inspect.Signature, dict[str, Any]] | None:
+    """Extract signature and type hints for a factory, or None if not introspectable."""
+    try:
+        sig = inspect.signature(factory)
+    except (ValueError, TypeError):
+        return None
+    hint_target = factory.__init__ if isinstance(factory, type) else factory
+    hints = _get_type_hints_or_raise(hint_target, factory_name=_callable_name(factory))
+    return sig, hints
+
+
+def _get_type_hints_or_raise(
+    fn: Callable[..., Any],
+    *,
+    factory_name: str,
+) -> dict[str, Any]:
+    """Get runtime-resolvable type hints for a factory or constructor."""
+    try:
+        return typing.get_type_hints(fn, include_extras=True)
+    except (AttributeError, NameError, TypeError, ValueError) as exc:
+        target_name = _callable_name(fn)
+        raise ResolutionError(
+            f"Cannot resolve {factory_name}: failed to evaluate type hints for "
+            f"{target_name}; make annotations importable at runtime or use an explicit "
+            f"factory ({exc.__class__.__name__}: {exc})",
+        ) from exc
+
+
+def _resolve_param_type(
+    param_type: Any,
+    *,
+    factory_name: str,
+    param_name: str,
+) -> _ResolvedParamType:
+    """Normalize a parameter annotation into a DI binding key and semantics."""
+    if param_type is None:
+        return _ResolvedParamType(binding_key=None, display_name="?")
+
+    origin = typing.get_origin(param_type)
+    if origin is typing.Annotated:
+        raise ResolutionError(
+            f"Cannot resolve {factory_name}: parameter '{param_name}' uses Annotated[...] "
+            "which miniject does not support; use an explicit factory instead",
+        )
+
+    if origin in _UNION_TYPES:
+        args = typing.get_args(param_type)
+        non_none_args = tuple(arg for arg in args if arg is not _NONE_TYPE)
+        if len(non_none_args) == 1 and len(non_none_args) != len(args):
+            inner = non_none_args[0]
+            inner_origin = typing.get_origin(inner)
+            if inner_origin is typing.Annotated:
+                raise ResolutionError(
+                    f"Cannot resolve {factory_name}: parameter '{param_name}' uses "
+                    "Annotated[...] which miniject does not support; use an explicit "
+                    "factory instead",
+                )
+            binding_key = inner if _is_auto_injectable_type(inner) else None
+            return _ResolvedParamType(
+                binding_key=binding_key,
+                display_name=_format_type_name(param_type),
+            )
+
+    binding_key = param_type if _is_auto_injectable_type(param_type) else None
+    return _ResolvedParamType(
+        binding_key=binding_key,
+        display_name=_format_type_name(param_type),
+    )
+
+
+def _format_type_name(param_type: Any) -> str:
+    """Render a readable type name for resolution errors."""
+    if param_type is None:
+        return "?"
+    if isinstance(param_type, type):
+        return param_type.__name__
+    return str(param_type).replace("typing.", "")
+
+
+def _is_auto_injectable_type(param_type: Any) -> bool:
+    """Return whether a type hint should be used as a DI lookup key."""
+    return isinstance(param_type, type) and param_type not in _DISALLOWED_AUTO_INJECT_TYPES
+
+
+def _callable_name(fn: Callable[..., Any]) -> str:
+    """Best-effort human-readable callable name for diagnostics."""
+    return getattr(fn, "__name__", fn.__class__.__name__)
+
+
+def _require_factory(binding: _Binding) -> Callable[..., Any]:
+    """Return a binding factory or raise if the binding is malformed."""
+    factory = binding.factory
+    if factory is None:
+        msg = "Binding is missing a factory"
+        raise ResolutionError(msg)
+    return factory
+
+
+def _validate_service_type(service: type[Any]) -> None:
+    """Reject unsupported DI keys up front."""
+    if service in _DISALLOWED_AUTO_INJECT_TYPES:
+        msg = (
+            f"Cannot bind {service.__name__}: scalar builtins are not supported as DI keys; "
+            "use a typed value object or an explicit factory instead"
+        )
+        raise TypeError(msg)

miniject-0.1.0.dist-info/METADATA

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: miniject
+Version: 0.1.0
+Summary: Lightweight dependency injection container with auto-wiring and scoped child containers.
+Project-URL: Repository, https://github.com/danielstarman/miniject
+License-Expression: MIT
+License-File: LICENSE
+Keywords: auto-wiring,container,dependency-injection,di,ioc
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: pyright; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'

miniject-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+miniject/__init__.py,sha256=A62uIzhi2kon4_1ig4vLSQwKAUXSDyRoKdpC5pZajeg,416
+miniject/_container.py,sha256=g21mD63QA1EsEWYFI1Yw_rEHzrMcceVbL-nvMHOgDCY,13207
+miniject/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+miniject-0.1.0.dist-info/METADATA,sha256=By4nOSrqcx-s8lmx68Lqf95J1AfePaE2SALdqvNa1g0,848
+miniject-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+miniject-0.1.0.dist-info/licenses/LICENSE,sha256=qA6OKCSvrEXsWU_L0GgFU4w05Nuujoc6zEutEij_jHw,1086
+miniject-0.1.0.dist-info/RECORD,,

miniject-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

miniject-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dstarman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.