static-dependency-injector 0.2.0__py3-none-any.whl

static_dependency_injector/_pytest_plugin.py

@@ -0,0 +1,20 @@
+"""pytest plugin: reset ``TestContextSingleton`` providers after each test.
+
+Auto-registered through the ``pytest11`` entry point, so any test suite that
+installs this package gets per-test reset of test-scoped providers for free,
+replacing manual ``provider.reset()`` calls in test teardown.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+
+def pytest_runtest_teardown(item: Any) -> None:
+    # Lazy import keeps plugin load cheap and avoids import-order coupling;
+    # failures here must never fail the test run.
+    try:
+        from static_dependency_injector.containers import StaticDeclarativeContainer
+
+        StaticDeclarativeContainer.reset_test_context()
+    except Exception:  # noqa: BLE001
+        pass

static_dependency_injector/containers/__init__.py

@@ -0,0 +1,4 @@
+from static_dependency_injector.containers._container_config_dict import ContainerConfigDict
+from static_dependency_injector.containers._static_declarative_container import StaticDeclarativeContainer
+
+__all__ = ("ContainerConfigDict", "StaticDeclarativeContainer")

static_dependency_injector/containers/_container_config_dict.py

@@ -0,0 +1,13 @@
+from typing import TypedDict
+
+
+class ContainerConfigDict(TypedDict, total=False):
+    """Per-container configuration.
+
+    ``name`` defaults to the fully-qualified class name (``module.QualName``).
+    Two container classes sharing a ``name`` share one set of provider
+    bindings (first writer under a name wins; overrides are visible to every
+    class registered under that name).
+    """
+
+    name: str

static_dependency_injector/containers/_static_declarative_container.py

@@ -0,0 +1,57 @@
+from typing import Any
+
+from dependency_injector import containers
+
+from static_dependency_injector.containers._static_declarative_container_meta import (
+    StaticDeclarativeContainerMeta,
+    _ResolvedProperty,
+)
+
+
+class StaticDeclarativeContainer(
+    containers.DeclarativeContainer,
+    metaclass=StaticDeclarativeContainerMeta,
+):
+    """Base class for static, lazily-resolved DI containers.
+
+    Subclass it and declare providers as class attributes; read them back as
+    resolved values via the class (``MyServices.db``). Replace providers per
+    test with :meth:`set_overrides` and restore them with :meth:`clear_overrides`.
+    """
+
+    @classmethod
+    def _provider_names(cls) -> frozenset[str]:
+        """Names of this container's providers (own and inherited)."""
+        return frozenset(
+            attr
+            for klass in type(cls).__mro__
+            for attr, value in vars(klass).items()
+            if isinstance(value, _ResolvedProperty)
+        )
+
+    @classmethod
+    def set_overrides(cls, **values: Any) -> None:
+        """Override named providers with concrete values until cleared.
+
+        ``MyServices.set_overrides(db=fake_db, clock=frozen)`` swaps each
+        provider's resolved value (running its ``on_set`` hook). A subsequent
+        ``MyServices.db`` then returns ``fake_db``. Prefer this over attribute
+        assignment - it type-checks cleanly.
+        """
+        unknown = set(values) - cls._provider_names()
+        if unknown:
+            raise TypeError(f"{cls.__name__} has no provider(s): {sorted(unknown)}")
+        for name, value in values.items():
+            setattr(cls, name, value)
+
+    @classmethod
+    def clear_overrides(cls, *names: str) -> None:
+        """Clear provider overrides. With ``names`` clear those; with none,
+        clear every provider on this container."""
+        valid = cls._provider_names()
+        targets = frozenset(names) if names else valid
+        unknown = targets - valid
+        if unknown:
+            raise TypeError(f"{cls.__name__} has no provider(s): {sorted(unknown)}")
+        for name in targets:
+            delattr(cls, name)

static_dependency_injector/containers/_static_declarative_container_meta.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import threading
+from typing import TYPE_CHECKING, Any, ClassVar, cast
+
+from dependency_injector import providers
+
+from static_dependency_injector.containers._container_config_dict import ContainerConfigDict
+
+if TYPE_CHECKING:
+    # The shipped stubs don't export the declarative metaclass; for the checker
+    # we only need to know it is a metaclass (a ``type``). At runtime we subclass
+    # the real one so containers behave like dependency_injector's.
+    _DeclarativeContainerMeta = type
+else:
+    from dependency_injector.containers import (
+        DeclarativeContainerMetaClass as _DeclarativeContainerMeta,
+    )
+
+
+class _ResolvedProperty(property):
+    """Marker ``property`` subclass: lets a container's provider attributes be
+    told apart from any other properties on the metaclass MRO (e.g. those of
+    ``dependency_injector``)."""
+
+
+class StaticDeclarativeContainerMeta(_DeclarativeContainerMeta):
+    """Lifts declared providers onto a per-class metaclass as resolved
+    properties, and registers them under the container's ``name``.
+    """
+
+    _REGISTRY: ClassVar[dict[str, dict[str, providers.Provider[Any]]]] = {}
+    _REGISTRY_LOCK: ClassVar[threading.RLock] = threading.RLock()
+
+    @staticmethod
+    def _resolved_property(name: str, attr: str) -> _ResolvedProperty:
+        """Build a class property that resolves provider ``name``/``attr`` lazily."""
+        registry = StaticDeclarativeContainerMeta._REGISTRY
+
+        def fget(_cls: Any) -> Any:
+            return registry[name][attr]()
+
+        def fset(cls: Any, value: Any) -> None:
+            provider = registry[name][attr]
+            hook = getattr(provider, "_static_di_on_set", None)
+            if hook is not None:
+                value = hook(cls, value)
+            provider.override(providers.Object(value))
+
+        def fdel(_cls: Any) -> None:
+            registry[name][attr].reset_override()
+
+        return _ResolvedProperty(fget, fset, fdel)
+
+    def __new__(
+        mcs,
+        cls_name: str,
+        bases: tuple[type, ...],
+        namespace: dict[str, Any],
+        **kwargs: Any,
+    ) -> StaticDeclarativeContainerMeta:
+        own = {attr: value for attr, value in namespace.items() if isinstance(value, providers.Provider)}
+        if own:
+            config: ContainerConfigDict = namespace.get("container_config", {})
+            module = namespace.get("__module__", "")
+            qualname = namespace.get("__qualname__", cls_name)
+            name = config.get("name") or (f"{module}.{qualname}" if module else qualname)
+            with mcs._REGISTRY_LOCK:
+                bucket = mcs._REGISTRY.setdefault(name, {})
+                for attr, provider in own.items():
+                    bucket.setdefault(attr, provider)  # first writer under a name wins
+            props = {attr: mcs._resolved_property(name, attr) for attr in own}
+            mcs = cast(
+                "type[StaticDeclarativeContainerMeta]",
+                type(f"_{cls_name}Meta", (mcs,), props),  # ty:ignore[unsupported-dynamic-base]
+            )
+        return super().__new__(mcs, cls_name, bases, namespace, **kwargs)
+
+    @classmethod
+    def reset_test_context(cls) -> None:
+        """Reset every test-scoped provider (``TestContextSingleton``) across all
+        registered containers, so the next test gets fresh instances.
+
+        The bundled pytest plugin calls this on each test teardown, so a manual
+        ``provider.reset()`` in a test ``finally`` is no longer needed. Also
+        callable directly: ``MyServices.reset_test_context()``.
+        """
+        with cls._REGISTRY_LOCK:
+            test_scoped = [
+                provider
+                for bucket in cls._REGISTRY.values()
+                for provider in bucket.values()
+                if getattr(provider, "_static_di_test_scoped", False)
+            ]
+        for provider in test_scoped:
+            reset = getattr(provider, "reset", None)
+            if callable(reset):
+                reset()

static_dependency_injector/static_providers/__init__.py

@@ -0,0 +1,32 @@
+from static_dependency_injector.static_providers._container_providers import (
+    Callable,
+    ContextLocalSingleton,
+    Coroutine,
+    Dependency,
+    Factory,
+    Object,
+    Provider,
+    Resource,
+    Selector,
+    Singleton,
+    TestContextSingleton,
+    ThreadLocalSingleton,
+    ThreadSafeSingleton,
+)
+
+__all__ = [
+    "Callable",
+    "ContextLocalSingleton",
+    "Coroutine",
+    "Dependency",
+    "Factory",
+    "Object",
+    "Provider",
+    "Resource",
+    "Selector",
+    "Singleton",
+    "TestContextSingleton",
+    "ThreadLocalSingleton",
+    "ThreadSafeSingleton",
+]
+

static_dependency_injector/static_providers/_container_providers.py

@@ -0,0 +1,101 @@
+from collections.abc import Callable as _Callable
+from typing import Any
+
+from dependency_injector import providers
+
+OnSetHook = _Callable[[Any, Any], Any]
+
+
+class _ContainerProvider[T](providers.Provider[T]):
+    """Descriptor mixin for static-container providers.
+
+    Reading a container attribute resolves the dependency (``__get__`` ->
+    ``self()``), typed as ``T``. Overriding is done through the container's
+    ``set_overrides`` / ``clear_overrides``; direct attribute assignment is
+    intentionally not part of the typed API. ``on_set`` registers a hook run
+    over the value before an override is applied.
+    """
+
+    _static_di_on_set: OnSetHook | None = None
+
+    def on_set(self, hook: OnSetHook) -> OnSetHook:
+        self._static_di_on_set = hook
+        return hook
+
+    def __get__(self, _: Any, __: Any = None) -> T:
+        return self()
+
+
+# --- Instance factories --------------------------------------------------
+
+
+class Factory[T](_ContainerProvider[T], providers.Factory[T]):
+    """``Factory``: builds a new instance on every access."""
+
+
+class Singleton[T](_ContainerProvider[T], providers.Singleton[T]):
+    """``Singleton``: one instance per container, cached after the first access."""
+
+
+class ThreadSafeSingleton[T](_ContainerProvider[T], providers.ThreadSafeSingleton[T]):
+    """``Singleton`` guarded by a lock while the instance is created."""
+
+
+class ThreadLocalSingleton[T](_ContainerProvider[T], providers.ThreadLocalSingleton[T]):
+    """``Singleton`` with a separate instance per thread."""
+
+
+class ContextLocalSingleton[T](_ContainerProvider[T], providers.ContextLocalSingleton[T]):
+    """``Singleton`` with a separate instance per ``contextvars`` context."""
+
+
+# --- Calls ---------------------------------------------------------------
+
+
+class Callable[T](_ContainerProvider[T], providers.Callable[T]):
+    """``Callable``: calls a function with the given arguments and returns the result."""
+
+
+class Coroutine[T](_ContainerProvider[T], providers.Coroutine[T]):
+    """``async`` variant of ``Callable`` for coroutines; returns an awaitable."""
+
+
+# --- Values, resources, dependencies -------------------------------------
+
+
+class Object[T](_ContainerProvider[T], providers.Object[T]):
+    """``Object``: returns the given value unchanged."""
+
+
+class Resource[T](_ContainerProvider[T], providers.Resource[T]):
+    """``Resource``: a resource with init/teardown (generator or context manager)."""
+
+
+class Dependency[T](_ContainerProvider[T], providers.Dependency[T]):
+    """``Dependency``: declares a dependency that the caller must provide."""
+
+
+class Selector[T](_ContainerProvider[T], providers.Selector[T]):
+    """``Selector``: picks a provider by a selector value at runtime."""
+
+
+class Provider[T](_ContainerProvider[T], providers.Provider[T]):
+    """Base provider / escape hatch for custom implementations."""
+
+
+# --- Test scope ----------------------------------------------------------
+
+
+class TestContextSingleton[T](ContextLocalSingleton[T]):
+    """``ContextLocalSingleton`` that is reset at the test boundary.
+
+    Marked test-scoped: the bundled pytest plugin calls
+    ``StaticDeclarativeContainer.reset_test_context()`` after each test, which
+    resets such providers. A manual ``provider.reset()`` in a test ``finally``
+    is therefore unnecessary - the next test gets a fresh instance on its own
+    ``contextvars`` context.
+    """
+
+    __test__ = False  # keep pytest from collecting this Test-prefixed class
+    _static_di_test_scoped: bool = True
+

static_dependency_injector-0.2.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: static-dependency-injector
+Version: 0.2.0
+Summary: Static, lazily-resolved declarative DI containers built on dependency-injector.
+Keywords: dependency-injection,di,ioc,container,static,dependency-injector
+Author: Viacheslav Dermichev
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Classifier: Framework :: Pytest
+Requires-Dist: dependency-injector>=4.49.1
+Requires-Dist: ty>=0.0.55
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/v-dermichev/static-dependency-injector
+Project-URL: Repository, https://github.com/v-dermichev/static-dependency-injector
+Project-URL: Issues, https://github.com/v-dermichev/static-dependency-injector/issues
+Description-Content-Type: text/markdown
+
+# static-dependency-injector
+
+[![PyPI](https://img.shields.io/pypi/v/static-dependency-injector)](https://pypi.org/project/static-dependency-injector/)
+[![License](https://img.shields.io/pypi/l/static-dependency-injector)](https://github.com/v-dermichev/static-dependency-injector/blob/main/LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-v--dermichev%2Fstatic--dependency--injector-blue?logo=github)](https://github.com/v-dermichev/static-dependency-injector)
+
+Static, lazily-resolved declarative DI containers built on top of
+[`dependency-injector`](https://github.com/ets-labs/python-dependency-injector).
+
+Declare providers as class attributes and read them back as resolved **values**
+straight from the container class — no instance, no `()` call:
+
+```python
+from static_dependency_injector import static_providers as sp
+from static_dependency_injector.containers import StaticDeclarativeContainer
+
+
+class Services(StaticDeclarativeContainer):
+    config = sp.Singleton(load_config)
+    db = sp.Singleton(Database, config=config)
+
+
+db = Services.db                       # resolved Database instance (lazy, cached)
+Services.set_overrides(db=fake_db)     # override (e.g. in a test)
+Services.clear_overrides("db")         # clear it (or clear_overrides() for all)
+```
+
+Providers stay lazy: the underlying callables are not invoked until first access,
+and each provider keeps `dependency-injector`'s caching semantics.
+
+## Installation
+
+```bash
+pip install static-dependency-injector
+# or
+uv add static-dependency-injector
+```
+
+## Why
+
+- **Read providers as values** — `Services.db` returns the resolved instance, no
+  `()` call and no container instance.
+- **Fully typed** — reads resolve to the dependency's type, and the override API
+  is clean under ty, mypy and pyright (Pylance).
+- **Lazy & cached** — keeps `dependency-injector`'s resolution and per-provider
+  caching semantics; nothing is built until first access.
+- **Test-friendly** — `set_overrides` / `clear_overrides` for per-test overrides,
+  plus `TestContextSingleton` auto-reset via a bundled pytest plugin.
+- **Thin** — a typed wrapper over `dependency-injector`; no vendoring, no magic
+  beyond the container metaclass.
+
+## Providers
+
+Typed wrappers over `dependency-injector` providers (`static_providers`):
+
+`Factory`, `Singleton`, `ThreadSafeSingleton`, `ThreadLocalSingleton`,
+`ContextLocalSingleton`, `Callable`, `Coroutine`, `Object`, `Resource`,
+`Dependency`, `Selector`, `Provider`, and the test-scoped `TestContextSingleton`.
+
+Each is generic in its resolved type, so `Services.db` reads back as the
+dependency's type.
+
+## Test-scoped providers
+
+`TestContextSingleton` is reset automatically after every test by the bundled
+pytest plugin (auto-registered on install) — no manual `reset()` in teardown:
+
+```python
+class Services(StaticDeclarativeContainer):
+    driver = sp.TestContextSingleton(make_driver)
+
+# after each test the plugin calls Services.reset_test_context() for you
+```
+
+You can also reset manually: `Services.reset_test_context()`.
+
+## Type checking
+
+Reads resolve to the dependency's type, and the override API type-checks clean
+under **ty**, **mypy** and **pyright** (Pylance) — verified by a test matrix that
+runs all three. Overriding is done with `set_overrides` / `clear_overrides`;
+direct attribute assignment (`Services.db = …`) is intentionally rejected by all
+three checkers, so there is one obvious, typed way to override.
+
+## Notes & limitations
+
+Because containers are resolved at the **class level** (no container instance):
+
+- **Overrides** go through `set_overrides` / `clear_overrides`.
+  dependency_injector's *container-level* override
+  (`Container.override(other_container)`) does **not** affect resolution here -
+  reads come from the static registry, not a container instance.
+- **`Resource` teardown** is not triggered automatically: a `Resource` provider
+  initializes on first access, but its post-`yield` teardown needs a container
+  instance / `shutdown_resources()`, which the class-level model does not drive.
+  Use `Resource` for init-only setup, or manage teardown yourself.
+
+## Requirements
+
+- Python 3.12+ (uses PEP 695 generics)
+- `dependency-injector >= 4.49.1`
+
+## License
+
+MIT. Uses `dependency-injector` (BSD-3-Clause) as a runtime dependency; none of
+its source is vendored.

static_dependency_injector-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+static_dependency_injector/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+static_dependency_injector/_pytest_plugin.py,sha256=aUCicAf7EszZM_RJKV0PqNa-thRkUdSiabf68cUJAxw,734
+static_dependency_injector/containers/__init__.py,sha256=BAIVwzxPfWut2dmla3NVl2Q8suiexezMU4voRf8ytFU,265
+static_dependency_injector/containers/_container_config_dict.py,sha256=5Al0TyA7gg4IypuRxHqCWC4YDYkbHV_xJSZls3u6joQ,408
+static_dependency_injector/containers/_static_declarative_container.py,sha256=08-iOkpALKdy5j4ShT6Dehz-0MDviRBAcKRpeB6az4E,2139
+static_dependency_injector/containers/_static_declarative_container_meta.py,sha256=ckkP_EF-Z4ZTZErVHYzIs4zkrJH5S41l1Z0sf5Mox1U,4017
+static_dependency_injector/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+static_dependency_injector/static_providers/__init__.py,sha256=sqemBVmxVJkn34-98uxyLM-oCv1_8XI3K2lgx1Ga9VQ,585
+static_dependency_injector/static_providers/_container_providers.py,sha256=Oumjs1w3oIX7meNbjv_qMtWc4OF8s0MKaZwLonosxD4,3520
+static_dependency_injector-0.2.0.dist-info/licenses/LICENSE,sha256=RUqQucXRgEKTNKv-JXOsd-LIwDAIEaeFL4GaugvxWis,1077
+static_dependency_injector-0.2.0.dist-info/WHEEL,sha256=s49dN1sxqzkgPplo4QuUaKomil-_cbDzeLK4-pZKD-A,81
+static_dependency_injector-0.2.0.dist-info/entry_points.txt,sha256=LnBlqd_n4r8XThXjONEK29Lf6oLVovBx5oD6qM0e8lk,83
+static_dependency_injector-0.2.0.dist-info/METADATA,sha256=DionKJacd_pyTFdotsstWEPU6fVjgP6gKGpgO3ctMaA,5388
+static_dependency_injector-0.2.0.dist-info/RECORD,,

static_dependency_injector-0.2.0.dist-info/WHEEL

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

static_dependency_injector-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[pytest11]
+static_dependency_injector = static_dependency_injector._pytest_plugin
+

static_dependency_injector-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Viacheslav Dermichev
+
+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.