FastDepends

Dependencies in FastDepends can contain their own dependencies. You simply declare Depends requirements within the dependency function itself.

Caching Behavior: By default, FastDepends caches dependency responses for the duration of one @inject call task. If multiple nested dependencies require the same sub-dependency, that sub-dependency is executed only once and its result is shared. However, different @inject calls will have different caches.

To disable caching for a specific dependency and force it to execute every time it is requested, use Depends(..., cache=False).

from fast_depends import inject, Depends

def dependency_a():
    return "A"

def dependency_b(a: str = Depends(dependency_a)):
    return f"B with {a}"

@inject
def main_function(b: str = Depends(dependency_b)):
    return b

# To disable caching for dependency_a:
# def dependency_b(a: str = Depends(dependency_a, cache=False)):

FastDepends operates by shifting the heavy lifting to application startup time to ensure high performance during runtime. The process follows four main stages:

1. Initialization Time: FastDepends inspects your functions and builds a dependency graph. It creates special Pydantic models where the function's expected arguments are defined as model fields.
2. Runtime Argument Capture: When a function is called, FastDepends captures the incoming *args and **kwargs and uses them to initialize the function's representation models.
3. Dependency Execution: FastDepends executes the function's dependencies, passing the model fields as arguments, and then calls the original function.
4. Output Casting: Finally, FastDepends captures the function's output and casts it to the expected return type.

Because the library primarily works with *args and **kwargs, it remains framework-agnostic and can be integrated into various business domains and technologies. Runtime performance is comparable to Pydantic's speed because the library mostly performs type casting on pre-built models.

If you want to avoid overriding dependencies globally (which affects all tests), you can instantiate a local Provider object. This allows you to control overrides within a specific scope or for specific function calls using the dependency_overrides_provider argument in the @inject decorator.

Use the provider.scope(original, override) context manager to ensure the override is only active within that block.

from typing import Annotated
from fast_depends import Depends, Provider, inject

# Create a local provider instead of using the global one
provider = Provider()

def abc_func() -> int:
    raise Exception("Original dependency called!")

def real_func() -> int:
    return 1

# Pass the custom provider to the @inject decorator
@inject(dependency_overrides_provider=provider)
def func(
    dependency: Annotated[int, Depends(abc_func)]
) -> int:
    return dependency

# Use the scope context manager to apply the override locally
with provider.scope(abc_func, real_func):
    assert func() == 1

Starlette handlers typically receive only a single request argument. To use FastDepends with Starlette, you must create a wrapper that unwraps the request object into keyword arguments (kwargs) so that dependency injection can function. This is achieved by wrapping the original handler with fast_depends.inject and a custom Starlette-specific wrapper.

To implement this, you need to:

1. Define a custom field (e.g., Path) to extract data from the request.
2. Create a wrapper function (e.g., @wrap_starlette) that handles the Starlette request lifecycle and calls the injected handler.
3. Apply @wrap_starlette and fast_depends.inject to your route handlers.

from typing import Annotated
from starlette.responses import PlainTextResponse
from starlette.routing import Route
from starlette.applications import Starlette
from fast_depends import Depends, inject

# 1. Define a Custom Field to extract from request
class Path:
    def __init__(self, name: str):
        self.name = name

# 2. Create the Starlette wrapper to unwrap 'request' into kwargs
def wrap_starlette(handler):
    @inject
    async def wrapper(request, **kwargs):
        # Logic to extract path params from request and pass to handler
        # (Implementation details would go here to map request.path_params to kwargs)
        return await handler(request, **kwargs)
    return wrapper

# 3. Usage with Dependencies and Annotated
@wrap_starlette
async def get_user(user_id: Annotated[int, Path("user_id")]):
    return f"user {user_id}"

@wrap_starlette
async def hello(user: str = Depends(get_user)):
    return PlainTextResponse(f"Hello, {user}!")

app = Starlette(debug=True, routes=[
    Route("/{user_id}", hello)
])

To avoid ambiguity between Python's positional argument parsing and FastDepends dependency injection, follow these recommendations:

1. Avoid positional arguments for Annotated types: Do not rely on positional arguments when calling functions that use Annotated dependencies. If you call func(1) where func(user: CurrentUser, user_id: int = None) is defined, FastDepends may attempt to map the positional value to the first parameter (user), leading to errors.
2. Use Named Arguments: Always use keyword arguments (e.g., func(user_id=1)) when calling functions with Annotated dependencies.
3. Use pydantic.Field: The most robust way to define dependencies is to use pydantic.Field within Annotated for all parameters. This explicitly defines requirements and avoids misunderstanding between the developer, Python, and FastDepends.

Recommended Pattern:

def func(user_id: Annotated[int, Field(...)], user: CurrentUser): ...