fastapi-injected 0.1.4__tar.gz → 0.2.1__tar.gz

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: fastapi-injected
-Version: 0.1.4
+Version: 0.2.1
 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>
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.12
 Requires-Dist: fastapi>=0.139.2
 Requires-Dist: typing-extensions>=4.16.0
+Requires-Dist: typing-inspection>=0.4.4
 Description-Content-Type: text/markdown
 
 # fastapi-injected
@@ -116,6 +117,61 @@ async with push_inject_scope():
 
 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:

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/README.md

@@ -96,6 +96,61 @@ async with push_inject_scope():
 
 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:

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/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.1/fastapi_injected/_deps_tp.py

@@ -0,0 +1,63 @@
+from typing import Annotated, Any, TypeVar, get_args, get_origin
+
+from fastapi.params import Depends
+from typing_inspection.typing_objects import is_typealiastype
+
+
+def unwrap_tp(tp: Any) -> Any:
+    # PEP 695 aliases can be nested, e.g. `type A = B` where `type B = Annotated[...]`
+    while is_typealiastype(tp):
+        tp = 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",
+    "unwrap_tp",
+]

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/fastapi_injected/_fastapi_lifecycle.py

@@ -1,10 +1,11 @@
-from collections.abc import AsyncIterable
+from collections.abc import AsyncGenerator
 from functools import wraps
 from typing import TYPE_CHECKING, Any
 
-from fastapi import Request, WebSocket, routing
+from fastapi import Depends, FastAPI, Request, WebSocket, routing
 from fastapi.dependencies import utils
 
+from .overrides import push_overrides
 from .scope import push_inject_scope
 from .types import DependencyCache
 
@@ -49,14 +50,27 @@ def _get_dependency_cache(request: Request) -> DependencyCache:
         raise MissingDependencyCacheError("Dependency cache not found") from None
 
 
-async def init_inject_scope(request: Request) -> AsyncIterable[None]:
-    async with push_inject_scope(
-        dependency_cache=_get_dependency_cache(request),
-        request=request,
-    ):
-        yield
+async def init_inject_scope(request: Request) -> AsyncGenerator[None]:
+    with push_overrides(provider=request.scope["route"].dependency_overrides_provider):
+        async with push_inject_scope(
+            dependency_cache=_get_dependency_cache(request),
+            request=request,
+        ):
+            yield
+
+
+def add_injected_scope(
+    app: FastAPI,
+    /,
+) -> None:
+    if any(dep.dependency is init_inject_scope for dep in app.router.dependencies):
+        return
+
+    dependency = Depends(init_inject_scope)
+    app.router.dependencies.insert(0, dependency)
 
 
 __all__ = [
+    "add_injected_scope",
     "init_inject_scope",
 ]

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/fastapi_injected/deps.py

@@ -1,20 +1,30 @@
 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 typing import Annotated, Any, Literal, Protocol, cast, overload, runtime_checkable
 
-from fastapi import Depends
+from fastapi import Depends, params
 from fastapi.dependencies.models import Dependant
 from fastapi.dependencies.utils import get_dependant, get_typed_signature, solve_dependencies
 
+from ._deps_tp import is_dep, unwrap_tp
 from .scope import InjectScope
 from .sign import prepare_sign, update_func_sign
 from .types import Coro, HasSignature
 
 
+@runtime_checkable
+class HasDependsHook[**P, R](Protocol):
+    def __call__(self, *args: P.args, **kwargs: P.kwargs) -> Any:
+        pass
+
+    def __get_depends__(self) -> params.Depends:
+        pass
+
+
 @lru_cache(maxsize=1024)
 def create_dependant[**P, R](func: Callable[P, Coro[R]], /) -> Dependant:
     @wraps(func)
@@ -33,23 +43,36 @@ def create_dependant[**P, R](func: Callable[P, Coro[R]], /) -> Dependant:
 
 
 @lru_cache(maxsize=1024)
-def create_single_dependant[**P, R](func: Callable[P, R], /) -> Dependant:
+def create_single_dependant[**P, R](
+    func: Callable[P, R] | HasDependsHook[P, R],
+    /,
+    *,
+    path: str | None = None,
+) -> Dependant:
     async def _factory(__value__: R) -> R:
         return __value__
 
+    match func:
+        case _ if is_dep(func):
+            annotation = unwrap_tp(func)
+        case HasDependsHook():
+            annotation = Annotated[Any, func.__get_depends__()]
+        case _:
+            annotation = Annotated[Any, Depends(func)]
+
     cast("HasSignature", _factory).__signature__ = inspect.Signature(
         parameters=[
             inspect.Parameter(
                 "__value__",
                 inspect.Parameter.POSITIONAL_OR_KEYWORD,
-                annotation=Annotated[Any, Depends(func)],
+                annotation=annotation,
             ),
         ],
         return_annotation=Any,
     )
 
     return get_dependant(
-        path="",
+        path=path or "",
         call=_factory,
     )
 
@@ -82,7 +105,7 @@ async def resolve_dependencies(
         request=scope.request,
         dependant=dependant,
         dependency_cache=copy(scope.dependency_cache),
-        dependency_overrides_provider=_dependency_override_provider.get(),
+        dependency_overrides_provider=get_inject_dependency_override_provider(),
         # this parameter is deprecated and not used
         async_exit_stack=cast(AsyncExitStack, None),
         embed_body_fields=False,
@@ -108,12 +131,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",
 ]

fastapi_injected-0.2.1/fastapi_injected/overrides.py

@@ -0,0 +1,122 @@
+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_overrides(obj: Any | None, /) -> Iterator[Mapping[Any, Any]]:
+    if obj is None:
+        return
+
+    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
+
+
+def create_fallback_override_provider(
+    *,
+    overrides: Overrides | None = None,
+    provider: HasDependencyOverrides | None = None,
+) -> OverridesProvider:
+    return OverridesProvider(
+        ChainMap(
+            {_get_override_key(k): _create_resolver(v) for k, v in (overrides or {}).items()},
+            *_get_overrides(provider),  # type: ignore[ty:invalid-argument-type]
+            *_get_overrides(get_inject_dependency_override_provider()),  # type: ignore[ty:invalid-argument-type]
+        ),
+    )
+
+
+@contextmanager
+def push_overrides(
+    overrides: Overrides | None = None,
+    /,
+    *,
+    provider: HasDependencyOverrides | None = None,
+    require_fresh_scope: bool = True,
+) -> Iterator[None]:
+
+    if require_fresh_scope:
+        _enforce_fresh_scope()
+
+    with set_inject_dependency_override_provider(
+        create_fallback_override_provider(
+            overrides=overrides,
+            provider=provider,
+        ),
+    ):
+        yield
+
+
+__all__ = [
+    "FactoryOverride",
+    "OverridesProvider",
+    "ValueOverride",
+    "create_fallback_override_provider",
+    "push_overrides",
+]

fastapi_injected-0.2.1/fastapi_injected/resolve.py

@@ -0,0 +1,56 @@
+from collections.abc import Callable
+from typing import Any, overload
+
+from typing_extensions import TypeForm
+
+from fastapi_injected.types import DepReturn
+
+from .deps import HasDependsHook, create_single_dependant, resolve_dependencies
+from .scope import inside_inject_scope
+
+
+@overload
+async def resolve[**P, R](
+    tp: Callable[P, DepReturn[R]] | HasDependsHook[P, DepReturn[R]],
+    /,
+    *,
+    new_scope: bool = False,
+) -> R:
+    pass
+
+
+@overload
+async def resolve[R](
+    tp: TypeForm[R],
+    /,
+    *,
+    new_scope: bool = False,
+) -> R:
+    pass
+
+
+async def resolve(
+    tp: Any,
+    /,
+    *,
+    new_scope: bool = False,
+) -> Any:
+
+    async with inside_inject_scope(
+        new_scope=new_scope,
+    ) as inject_scope:
+        dependant = create_single_dependant(
+            tp,
+            path=inject_scope.path_format,
+        )
+
+        return await resolve_dependencies(
+            dependant,
+            inject_scope,
+            single=True,
+        )
+
+
+__all__ = [
+    "resolve",
+]

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/fastapi_injected/scope.py

@@ -7,6 +7,7 @@ from contextvars import ContextVar
 from dataclasses import dataclass
 
 from fastapi import Request
+from fastapi.routing import APIRoute, APIWebSocketRoute
 from starlette.types import Message, Scope
 
 from .types import DependencyCache
@@ -50,6 +51,14 @@ class InjectScope:
     dependency_cache: DependencyCache
     request: Request
 
+    @property
+    def path_format(self) -> str | None:
+        match self.request.scope:
+            case {"route": APIRoute() | APIWebSocketRoute() as route}:
+                return route.path_format
+            case _:
+                return None
+
 
 _inject_scope: ContextVar[InjectScope | None] = ContextVar(
     "_inject_scope",

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/fastapi_injected/types.py

@@ -1,6 +1,6 @@
 import inspect
-from collections.abc import Callable, Coroutine
-from typing import TYPE_CHECKING, Annotated, Any, Protocol, TypeVar
+from collections.abc import AsyncIterator, Callable, Coroutine, Iterator, Mapping
+from typing import TYPE_CHECKING, Annotated, Any, Protocol, TypeVar, runtime_checkable
 
 from fastapi import Depends
 from fastapi.types import DependencyCacheKey
@@ -49,14 +49,23 @@ class HasSignature(Protocol):
     __signature__: inspect.Signature
 
 
+@runtime_checkable
+class HasDependencyOverrides(Protocol):
+    dependency_overrides: Mapping[Any, Any]
+
+
+type DepReturn[R] = Coro[R] | Iterator[R] | AsyncIterator[R] | R
+
 __all__ = [
     "AsyncFunc",
     "Coro",
     "Decorator",
     "Dep",
     "DepFactory",
+    "DepReturn",
     "DependencyCache",
     "Func",
+    "HasDependencyOverrides",
     "HasSignature",
     "Injected",
 ]

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-injected"
-version = "0.1.4"
+version = "0.2.1"
 description = "Yet another library to reuse fastapi dependency injection"
 authors = [
     { name = "Yurii Karabas", email = "1998uriyyo@gmail.com" },
@@ -20,6 +20,7 @@ classifiers = [
 dependencies = [
     "fastapi>=0.139.2",
     "typing-extensions>=4.16.0",
+    "typing-inspection>=0.4.4",
 ]
 
 [dependency-groups]
@@ -65,6 +66,7 @@ ignore = [
     "FBT", # ignore flake8-boolean-trap
     "EM",  # ignore error message formatting
     "TC",  # ignore type checking
+    "CPY", # ignore copyright
 ]
 exclude = [
     ".bzr",

{fastapi_injected-0.1.4 → fastapi_injected-0.2.1}/tests/deps.py

@@ -28,9 +28,19 @@ class Container:
     ctx: DepFactory[ContextState, ctx_dep]
 
 
+def get_value() -> int:
+    return 1
+
+
+@dataclass
+class State:
+    value: DepFactory[int, get_value]
+
+
 __all__ = [
     "Child",
     "Container",
     "ContextState",
+    "State",
     "ctx_dep",
 ]