fastapi-injected 0.1.3__tar.gz → 0.2.0__tar.gz

fastapi_injected-0.2.0/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: fastapi-injected
+Version: 0.2.0
+Summary: Yet another library to reuse fastapi dependency injection
+Project-URL: Repository, https://github.com/uriyyo/fastapi-injected
+Author-email: Yurii Karabas <1998uriyyo@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.139.2
+Requires-Dist: typing-extensions>=4.16.0
+Description-Content-Type: text/markdown
+
+# fastapi-injected
+
+Yet another attempt to reuse FastAPI's dependency injection outside of request handlers.
+
+This is an opinionated library: it takes the DI machinery you already know from FastAPI (`Depends`, generator dependencies with teardown, dependency caching) and makes it usable in plain async functions — background jobs, CLI commands, workers, scripts — without a `Request` in sight.
+
+## Installation
+
+```sh
+pip install fastapi-injected
+```
+
+Requires Python 3.12+.
+
+## Usage
+
+Declare dependencies as regular classes and annotate fields with `Dep[...]`:
+
+```python
+from dataclasses import dataclass
+from typing import AsyncIterator
+
+from fastapi_injected import Dep, DepFactory, Injected, inject
+
+
+@dataclass
+class Session:
+    closed: bool = False
+
+
+async def session_dep() -> AsyncIterator[Session]:
+    session = Session()
+    try:
+        yield session
+    finally:
+        session.closed = True
+
+
+@dataclass
+class Repository:
+    session: DepFactory[Session, session_dep]
+
+
+@dataclass
+class Service:
+    repo: Dep[Repository]
+
+
+@inject
+async def handler(*, service: Dep[Service] = Injected) -> None:
+    ...  # service is built and injected, session is closed on exit
+
+
+await handler()
+```
+
+- `Dep[T]` — resolve `T` by calling it, same as FastAPI's `Annotated[T, Depends()]`.
+- `DepFactory[T, factory]` — resolve `T` via a factory, same as `Annotated[T, Depends(factory)]`. Generator factories get proper teardown.
+- `Injected` — a sentinel default that exists purely to make type checkers happy: without it they would complain about a missing argument at call sites. At runtime the parameter is always filled in by `@inject`.
+
+Injected parameters mix freely with regular ones — pass your own arguments as usual and the rest is injected:
+
+```python
+@inject
+async def add(a: int, b: int, *, service: Dep[Service] = Injected) -> int:
+    ...
+
+
+result = await add(1, 2)
+```
+
+### Resolving a type directly
+
+No decorator needed — resolve a dependency graph on demand:
+
+```python
+from fastapi_injected import resolve
+
+service = await resolve(Service)
+```
+
+Like `@inject`, `resolve` accepts `new_scope=True` to force a fresh scope instead of reusing the surrounding one.
+
+### Scopes and caching
+
+By default every call to an injected function gets its own scope: dependencies are built, cached within the call, and torn down when it returns. Wrap several calls in `push_inject_scope()` to share one cache (and defer teardown to the end of the scope):
+
+```python
+from fastapi_injected import push_inject_scope
+
+async with push_inject_scope():
+    a = await handler()  # dependencies built here
+    b = await handler()  # same instances reused
+# generator dependencies are torn down here
+```
+
+Use `@inject(new_scope=True)` to opt a function out of the surrounding scope and always get fresh dependencies.
+
+### Overriding dependencies
+
+`push_overrides` swaps dependencies out for the duration of a `with` block — handy in tests, or anywhere you need to run the same code against a different implementation:
+
+```python
+from fastapi_injected import push_overrides
+
+with push_overrides({Session: Session(closed=True)}):
+    await handler()  # gets the override instead of the real dependency
+```
+
+A key can be the dependency itself, or the annotation you wrote in the signature — `Dep[Session]` and `DepFactory[Session, session_dep]` both work and are normalized to the same underlying dependency:
+
+```python
+with push_overrides({DepFactory[Session, session_dep]: my_session}):
+    ...
+```
+
+Values are used as-is, but two wrappers make the intent explicit and cover the ambiguous cases:
+
+- `ValueOverride(value)` — always inject `value`, even when it is itself callable.
+- `FactoryOverride(factory)` — call `factory` to produce the value. Sync, async, and generator factories are all supported, with the same teardown semantics as regular dependencies.
+
+```python
+from fastapi_injected import FactoryOverride, ValueOverride
+
+with push_overrides(
+    {
+        Session: ValueOverride(fake_session),
+        Repository: FactoryOverride(lambda: FakeRepository()),
+    },
+):
+    ...
+```
+
+Overrides apply to the whole graph, not just top-level parameters — overriding a nested dependency changes what its dependents receive. Nested `push_overrides` blocks merge, with the innermost one winning.
+
+Because the surrounding scope caches resolved dependencies, an override pushed after something has already been built would silently have no effect. To catch that, `push_overrides` raises `NonFreshScopeError` if the current scope already holds cached dependencies. Pass `require_fresh_scope=False` if you know what you are doing and want the override to apply only to what has not been resolved yet:
+
+```python
+async with push_inject_scope():
+    await handler()  # dependencies cached here
+
+    with push_overrides({Session: fake}):  # raises NonFreshScopeError
+        ...
+```
+
+### Inspecting annotations
+
+A few helpers are exported for code that needs to reason about `Dep[...]` annotations — building override maps, custom decorators, and the like:
+
+- `is_dep(tp)` — whether `tp` is a `Dep`/`DepFactory` annotation.
+- `unwrap_dep_tp(tp)` — the annotated type (`Any` for a bare `Dep`).
+- `unwrap_dep_dependency(tp)` — the callable that resolves it: the factory for `DepFactory[T, factory]`, the type itself for `Dep[T]`.
+
+### FastAPI request integration
+
+Inside a FastAPI app, `@inject`-ed functions and `resolve` can share the request's own dependency cache — the same instances FastAPI built for the handler. Register `init_inject_scope` as a dependency:
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_injected import Dep, init_inject_scope, resolve
+
+app = FastAPI(dependencies=[Depends(init_inject_scope)])
+
+
+@app.get("/")
+async def route(service: Dep[Service]) -> str:
+    same = await resolve(Service)  # same instance as `service`
+    ...
+```
+
+Anything called from the handler — including `@inject`-ed helpers — resolves against the request's cache, so a per-request dependency like a DB session stays a single instance for the whole request.
+
+## License
+
+MIT

fastapi_injected-0.2.0/README.md

@@ -0,0 +1,175 @@
+# fastapi-injected
+
+Yet another attempt to reuse FastAPI's dependency injection outside of request handlers.
+
+This is an opinionated library: it takes the DI machinery you already know from FastAPI (`Depends`, generator dependencies with teardown, dependency caching) and makes it usable in plain async functions — background jobs, CLI commands, workers, scripts — without a `Request` in sight.
+
+## Installation
+
+```sh
+pip install fastapi-injected
+```
+
+Requires Python 3.12+.
+
+## Usage
+
+Declare dependencies as regular classes and annotate fields with `Dep[...]`:
+
+```python
+from dataclasses import dataclass
+from typing import AsyncIterator
+
+from fastapi_injected import Dep, DepFactory, Injected, inject
+
+
+@dataclass
+class Session:
+    closed: bool = False
+
+
+async def session_dep() -> AsyncIterator[Session]:
+    session = Session()
+    try:
+        yield session
+    finally:
+        session.closed = True
+
+
+@dataclass
+class Repository:
+    session: DepFactory[Session, session_dep]
+
+
+@dataclass
+class Service:
+    repo: Dep[Repository]
+
+
+@inject
+async def handler(*, service: Dep[Service] = Injected) -> None:
+    ...  # service is built and injected, session is closed on exit
+
+
+await handler()
+```
+
+- `Dep[T]` — resolve `T` by calling it, same as FastAPI's `Annotated[T, Depends()]`.
+- `DepFactory[T, factory]` — resolve `T` via a factory, same as `Annotated[T, Depends(factory)]`. Generator factories get proper teardown.
+- `Injected` — a sentinel default that exists purely to make type checkers happy: without it they would complain about a missing argument at call sites. At runtime the parameter is always filled in by `@inject`.
+
+Injected parameters mix freely with regular ones — pass your own arguments as usual and the rest is injected:
+
+```python
+@inject
+async def add(a: int, b: int, *, service: Dep[Service] = Injected) -> int:
+    ...
+
+
+result = await add(1, 2)
+```
+
+### Resolving a type directly
+
+No decorator needed — resolve a dependency graph on demand:
+
+```python
+from fastapi_injected import resolve
+
+service = await resolve(Service)
+```
+
+Like `@inject`, `resolve` accepts `new_scope=True` to force a fresh scope instead of reusing the surrounding one.
+
+### Scopes and caching
+
+By default every call to an injected function gets its own scope: dependencies are built, cached within the call, and torn down when it returns. Wrap several calls in `push_inject_scope()` to share one cache (and defer teardown to the end of the scope):
+
+```python
+from fastapi_injected import push_inject_scope
+
+async with push_inject_scope():
+    a = await handler()  # dependencies built here
+    b = await handler()  # same instances reused
+# generator dependencies are torn down here
+```
+
+Use `@inject(new_scope=True)` to opt a function out of the surrounding scope and always get fresh dependencies.
+
+### Overriding dependencies
+
+`push_overrides` swaps dependencies out for the duration of a `with` block — handy in tests, or anywhere you need to run the same code against a different implementation:
+
+```python
+from fastapi_injected import push_overrides
+
+with push_overrides({Session: Session(closed=True)}):
+    await handler()  # gets the override instead of the real dependency
+```
+
+A key can be the dependency itself, or the annotation you wrote in the signature — `Dep[Session]` and `DepFactory[Session, session_dep]` both work and are normalized to the same underlying dependency:
+
+```python
+with push_overrides({DepFactory[Session, session_dep]: my_session}):
+    ...
+```
+
+Values are used as-is, but two wrappers make the intent explicit and cover the ambiguous cases:
+
+- `ValueOverride(value)` — always inject `value`, even when it is itself callable.
+- `FactoryOverride(factory)` — call `factory` to produce the value. Sync, async, and generator factories are all supported, with the same teardown semantics as regular dependencies.
+
+```python
+from fastapi_injected import FactoryOverride, ValueOverride
+
+with push_overrides(
+    {
+        Session: ValueOverride(fake_session),
+        Repository: FactoryOverride(lambda: FakeRepository()),
+    },
+):
+    ...
+```
+
+Overrides apply to the whole graph, not just top-level parameters — overriding a nested dependency changes what its dependents receive. Nested `push_overrides` blocks merge, with the innermost one winning.
+
+Because the surrounding scope caches resolved dependencies, an override pushed after something has already been built would silently have no effect. To catch that, `push_overrides` raises `NonFreshScopeError` if the current scope already holds cached dependencies. Pass `require_fresh_scope=False` if you know what you are doing and want the override to apply only to what has not been resolved yet:
+
+```python
+async with push_inject_scope():
+    await handler()  # dependencies cached here
+
+    with push_overrides({Session: fake}):  # raises NonFreshScopeError
+        ...
+```
+
+### Inspecting annotations
+
+A few helpers are exported for code that needs to reason about `Dep[...]` annotations — building override maps, custom decorators, and the like:
+
+- `is_dep(tp)` — whether `tp` is a `Dep`/`DepFactory` annotation.
+- `unwrap_dep_tp(tp)` — the annotated type (`Any` for a bare `Dep`).
+- `unwrap_dep_dependency(tp)` — the callable that resolves it: the factory for `DepFactory[T, factory]`, the type itself for `Dep[T]`.
+
+### FastAPI request integration
+
+Inside a FastAPI app, `@inject`-ed functions and `resolve` can share the request's own dependency cache — the same instances FastAPI built for the handler. Register `init_inject_scope` as a dependency:
+
+```python
+from fastapi import Depends, FastAPI
+from fastapi_injected import Dep, init_inject_scope, resolve
+
+app = FastAPI(dependencies=[Depends(init_inject_scope)])
+
+
+@app.get("/")
+async def route(service: Dep[Service]) -> str:
+    same = await resolve(Service)  # same instance as `service`
+    ...
+```
+
+Anything called from the handler — including `@inject`-ed helpers — resolves against the request's cache, so a per-request dependency like a DB session stays a single instance for the whole request.
+
+## License
+
+MIT

{fastapi_injected-0.1.3 → fastapi_injected-0.2.0}/fastapi_injected/__init__.py

@@ -1,5 +1,7 @@
+from ._deps_tp import is_dep, unwrap_dep_dependency, unwrap_dep_tp
 from ._fastapi_lifecycle import init_inject_scope
 from .inject import inject
+from .overrides import FactoryOverride, ValueOverride, push_overrides
 from .resolve import resolve
 from .scope import push_inject_scope
 from .types import Dep, DepFactory, Injected
@@ -7,9 +9,15 @@ from .types import Dep, DepFactory, Injected
 __all__ = [
     "Dep",
     "DepFactory",
+    "FactoryOverride",
     "Injected",
+    "ValueOverride",
     "init_inject_scope",
     "inject",
+    "is_dep",
     "push_inject_scope",
+    "push_overrides",
     "resolve",
+    "unwrap_dep_dependency",
+    "unwrap_dep_tp",
 ]

fastapi_injected-0.2.0/fastapi_injected/_deps_tp.py

@@ -0,0 +1,60 @@
+from typing import Annotated, Any, TypeAliasType, TypeVar, get_args, get_origin
+
+from fastapi.params import Depends
+
+
+def _unwrap_tp(tp: Any) -> Any:
+    if isinstance(tp, TypeAliasType):
+        return tp.__value__
+
+    return tp
+
+
+def _get_annotated_metadata(tp: Any) -> tuple[Any, ...]:
+    if get_origin(tp) is Annotated:
+        return get_args(tp)[1:]
+
+    return ()
+
+
+def is_dep(tp: Any) -> bool:
+    tp = _unwrap_tp(tp)
+
+    return any(isinstance(tp, Depends) for tp in _get_annotated_metadata(tp))
+
+
+def _enforce_dep(tp: Any) -> Any:
+    tp = _unwrap_tp(tp)
+
+    if not is_dep(tp):
+        msg = f"Expected a Dep, got {tp!r}"
+        raise TypeError(msg)
+
+    return tp
+
+
+def unwrap_dep_tp(obj: Any, /) -> Any:
+    obj = _enforce_dep(obj)
+
+    match get_args(obj)[0]:
+        case TypeVar():  # bare `Dep`, used without a type argument
+            return Any
+        case tp:
+            return tp
+
+
+def unwrap_dep_dependency(obj: Any, /) -> Any:
+    obj = _enforce_dep(obj)
+    tp, *metadatas = get_args(obj)
+    for metadata in metadatas:
+        if isinstance(metadata, Depends) and metadata.dependency is not None:
+            return metadata.dependency
+
+    return tp
+
+
+__all__ = [
+    "is_dep",
+    "unwrap_dep_dependency",
+    "unwrap_dep_tp",
+]

{fastapi_injected-0.1.3 → fastapi_injected-0.2.0}/fastapi_injected/deps.py

@@ -1,15 +1,14 @@
 import inspect
-from collections.abc import Callable
-from contextlib import AsyncExitStack
-from contextvars import ContextVar
+from collections.abc import Callable, Iterator
+from contextlib import AbstractContextManager, AsyncExitStack, contextmanager
+from contextvars import ContextVar, Token
 from copy import copy
 from functools import lru_cache, wraps
 from typing import Annotated, Any, Literal, cast, overload
 
 from fastapi import Depends
 from fastapi.dependencies.models import Dependant
-from fastapi.dependencies.utils import get_dependant, get_typed_signature
-from fastapi.dependencies.utils import solve_dependencies as _solve_dependencies
+from fastapi.dependencies.utils import get_dependant, get_typed_signature, solve_dependencies
 
 from .scope import InjectScope
 from .sign import prepare_sign, update_func_sign
@@ -56,7 +55,7 @@ def create_single_dependant[**P, R](func: Callable[P, R], /) -> Dependant:
 
 
 @overload
-async def solve_dependencies(
+async def resolve_dependencies(
     dependant: Dependant,
     scope: InjectScope,
     *,
@@ -65,7 +64,7 @@ async def solve_dependencies(
 
 
 @overload
-async def solve_dependencies(
+async def resolve_dependencies(
     dependant: Dependant,
     scope: InjectScope,
     *,
@@ -73,13 +72,13 @@ async def solve_dependencies(
 ) -> Any: ...
 
 
-async def solve_dependencies(
+async def resolve_dependencies(
     dependant: Dependant,
     scope: InjectScope,
     *,
     single: bool = False,
 ) -> dict[str, Any]:
-    solved = await _solve_dependencies(
+    solved = await solve_dependencies(
         request=scope.request,
         dependant=dependant,
         dependency_cache=copy(scope.dependency_cache),
@@ -109,12 +108,27 @@ _dependency_override_provider: ContextVar[Any] = ContextVar(
 )
 
 
-def set_inject_dependency_override_provider(provider: Any, /) -> None:
-    _dependency_override_provider.set(provider)
+@contextmanager
+def _reset_token(var: ContextVar[Any], token: Token[Any]) -> Iterator[None]:
+    try:
+        yield
+    finally:
+        var.reset(token)
+
+
+def set_inject_dependency_override_provider(provider: Any, /) -> AbstractContextManager[None]:
+    token = _dependency_override_provider.set(provider)
+
+    return _reset_token(_dependency_override_provider, token)
+
+
+def get_inject_dependency_override_provider() -> Any | None:
+    return _dependency_override_provider.get()
 
 
 __all__ = [
     "create_dependant",
+    "get_inject_dependency_override_provider",
+    "resolve_dependencies",
     "set_inject_dependency_override_provider",
-    "solve_dependencies",
 ]

{fastapi_injected-0.1.3 → fastapi_injected-0.2.0}/fastapi_injected/inject.py

@@ -1,7 +1,7 @@
 from functools import partial, wraps
 from typing import overload
 
-from .deps import create_dependant, solve_dependencies
+from .deps import create_dependant, resolve_dependencies
 from .scope import inside_inject_scope
 from .sign import strip_sign
 from .types import AsyncFunc, Decorator
@@ -40,7 +40,7 @@ def inject[**P, R](
         async with inside_inject_scope(
             new_scope=new_scope,
         ) as inject_scope:
-            solved = await solve_dependencies(dependant, inject_scope)
+            solved = await resolve_dependencies(dependant, inject_scope)
 
             for key, value in solved.items():
                 kwargs.setdefault(key, value)

fastapi_injected-0.2.0/fastapi_injected/overrides.py

@@ -0,0 +1,106 @@
+from collections import ChainMap
+from collections.abc import AsyncGenerator, Awaitable, Callable, Generator, Iterator, Mapping
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any
+
+from ._deps_tp import is_dep, unwrap_dep_dependency
+from .deps import get_inject_dependency_override_provider, set_inject_dependency_override_provider
+from .scope import current_inject_scope
+from .types import HasDependencyOverrides
+
+
+class NonFreshScopeError(Exception):
+    def __init__(self) -> None:
+        super().__init__("push_overrides requires a fresh scope")
+
+
+def _get_current_overrides() -> Iterator[Mapping[Any, Any]]:
+    obj = get_inject_dependency_override_provider()
+
+    if isinstance(obj, HasDependencyOverrides):
+        yield obj.dependency_overrides
+
+
+def _get_override_key(tp: Any) -> Any:
+    if is_dep(tp):
+        value = unwrap_dep_dependency(tp)
+
+        if value is not None:
+            return value
+
+    return tp
+
+
+@dataclass
+class _OverridesProvider:
+    dependency_overrides: Mapping[Any, Any]
+
+
+def _create_async_resolver[T](val: T) -> Callable[[], Awaitable[T]]:
+    async def _resolver() -> T:
+        return val
+
+    return _resolver
+
+
+def _create_resolver[T](val: T, /) -> Any:
+    match val:
+        case ValueOverride(value):
+            return _create_async_resolver(value)
+        case FactoryOverride(factory):
+            return factory
+        case _:
+            return _create_async_resolver(val)
+
+
+@dataclass
+class ValueOverride[T]:
+    value: T
+
+
+@dataclass
+class FactoryOverride[**P, T]:
+    factory: Callable[P, T | Awaitable[T] | Generator[T] | AsyncGenerator[T]]
+
+
+type Overrides = dict[Any, Any | ValueOverride | FactoryOverride]
+
+
+def _enforce_fresh_scope() -> None:
+    scope = current_inject_scope()
+
+    if scope is None:
+        return
+
+    if scope.dependency_cache:
+        raise NonFreshScopeError
+
+
+@contextmanager
+def push_overrides(
+    overrides: Overrides,
+    /,
+    *,
+    require_fresh_scope: bool = True,
+) -> Iterator[None]:
+
+    if require_fresh_scope:
+        _enforce_fresh_scope()
+
+    deps = ChainMap(
+        {_get_override_key(k): _create_resolver(v) for k, v in overrides.items()},
+        *_get_current_overrides(),  # type: ignore[ty:invalid-argument-type]
+    )
+
+    with set_inject_dependency_override_provider(
+        _OverridesProvider(deps),
+    ):
+        yield
+
+
+__all__ = [
+    "FactoryOverride",
+    "ValueOverride",
+    "push_overrides",
+]

{fastapi_injected-0.1.3 → fastapi_injected-0.2.0}/fastapi_injected/resolve.py

@@ -1,6 +1,6 @@
 from typing_extensions import TypeForm
 
-from .deps import create_single_dependant, solve_dependencies
+from .deps import create_single_dependant, resolve_dependencies
 from .scope import inside_inject_scope
 
 
@@ -14,7 +14,7 @@ async def resolve[R](
     async with inside_inject_scope(
         new_scope=new_scope,
     ) as inject_scope:
-        return await solve_dependencies(
+        return await resolve_dependencies(
             dependant,
             inject_scope,
             single=True,