fastapi-standalone-di 0.1.0__py3-none-any.whl

fastapi_standalone_di/__init__.py

@@ -0,0 +1,48 @@
+"""Use FastAPI's dependency injection outside of any web/ASGI context."""
+
+from fastapi_standalone_di.app_state import (
+    AppState,
+    get_app_state,
+    set_app_state_value,
+)
+from fastapi_standalone_di.registration import (
+    RegistrableDependency,
+    patch_for_registrable_dependency_support,
+)
+from fastapi_standalone_di.resolve import (
+    DependantCache,
+    DependencyOverrides,
+    DependencyScope,
+    FastAPIContainer,
+    MissingParameterError,
+    ParameterError,
+    ParameterValidationError,
+    ParamSource,
+    ResolutionScope,
+    ResolvedDependencies,
+    ScopeError,
+    get_container,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AppState",
+    "DependantCache",
+    "DependencyOverrides",
+    "DependencyScope",
+    "FastAPIContainer",
+    "MissingParameterError",
+    "ParamSource",
+    "ParameterError",
+    "ParameterValidationError",
+    "RegistrableDependency",
+    "ResolutionScope",
+    "ResolvedDependencies",
+    "ScopeError",
+    "__version__",
+    "get_app_state",
+    "get_container",
+    "patch_for_registrable_dependency_support",
+    "set_app_state_value",
+]

fastapi_standalone_di/_compat.py

@@ -0,0 +1,49 @@
+"""Version-independent introspection of a callable's execution model.
+
+FastAPI historically exposed ``is_async_gen_callable`` / ``is_gen_callable`` /
+``is_coroutine_callable`` as functions in ``fastapi.dependencies.utils`` (older
+releases) and later moved the information onto ``Dependant`` attributes,
+removing the module-level helpers. To stay compatible across the whole
+supported FastAPI range we reimplement the (small, stable) detection logic here
+instead of importing it — it depends only on the standard library.
+"""
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+
+def _unwrap(call: Callable[..., Any]) -> Callable[..., Any]:
+    while isinstance(call, functools.partial):
+        call = call.func
+    return call
+
+
+def is_async_gen_callable(call: Callable[..., Any]) -> bool:
+    """True if calling *call* returns an async generator."""
+    call = _unwrap(call)
+    if inspect.isasyncgenfunction(call):
+        return True
+    dunder_call = getattr(call, "__call__", None)  # noqa: B004
+    return inspect.isasyncgenfunction(dunder_call)
+
+
+def is_gen_callable(call: Callable[..., Any]) -> bool:
+    """True if calling *call* returns a (sync) generator."""
+    call = _unwrap(call)
+    if inspect.isgeneratorfunction(call):
+        return True
+    dunder_call = getattr(call, "__call__", None)  # noqa: B004
+    return inspect.isgeneratorfunction(dunder_call)
+
+
+def is_coroutine_callable(call: Callable[..., Any]) -> bool:
+    """True if *call* is a coroutine function (or a callable with one)."""
+    call = _unwrap(call)
+    if inspect.iscoroutinefunction(call):
+        return True
+    if inspect.isclass(call):
+        return False
+    dunder_call = getattr(call, "__call__", None)  # noqa: B004
+    return inspect.iscoroutinefunction(dunder_call)

fastapi_standalone_di/app_state.py

@@ -0,0 +1,128 @@
+"""Application state abstraction for FastAPI and standalone contexts.
+
+``AppState`` provides a unified interface to access application-level state
+(database clients, caches, managers, …) regardless of whether the code runs
+inside a FastAPI ASGI request or in a standalone context (CLI scripts,
+background tasks, :class:`~fastapi_standalone_di.resolve.FastAPIContainer`).
+
+In **FastAPI mode**, ``AppState`` delegates to ``request.app.state`` (Starlette's
+built-in state). In **standalone mode**, it falls back to an internal dict.
+
+Usage in a FastAPI dependency::
+
+    def get_db(app_state: AppState = Depends(get_app_state)) -> Database:
+        return app_state.get("db")
+
+Usage with ``FastAPIContainer``::
+
+    set_app_state_value("db", db_client)
+    container = FastAPIContainer()
+    db = await container.get(get_db)
+"""
+
+from typing import Any, ClassVar, Self
+
+from fastapi import FastAPI
+from starlette.datastructures import State
+from starlette.requests import HTTPConnection
+
+
+class AppState:
+    """Abstraction over Starlette's ``State`` that works with and without a request.
+
+    *  **FastAPI mode** — created via :meth:`from_request`; reads/writes go to
+       ``request.app.state``.
+    *  **Standalone mode** — created via :meth:`standalone`; reads/writes go to
+       a module-level singleton dict.
+    """
+
+    _standalone_instance: ClassVar[Self | None] = None
+
+    def __init__(self, state: State | None = None) -> None:
+        self._state = state
+        self._store: dict[str, Any] = {}
+
+    # --- read / write ---------------------------------------------------------
+
+    def get(self, key: str) -> Any | None:
+        if self._state is not None:
+            return getattr(self._state, key, None)
+        return self._store.get(key)
+
+    def set(self, key: str, value: Any) -> None:
+        if self._state is not None:
+            setattr(self._state, key, value)
+        else:
+            self._store[key] = value
+
+    def delete(self, key: str) -> None:
+        if self._state is not None:
+            if hasattr(self._state, key):
+                delattr(self._state, key)
+        else:
+            self._store.pop(key, None)
+
+    def as_state(self) -> State:
+        """Return a Starlette ``State`` backed by this ``AppState``'s storage.
+
+        Reads and writes on the returned ``State`` share the same underlying
+        store, so a stubbed ``request.app.state`` stays in sync with this
+        ``AppState`` (and with :func:`set_app_state_value`).
+        """
+        if self._state is not None:
+            return self._state
+        return State(self._store)
+
+    # --- constructors ---------------------------------------------------------
+
+    @classmethod
+    def from_request(cls, request: HTTPConnection) -> Self:
+        """Create an ``AppState`` backed by the ASGI application state."""
+        return cls(state=request.app.state)
+
+    @classmethod
+    def from_app(cls, app: FastAPI) -> Self:
+        """Create an ``AppState`` backed by a Starlette/FastAPI application."""
+        return cls(state=app.state)
+
+    @classmethod
+    def standalone(cls) -> Self:
+        """Return the module-level singleton (no ASGI context needed)."""
+        if cls._standalone_instance is None:
+            cls._standalone_instance = cls()
+        return cls._standalone_instance
+
+    @classmethod
+    def reset_standalone(cls) -> None:
+        """Reset the standalone singleton (useful in tests)."""
+        cls._standalone_instance = None
+
+
+# --- FastAPI dependency -------------------------------------------------------
+
+
+def get_app_state(
+    request: HTTPConnection = None,  # type: ignore[assignment]
+) -> AppState:
+    """FastAPI dependency that returns an :class:`AppState`.
+
+    When injected by FastAPI, *request* is provided automatically and the
+    returned ``AppState`` delegates to ``request.app.state``. When resolved
+    outside ASGI (e.g. via :class:`FastAPIContainer`), *request* is ``None`` and
+    the standalone singleton is used instead.
+    """
+    if request is not None:
+        return AppState.from_request(request)
+    return AppState.standalone()
+
+
+# --- convenience helpers for startup / scripts --------------------------------
+
+
+def set_app_state_value(key: str, value: Any) -> None:
+    """Set a value in the standalone ``AppState`` store.
+
+    Call this at application startup (alongside ``app.state.xxx = …``) so that
+    the value is available for both FastAPI and standalone contexts.
+    """
+    AppState.standalone().set(key, value)

fastapi_standalone_di/registration.py

@@ -0,0 +1,132 @@
+"""Registrable dependency interfaces for FastAPI.
+
+``RegistrableDependency`` lets you declare an *interface* (an abstract base)
+and depend on it via ``Depends(IMyService)`` while binding the concrete
+implementation elsewhere with ``IMyService.register(MyServiceImpl)``. This
+decouples the dependency declaration from its wiring, which is convenient both
+inside FastAPI routes and when resolving dependencies standalone via
+:class:`~fastapi_standalone_di.resolve.FastAPIContainer`.
+"""
+
+import inspect
+from collections.abc import Callable
+from inspect import isclass
+from typing import Any, Literal
+
+import fastapi.params
+
+
+class classproperty(property):
+    fget: Callable[[Any], Any]
+
+    def __init__(self, fget: Callable[[Any], Any], *arg: Any, **kw: Any):
+        super().__init__(fget, *arg, **kw)
+        self.__doc__ = fget.__doc__
+
+    def __get__(self, obj: Any, cls: type | None = None) -> Any:
+        return self.fget(cls)
+
+
+class RegistrableDependency:
+    """Base class for a dependency interface with a swappable implementation."""
+
+    _impl: Callable[..., Any] | None = None
+
+    @classproperty
+    def impl(cls) -> Callable[..., Any]:
+        return cls.dependency()
+
+    @classmethod
+    def register(cls, impl: Callable[..., Any] | None) -> None:
+        """Register (or clear, with ``None``) the implementation for this interface."""
+        cls._impl = impl
+
+    @classmethod
+    def dependency(cls) -> Callable[..., Any]:
+        """Entry point for ``fastapi.Depends``: return the registered implementation.
+
+        Raises :class:`RuntimeError` when no implementation is registered — it
+        never returns ``None``.
+        """
+        if cls._impl is None:
+            raise RuntimeError(
+                f"No implementation registered for {cls.__module__}.{cls.__name__}"
+            )
+        return cls._impl
+
+
+FastAPIDepends = fastapi.params.Depends
+
+# ``scope`` was added to ``Depends.__init__`` only in recent FastAPI; detect it
+# so ``_Depends`` stays constructible on older releases.
+_DEPENDS_SUPPORTS_SCOPE = (
+    "scope" in inspect.signature(FastAPIDepends.__init__).parameters
+)
+
+
+class _Depends(FastAPIDepends):
+    """A ``Depends`` that dereferences a ``RegistrableDependency`` to its impl.
+
+    ``scope`` (``"function"``/``"request"``) is forwarded to FastAPI for
+    introspection parity but has no intrinsic effect when resolving standalone:
+    there is no request lifecycle outside ASGI. :class:`FastAPIContainer`
+    interprets it only when its ``default_scope`` is a mapping keyed by these
+    literals; otherwise the value is inert.
+    """
+
+    # The ``scope`` branch is resolved once, at class-definition time, rather
+    # than on every instantiation.
+    if _DEPENDS_SUPPORTS_SCOPE:
+
+        def __init__(
+            self,
+            dependency: Callable[..., Any] | None = None,
+            *,
+            use_cache: bool = True,
+            scope: Literal["function", "request"] | None = None,
+        ):
+            FastAPIDepends.__init__(self, dependency, use_cache=use_cache, scope=scope)
+            self._dependency = dependency
+    else:
+
+        def __init__(
+            self,
+            dependency: Callable[..., Any] | None = None,
+            *,
+            use_cache: bool = True,
+            scope: Literal["function", "request"] | None = None,
+        ):
+            FastAPIDepends.__init__(self, dependency, use_cache=use_cache)
+            self._dependency = dependency
+
+    @property
+    def dependency(self) -> Callable[..., Any] | None:
+        return (
+            self._dependency.dependency()
+            if isclass(self._dependency)
+            and issubclass(self._dependency, RegistrableDependency)
+            else self._dependency
+        )
+
+    @dependency.setter
+    def dependency(self, value: Callable[..., Any] | None) -> None:
+        self._dependency = value
+
+
+def patch_for_registrable_dependency_support() -> bool:
+    """Patch ``fastapi.params.Depends`` to resolve ``RegistrableDependency`` eagerly.
+
+    Only needed when FastAPI itself must see the concrete implementation at
+    introspection time (e.g. for OpenAPI). :class:`FastAPIContainer` resolves the
+    indirection on its own and does not require this patch.
+
+    The patch only affects ``Depends`` objects created **after** it runs: any
+    ``Depends()`` already instantiated keeps the original class. Apply it at
+    import time, before the routes declaring the dependencies are defined.
+
+    Returns ``True`` if the patch was applied, ``False`` if already patched.
+    """
+    if FastAPIDepends is fastapi.params.Depends:
+        fastapi.params.Depends = _Depends  # type: ignore[assignment,misc]
+        return True
+    return False