miniject 0.1.0__tar.gz

miniject-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: ["master"]
+  pull_request:
+
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run Ruff
+        run: ruff check
+
+      - name: Run Pyright
+        run: python -m pyright --pythonpath "$(command -v python)"
+
+      - name: Run pytest
+        run: PYTHONPATH=src python -m pytest -q

miniject-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.ruff_cache/

miniject-0.1.0/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.

miniject-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,204 @@
+# miniject
+
+Lightweight dependency injection container for Python. Auto-wires constructor
+dependencies from type hints, supports singleton and transient scopes, and
+provides scoped child containers for testing and per-context overrides.
+
+**Small codebase. Zero dependencies. Fully typed.**
+
+## Installation
+
+```bash
+pip install miniject
+```
+
+## Quick start
+
+```python
+from miniject import Container
+
+class Database:
+    def __init__(self, url: str = "sqlite:///:memory:") -> None:
+        self.url = url
+
+class UserRepo:
+    def __init__(self, database: Database) -> None:
+        self.database = database
+
+class UserService:
+    def __init__(self, repo: UserRepo) -> None:
+        self.repo = repo
+
+container = Container()
+container.bind(Database, instance=Database("postgres://localhost/mydb"))
+container.bind(UserRepo)       # auto-wired from type hints
+container.bind(UserService)    # resolves UserRepo → Database automatically
+
+service = container.resolve(UserService)
+assert service.repo.database.url == "postgres://localhost/mydb"
+```
+
+## API
+
+### `Container()`
+
+Create a new container.
+
+### `container.bind(service, *, factory=..., instance=..., singleton=...)`
+
+Register a service type. Four modes:
+
+| Call | Behavior |
+|------|----------|
+| `bind(SomeType)` | Auto-wire from `__init__` type hints (transient) |
+| `bind(SomeType, instance=obj)` | Singleton by instance |
+| `bind(SomeType, factory=fn)` | Custom factory (transient) |
+| `bind(SomeType, factory=fn, singleton=True)` | Custom factory (singleton, shared by child scopes) |
+
+**Auto-wiring** inspects constructor parameters via `typing.get_type_hints()`
+and resolves each typed parameter from the container. Parameters with default
+values are left to Python when no binding exists. Nullable dependencies such as
+`Database | None = None` are supported: if `Database` is bound it is injected,
+otherwise Python keeps the default `None`.
+
+Common scalar builtins like `int`, `str`, `float`, `bool`, and `bytes` are not
+supported as DI keys. Prefer typed value objects or explicit factories for
+scalar configuration values.
+
+Type hints must be importable at runtime. If `get_type_hints()` cannot resolve
+an annotation, miniject raises `ResolutionError` instead of silently skipping
+injection. `Annotated[...]` is intentionally unsupported. miniject does not
+provide qualifier-style multiple bindings for the same base type. If two
+dependencies mean different things, model them as different types. If the
+distinction is construction logic, use an explicit factory.
+
+## Design Philosophy
+
+miniject prefers minimal container magic:
+
+- constructors should describe semantic dependencies, not container selection rules
+- composition roots and factories should own non-trivial wiring decisions
+- if two dependencies mean different things, they should usually be different types
+- if construction depends on runtime policy, use an explicit factory rather than metadata
+
+### `container.resolve(service, **overrides)`
+
+Resolve a service, recursively auto-wiring all dependencies. Keyword
+`overrides` are passed directly to the factory/constructor, bypassing the
+container for those parameters.
+
+Raises `ResolutionError` on missing bindings or circular dependencies, with
+a full dependency chain in the message.
+
+### `container.scope()`
+
+Create a child container that inherits all parent bindings. Overrides in the
+child do not affect the parent.
+
+```python
+parent = Container()
+parent.bind(Database, instance=production_db)
+parent.bind(UserRepo)
+
+child = parent.scope()
+child.bind(Database, instance=test_db)    # override in child only
+
+child.resolve(UserRepo).database   # → test_db
+parent.resolve(UserRepo).database  # → production_db
+```
+
+Singletons defined in the parent remain shared when resolved through a child
+scope. If a child re-binds a service, that override is isolated to the child.
+
+Use cases:
+- **Testing** — swap specific dependencies without rebuilding the whole graph
+- **Per-request isolation** — override config for a specific context
+
+### `ResolutionError`
+
+Raised when resolution fails. The message includes the full dependency chain:
+
+```
+ResolutionError: Cannot resolve UserRepo: missing binding for parameter 'database'
+  (type=Database) (UserService -> UserRepo)
+```
+
+Circular dependencies are detected and reported:
+
+```
+ResolutionError: Circular dependency: A -> B -> A
+```
+
+## Composition root pattern
+
+Only composition roots (startup code, CLI entrypoints, test fixtures) should
+call `container.resolve()`. All other code receives dependencies via constructor
+injection:
+
+```python
+# src/myapp/container.py — composition root
+from miniject import Container
+
+def create_container(config: Config) -> Container:
+    c = Container()
+    c.bind(Config, instance=config)
+    c.bind(Database, factory=lambda: Database(config.db_url), singleton=True)
+    c.bind(UserRepo)
+    c.bind(UserService)
+    return c
+
+# src/myapp/services.py — normal code, no container import
+class UserService:
+    def __init__(self, repo: UserRepo) -> None:
+        self.repo = repo
+```
+
+## Thread safety
+
+miniject is designed for the **composition-root-at-startup** pattern: build
+and populate the container at application start, then share it for resolution.
+Concurrent `resolve()` calls are safe after configuration is complete, and
+singleton factories are initialized at most once per owning container.
+
+Rebinding services on a container that is already being shared across threads is
+not supported. If you need runtime reconfiguration, build a new container or a
+child scope instead of mutating a shared container in place.
+
+## When to use miniject
+
+miniject is a good fit when you want:
+
+- constructor injection from type hints
+- a tiny composition-root container with very little magic
+- child scopes for tests and context-specific overrides
+- explicit failure when runtime annotations are not actually resolvable
+
+miniject is probably **not** the right fit when you need:
+
+- async/resource lifecycle management
+- framework integration or function/method wiring
+- multiple qualified bindings for the same base type
+- extensive provider types, configuration loaders, or container metaprogramming
+
+## Comparison
+
+miniject is intentionally narrower than larger Python DI frameworks.
+
+- Compared with `dependency-injector`, miniject is much smaller and easier to
+  hold in your head, but it does not try to compete with provider graphs,
+  configuration providers, wiring, async resources, or broader framework
+  integrations.
+- Compared with `lagom`, miniject is more opinionated and lower-surface-area.
+  Lagom supports async usage, richer integrations, and more advanced type-driven
+  behavior. miniject aims to stay focused on composition-root constructor
+  injection.
+- Compared with `punq`, miniject lives in a more similar simplicity tier. The
+  main differences are miniject's scoped child containers, circular dependency
+  detection, and stricter stance on runtime-resolvable type hints.
+
+The goal is not to be the most powerful DI library. The goal is to be a small,
+predictable one that stays useful without turning into a framework.
+
+## License
+
+MIT

miniject-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "miniject"
+version = "0.1.0"
+description = "Lightweight dependency injection container with auto-wiring and scoped child containers."
+requires-python = ">=3.11"
+license = "MIT"
+keywords = ["dependency-injection", "di", "ioc", "container", "auto-wiring"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.urls]
+Repository = "https://github.com/danielstarman/miniject"
+
+[project.optional-dependencies]
+dev = ["pytest", "pyright", "ruff"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/miniject"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "ANN401",  # Any is appropriate at runtime introspection boundaries
+    "D",       # pydocstyle (docstrings covered manually)
+    "EM102",   # inline exception messages are fine for a small library
+    "SLF001",  # container internals may coordinate through private helpers
+    "TC003",   # keep runtime-visible imports for type-hint introspection
+    "TRY003",  # small project; dedicated exception-message helpers add noise
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*.py" = ["ANN001", "PLR2004", "S101"]
+
+[tool.pyright]
+include = ["src", "tests"]
+extraPaths = ["src"]
+typeCheckingMode = "strict"
+
+[[tool.pyright.executionEnvironments]]
+root = "tests"
+reportMissingParameterType = "none"
+reportUnknownParameterType = "none"

miniject-0.1.0/src/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-0.1.0/src/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/tests/test_container.py

@@ -0,0 +1,424 @@
+"""Tests for the DI container."""
+
+from __future__ import annotations
+
+from concurrent.futures import ThreadPoolExecutor
+from threading import Barrier, Lock
+from typing import Annotated
+
+import pytest
+
+from miniject import Container, ResolutionError
+
+# ── Test fixtures ────────────────────────────────────────────────────
+
+
+class _Database:
+    def __init__(self, path: str = ":memory:") -> None:
+        self.path = path
+
+
+class _Repo:
+    def __init__(self, database: _Database) -> None:
+        self.database = database
+
+
+class _Service:
+    def __init__(self, repo: _Repo, database: _Database) -> None:
+        self.repo = repo
+        self.database = database
+
+
+class _ServiceWithDefault:
+    def __init__(self, database: _Database, timeout: int = 30) -> None:
+        self.database = database
+        self.timeout = timeout
+
+
+class _TimeoutSettings:
+    def __init__(self, seconds: int) -> None:
+        self.seconds = seconds
+
+
+class _ServiceWithSettings:
+    def __init__(self, database: _Database, settings: _TimeoutSettings) -> None:
+        self.database = database
+        self.settings = settings
+
+
+class _ServiceWithOptionalDatabaseDefault:
+    def __init__(self, database: _Database | None = None) -> None:
+        self.database = database
+
+
+class _ServiceWithOptionalDatabaseRequired:
+    def __init__(self, database: _Database | None) -> None:
+        self.database = database
+
+
+class _AnnotatedService:
+    def __init__(self, database: Annotated[_Database, "primary"]) -> None:
+        self.database = database
+
+
+class _MissingRuntimeDependency:
+    pass
+
+
+class _MissingRuntimeHintService:
+    def __init__(self, database: _MissingRuntimeDependency) -> None:
+        self.database = database
+
+
+class _UntypedService:
+    def __init__(self, dependency) -> None:
+        self.dependency = dependency
+
+
+class _CircularA:
+    def __init__(self, b: _CircularB) -> None:
+        self.b = b
+
+
+class _CircularB:
+    def __init__(self, a: _CircularA) -> None:
+        self.a = a
+
+
+# ── bind + resolve: instance ─────────────────────────────────────────
+
+
+def test_bind_instance_and_resolve() -> None:
+    c = Container()
+    db = _Database("test.db")
+    c.bind(_Database, instance=db)
+
+    resolved = c.resolve(_Database)
+
+    assert resolved is db
+    assert resolved.path == "test.db"
+
+
+def test_instance_is_singleton() -> None:
+    c = Container()
+    db = _Database()
+    c.bind(_Database, instance=db)
+
+    assert c.resolve(_Database) is c.resolve(_Database)
+
+
+# ── bind + resolve: auto-wired ───────────────────────────────────────
+
+
+def test_auto_wire_transient() -> None:
+    c = Container()
+    c.bind(_Database, instance=_Database())
+    c.bind(_Repo)
+
+    repo = c.resolve(_Repo)
+
+    assert isinstance(repo, _Repo)
+    assert isinstance(repo.database, _Database)
+
+
+def test_auto_wire_transient_creates_new_each_time() -> None:
+    c = Container()
+    c.bind(_Database, instance=_Database())
+    c.bind(_Repo)
+
+    r1 = c.resolve(_Repo)
+    r2 = c.resolve(_Repo)
+
+    assert r1 is not r2
+    assert r1.database is r2.database  # shared singleton Database
+
+
+def test_auto_wire_deep_chain() -> None:
+    c = Container()
+    c.bind(_Database, instance=_Database())
+    c.bind(_Repo)
+    c.bind(_Service)
+
+    svc = c.resolve(_Service)
+
+    assert isinstance(svc.repo, _Repo)
+    assert isinstance(svc.database, _Database)
+    assert svc.repo.database is svc.database  # same Database singleton
+
+
+# ── bind + resolve: factory ──────────────────────────────────────────
+
+
+def test_factory_transient() -> None:
+    c = Container()
+    c.bind(_Database, factory=lambda: _Database("/custom"))
+
+    db = c.resolve(_Database)
+
+    assert db.path == "/custom"
+
+
+def test_factory_singleton() -> None:
+    c = Container()
+    c.bind(_Database, factory=lambda: _Database("/singleton"), singleton=True)
+
+    d1 = c.resolve(_Database)
+    d2 = c.resolve(_Database)
+
+    assert d1 is d2
+    assert d1.path == "/singleton"
+
+
+def _repo_factory(database: _Database) -> _Repo:
+    return _Repo(database)
+
+
+def test_factory_with_deps() -> None:
+    c = Container()
+    c.bind(_Database, instance=_Database())
+    c.bind(_Repo, factory=_repo_factory)
+
+    repo = c.resolve(_Repo)
+
+    assert isinstance(repo.database, _Database)
+
+
+# ── scope (child containers) ─────────────────────────────────────────
+
+
+def test_scope_inherits_parent_bindings() -> None:
+    parent = Container()
+    parent.bind(_Database, instance=_Database("/parent"))
+    parent.bind(_Repo)
+
+    child = parent.scope()
+    repo = child.resolve(_Repo)
+
+    assert repo.database.path == "/parent"
+
+
+def test_scope_override_does_not_affect_parent() -> None:
+    parent = Container()
+    parent.bind(_Database, instance=_Database("/parent"))
+
+    child = parent.scope()
+    child.bind(_Database, instance=_Database("/child"))
+
+    assert parent.resolve(_Database).path == "/parent"
+    assert child.resolve(_Database).path == "/child"
+
+
+def test_scope_override_propagates_to_auto_wiring() -> None:
+    parent = Container()
+    parent.bind(_Database, instance=_Database("/parent"))
+    parent.bind(_Repo)
+
+    child = parent.scope()
+    child.bind(_Database, instance=_Database("/child"))
+
+    parent_repo = parent.resolve(_Repo)
+    child_repo = child.resolve(_Repo)
+
+    assert parent_repo.database.path == "/parent"
+    assert child_repo.database.path == "/child"
+
+
+def test_parent_singleton_factory_is_shared_with_children() -> None:
+    parent = Container()
+    parent.bind(_Database, factory=lambda: _Database("/shared"), singleton=True)
+
+    child = parent.scope()
+
+    parent_db = parent.resolve(_Database)
+    child_db = child.resolve(_Database)
+
+    assert parent_db is child_db
+
+
+def test_parent_singleton_dependency_is_shared_when_resolved_through_child() -> None:
+    parent = Container()
+    parent.bind(_Database, factory=lambda: _Database("/shared"), singleton=True)
+    parent.bind(_Repo)
+
+    child = parent.scope()
+
+    parent_repo = parent.resolve(_Repo)
+    child_repo = child.resolve(_Repo)
+
+    assert parent_repo.database is child_repo.database
+
+
+def test_singleton_factory_is_initialized_once_under_concurrent_resolution() -> None:
+    start_barrier = Barrier(8)
+    call_count = 0
+    count_lock = Lock()
+
+    def _factory() -> _Database:
+        nonlocal call_count
+        with count_lock:
+            call_count += 1
+        return _Database("/shared")
+
+    c = Container()
+    c.bind(_Database, factory=_factory, singleton=True)
+
+    def _resolve(_: int) -> _Database:
+        start_barrier.wait()
+        return c.resolve(_Database)
+
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        results = list(pool.map(_resolve, range(8)))
+
+    assert all(result is results[0] for result in results)
+    assert call_count == 1
+
+
+def test_parent_singleton_is_initialized_once_when_children_resolve_concurrently() -> None:
+    start_barrier = Barrier(8)
+    call_count = 0
+    count_lock = Lock()
+
+    def _factory() -> _Database:
+        nonlocal call_count
+        with count_lock:
+            call_count += 1
+        return _Database("/shared")
+
+    parent = Container()
+    parent.bind(_Database, factory=_factory, singleton=True)
+    children = [parent.scope() for _ in range(8)]
+
+    def _resolve(child: Container) -> _Database:
+        start_barrier.wait()
+        return child.resolve(_Database)
+
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        results = list(pool.map(_resolve, children))
+
+    assert all(result is results[0] for result in results)
+    assert call_count == 1
+
+
+# ── default parameter behavior ───────────────────────────────────────
+
+
+def test_default_used_when_no_binding() -> None:
+    c = Container()
+    c.bind(_Database, instance=_Database())
+    c.bind(_ServiceWithDefault)
+
+    svc = c.resolve(_ServiceWithDefault)
+
+    assert svc.timeout == 30  # default preserved
+
+
+def test_scalar_bindings_are_rejected() -> None:
+    c = Container()
+
+    with pytest.raises(TypeError, match="scalar builtins"):
+        c.bind(int, instance=99)
+
+
+def test_typed_value_object_binding_is_injected() -> None:
+    c = Container()
+    settings = _TimeoutSettings(99)
+    c.bind(_Database, instance=_Database())
+    c.bind(_TimeoutSettings, instance=settings)
+    c.bind(_ServiceWithSettings)
+
+    svc = c.resolve(_ServiceWithSettings)
+
+    assert svc.settings is settings
+    assert svc.settings.seconds == 99
+
+
+def test_optional_binding_overrides_none_default() -> None:
+    c = Container()
+    db = _Database("/bound")
+    c.bind(_Database, instance=db)
+    c.bind(_ServiceWithOptionalDatabaseDefault)
+
+    svc = c.resolve(_ServiceWithOptionalDatabaseDefault)
+
+    assert svc.database is db
+
+
+def test_optional_binding_uses_none_default_when_unbound() -> None:
+    c = Container()
+    c.bind(_ServiceWithOptionalDatabaseDefault)
+
+    svc = c.resolve(_ServiceWithOptionalDatabaseDefault)
+
+    assert svc.database is None
+
+
+def test_optional_binding_without_default_still_requires_binding() -> None:
+    c = Container()
+    c.bind(_ServiceWithOptionalDatabaseRequired)
+
+    with pytest.raises(ResolutionError, match="missing binding for parameter 'database'"):
+        c.resolve(_ServiceWithOptionalDatabaseRequired)
+
+
+# ── error handling ───────────────────────────────────────────────────
+
+
+def test_bind_none_instance() -> None:
+    """None is a valid instance value — it should not fall through to auto-wiring."""
+    c = Container()
+    c.bind(type(None), instance=None)
+
+    assert c.resolve(type(None)) is None
+
+
+def test_missing_binding_raises_resolution_error() -> None:
+    c = Container()
+
+    with pytest.raises(ResolutionError, match="no binding"):
+        c.resolve(_Database)
+
+
+def test_missing_dep_shows_chain() -> None:
+    c = Container()
+    c.bind(_Repo)  # needs _Database but it's not registered
+
+    with pytest.raises(ResolutionError, match="_Database"):
+        c.resolve(_Repo)
+
+
+def test_annotated_dependency_requires_explicit_factory() -> None:
+    c = Container()
+    c.bind(_Database, instance=_Database())
+    c.bind(_AnnotatedService)
+
+    with pytest.raises(ResolutionError, match="Annotated"):
+        c.resolve(_AnnotatedService)
+
+
+def test_unresolvable_runtime_type_hints_raise_resolution_error() -> None:
+    c = Container()
+    c.bind(_MissingRuntimeHintService)
+
+    original = globals().pop("_MissingRuntimeDependency")
+    try:
+        with pytest.raises(ResolutionError, match="failed to evaluate type hints"):
+            c.resolve(_MissingRuntimeHintService)
+    finally:
+        globals()["_MissingRuntimeDependency"] = original
+
+
+def test_untyped_required_param_shows_unknown_type() -> None:
+    c = Container()
+    c.bind(_UntypedService)
+
+    with pytest.raises(ResolutionError, match=r"type=\?"):
+        c.resolve(_UntypedService)
+
+
+def test_circular_dependency_detected() -> None:
+    c = Container()
+    c.bind(_CircularA)
+    c.bind(_CircularB)
+
+    with pytest.raises(ResolutionError, match="Circular dependency"):
+        c.resolve(_CircularA)