Under the Hood of FastAPI’s DI Engine: Signature Reflection, Execution Graphs, and Async Exit Stacks

Niraj Matere — Sat, 12 Sep 2026 13:05:56 +0000

Dependency Injection (DI) in modern web frameworks is often treated as syntactic magic. In FastAPI, declaring commons: Annotated[dict, Depends(common_parameters)] in a route signature feels effortless. Behind this clean API lies a sophisticated, two-phase engine: a compile-time graph construction system powered by Python runtime signature reflection, and a runtime resolution pipeline leveraging contextlib.AsyncExitStack, thread pools, and cache keying.

In this deep dive, we will dismantle the internal mechanics of tiangolo/fastapi to explore how FastAPI inspects route handlers, builds recursive dependency models, executes graph nodes asynchronously, and manages resource lifecycles across HTTP request boundaries.

Architecture at a Glance: The Two-Phase Pipeline

FastAPI splits dependency injection into two distinct phases:

+----------------------------------------------------------------------------------+
| PHASE 1: COMPILE-TIME / APPLICATION BOOTSTRAP                                    |
| Route Definition --> inspect.signature() --> get_dependant() --> Dependant Graph |
+----------------------------------------------------------------------------------+
                                        |
                                        v
+----------------------------------------------------------------------------------+
| PHASE 2: RUNTIME / REQUEST HANDLING                                              |
| HTTP Request --> get_request_handler() --> solve_dependencies() --> Route Exec   |
|                          |                        |                              |
|                          v                        v                              |
|                  AsyncExitStack          Dependency Cache                        |
+----------------------------------------------------------------------------------+

(Architecture flow mapped using Documentor Pro, automated dependency graph mapping and codebase visualization)

Graph Construction Phase (Compile-Time): Occurs when routes are defined (@app.get(...)). FastAPI reflects on function signatures, unwraps typing.Annotated metadata, constructs parameter models, and builds a directed graph of Dependant objects.
Graph Resolution Phase (Runtime): Occurs per HTTP request inside get_request_handler(). FastAPI walks the Dependant tree, extracts parameters from the request (URL, query, headers, body), executes sub-dependencies (either concurrently in thread pools or natively via asyncio), caches resolved values, and tracks cleanup tasks inside an AsyncExitStack.

1. Compile-Time Graph Engine: Building the `Dependant` Tree

When an endpoint is registered, FastAPI does not inspect parameters on every incoming request. Instead, it inspects signatures once, generating a structural representation of the handler and its sub-dependencies.

The In-Memory Dataclass: `Dependant`

The entire injection model relies on the Dependant dataclass defined in fastapi/dependencies/models.py. It holds metadata about fields to extract from requests and sub-dependencies to execute:

@dataclass(slots=True)
class Dependant:
    path_params: list[ModelField] = field(default_factory=list)
    query_params: list[ModelField] = field(default_factory=list)
    header_params: list[ModelField] = field(default_factory=list)
    cookie_params: list[ModelField] = field(default_factory=list)
    body_params: list[ModelField] = field(default_factory=list)
    dependencies: list["Dependant"] = field(default_factory=list)
    name: str | None = None
    call: Callable[..., Any] | None = None
    request_param_name: str | None = None
    websocket_param_name: str | None = None
    http_connection_param_name: str | None = None
    response_param_name: str | None = None
    background_tasks_param_name: str | None = None
    security_scopes_param_name: str | None = None
    own_oauth_scopes: list[str] | None = None
    parent_oauth_scopes: list[str] | None = None
    use_cache: bool = True
    path: str | None = None
    scope: Literal["function", "request"] | None = None

A Dependant instance represents a node in the execution graph:

Target Callable (call): The function, class, or callable dependency to execute.
Child Nodes (dependencies): List of nested Dependant objects derived from Depends(...).
Field Extraction Lists (query_params, path_params, etc.): Pydantic ModelField structures mapped to input locations.
Ambient Objects (request_param_name, response_param_name): Parameter names requiring direct injection of Starlette ASGI primitives.

Introspecting Function Signatures: `get_dependant()`

The transformation of a route target into a Dependant tree begins in fastapi/dependencies/utils.py via get_dependant():

def get_dependant(
    *,
    path: str,
    call: Callable[..., Any],
    name: str | None = None,
    own_oauth_scopes: list[str] | None = None,
    parent_oauth_scopes: list[str] | None = None,
    use_cache: bool = True,
    scope: Literal["function", "request"] | None = None,
) -> Dependant:
    dependant = Dependant(
        call=call,
        name=name,
        path=path,
        use_cache=use_cache,
        scope=scope,
        own_oauth_scopes=own_oauth_scopes,
        parent_oauth_scopes=parent_oauth_scopes,
    )
    current_scopes = (parent_oauth_scopes or []) + (own_oauth_scopes or [])
    path_param_names = get_path_param_names(path)
    endpoint_signature = get_typed_signature(call)
    signature_params = endpoint_signature.parameters

    for param_name, param in signature_params.items():
        is_path_param = param_name in path_param_names
        param_details = analyze_param(
            param_name=param_name,
            annotation=param.annotation,
            value=param.default,
            is_path_param=is_path_param,
        )
        if param_details.depends is not None:
            assert param_details.depends.dependency
            # Check for invalid scope nesting
            if (
                (
                    _is_gen_callable(dependant.call)
                    or _is_async_gen_callable(dependant.call)
                )
                and _get_computed_scope(dependant=dependant) == "request"
                and param_details.depends.scope == "function"
            ):
                call_name = getattr(dependant.call, "__name__", "<unnamed_callable>")
                raise DependencyScopeError(
                    f'The dependency "{call_name}" has a scope of '
                    '"request", it cannot depend on dependencies with scope "function".'
                )

            sub_own_oauth_scopes: list[str] = []
            if isinstance(param_details.depends, params.Security):
                if param_details.depends.scopes:
                    sub_own_oauth_scopes = list(param_details.depends.scopes)

            # Recursive call: Build child Dependant node
            sub_dependant = get_dependant(
                path=path,
                call=param_details.depends.dependency,
                name=param_name,
                own_oauth_scopes=sub_own_oauth_scopes,
                parent_oauth_scopes=current_scopes,
                use_cache=param_details.depends.use_cache,
                scope=param_details.depends.scope,
            )
            dependant.dependencies.append(sub_dependant)
            continue

        if add_non_field_param_to_dependency(
            param_name=param_name,
            type_annotation=param_details.type_annotation,
            dependant=dependant,
        ):
            continue

        assert param_details.field is not None
        if isinstance(param_details.field.field_info, params.Body):
            dependant.body_params.append(param_details.field)
        else:
            add_param_to_fields(field=param_details.field, dependant=dependant)

    return dependant

Unpacking `Annotated` and Parameters: `analyze_param()`

How does FastAPI determine whether a parameter is a query param, body field, ASGI object, or sub-dependency?

analyze_param() parses Python's inspect.Parameter annotations. It handles both traditional parameter defaults (commons: dict = Depends(common_parameters)) and modern typing.Annotated forms (commons: Annotated[dict, Depends(common_parameters)]).

def analyze_param(
    *,
    param_name: str,
    annotation: Any,
    value: Any,
    is_path_param: bool,
) -> ParamDetails:
    field_info = None
    depends = None
    type_annotation: Any = Any
    use_annotation: Any = Any

    if is_typealiastype(annotation):
        annotation = annotation.__value__
    if annotation is not inspect.Signature.empty:
        use_annotation = annotation
        type_annotation = annotation

    # 1. Unpack typing.Annotated metadata
    if get_origin(use_annotation) is Annotated:
        annotated_args = get_args(annotation)
        type_annotation = annotated_args[0]
        fastapi_annotations = [
            arg for arg in annotated_args[1:]
            if isinstance(arg, (FieldInfo, params.Depends))
        ]
        # ... extracts the target Depends or FieldInfo instance ...
        if isinstance(fastapi_annotation, params.Depends):
            depends = fastapi_annotation

    # 2. Check default values if Annotated wasn't used
    if isinstance(value, params.Depends):
        depends = value

    # 3. Infer non-annotated implicit types (e.g., Request, Response, BackgroundTasks)
    if depends is None and lenient_issubclass(
        type_annotation,
        (Request, WebSocket, HTTPConnection, Response, StarletteBackgroundTasks, SecurityScopes),
    ):
        pass # Captured down the line via add_non_field_param_to_dependency

    # 4. Infer scalar vs scalar-sequence vs complex Pydantic body parameters
    elif field_info is None and depends is None:
        default_value = value if value is not inspect.Signature.empty else RequiredParam
        if is_path_param:
            field_info = params.Path(annotation=use_annotation)
        elif not field_annotation_is_scalar(annotation=type_annotation):
            field_info = params.Body(annotation=use_annotation, default=default_value)
        else:
            field_info = params.Query(annotation=use_annotation, default=default_value)

    # 5. Wrap in a Pydantic ModelField for validation engine
    if field_info is not None:
        field = create_model_field(
            name=param_name,
            type_=use_annotation,
            default=field_info.default,
            alias=alias,
            field_info=field_info,
        )

    return ParamDetails(type_annotation=type_annotation, depends=depends, field=field)

At the end of this compile-time phase, FastAPI holds a fully populated, recursive tree of Dependant objects. No type signatures or annotations need to be re-parsed during runtime request execution.

2. Fast Classification Caching for Callables

Dependencies can be standard synchronous functions (def), coroutines (async def), generator functions (yield), or async generators (async yield). Determining a callable's identity via inspection is expensive if done repeatedly.

FastAPI optimizes this in fastapi/dependencies/models.py by using an LRU-cached classification strategy combined with an explicit object identity wrapper:

class _CallIdentity:
    __slots__ = ("call",)
    def __init__(self, call: Callable[..., Any]) -> None:
        self.call = call
    def __hash__(self) -> int:
        return id(self.call)
    def __eq__(self, other: object) -> bool:
        return isinstance(other, _CallIdentity) and self.call is other.call

@lru_cache(maxsize=4096)
def _is_coroutine_callable_cached(call_identity: _CallIdentity) -> bool:
    call = call_identity.call
    if inspect.isroutine(_impartial(call)) and iscoroutinefunction(_impartial(call)):
        return True
    if inspect.isroutine(_unwrapped_call(call)) and iscoroutinefunction(_unwrapped_call(call)):
        return True
    # Unroll __call__ for callable instances/classes
    dunder_call = getattr(_impartial(call), "__call__", None)
    if dunder_call is None:
        return False
    return iscoroutinefunction(_impartial(dunder_call)) or iscoroutinefunction(_unwrapped_call(dunder_call))

def _is_coroutine_callable(call: Callable[..., Any] | None) -> bool:
    if call is None:
        return False
    return _is_coroutine_callable_cached(_CallIdentity(call))

By wrapping callable pointers with _CallIdentity (using Python's internal memory id()), FastAPI bypasses standard __eq__ comparisons on functional objects and caches execution classifications (is_coroutine, is_generator, is_async_generator) across up to 4,096 distinct dependency endpoints.

3. The Runtime Engine: Resolution & Execution Graph

When an HTTP request hits a route, Starlette routes the request to FastAPI’s endpoint wrapper created by get_request_handler().

The Handler Wrapper and Stacks Setup

Inside fastapi/routing.py, get_request_handler() prepares request parsing, invokes dependency resolution, and marshals response bodies:

async def app(request: Request) -> Response:
    # 1. Access middleware-level exit stack (used for auto-closing files)
    file_stack = request.scope.get("fastapi_middleware_astack")

    # 2. Extract parsed body bytes / Form multi-parts
    body: Any = None
    if body_field:
        if is_body_form:
            body = await request.form()
            file_stack.push_async_callback(body.close)
        else:
            body_bytes = await request.body()
            # JSON parsing logic omitted for brevity...

    # 3. Access inner exit stack for context-bound dependencies
    async_exit_stack = request.scope.get("fastapi_inner_astack")

    # 4. Resolve dependency execution graph
    solved_result = await solve_dependencies(
        request=request,
        dependant=dependant,
        body=body,
        dependency_overrides_provider=dependency_overrides_provider,
        async_exit_stack=async_exit_stack,
        embed_body_fields=embed_body_fields,
    )

    if solved_result.errors:
        raise RequestValidationError(errors=solved_result.errors)

    # 5. Run main path operation function with resolved dependency outputs
    raw_response = await run_endpoint_function(
        dependant=dependant, values=solved_result.values, is_coroutine=is_coroutine
    )

Solving Dependencies Recursively: `solve_dependencies()`

The actual graph execution takes place in solve_dependencies() (found in fastapi/dependencies/utils.py).

solve_dependencies() performs a depth-first post-order traversal across the dependency tree. Lower-level sub-dependencies are evaluated first, and their results are passed up to dependent callables.

async def solve_dependencies(
    *,
    request: Request | WebSocket,
    dependant: Dependant,
    body: dict[str, Any] | FormData | bytes | None = None,
    background_tasks: BackgroundTasks | None = None,
    response: Response | None = None,
    dependency_overrides_provider: Any | None = None,
    async_exit_stack: AsyncExitStack,
    embed_body_fields: bool = False,
    dependency_cache: dict[DependencyCacheKey, Any] | None = None,
    async_exit_stack_for_functions: AsyncExitStack | None = None,
) -> SolvedDependency:
    values: dict[str, Any] = {}
    errors: list[Any] = []
    if dependency_cache is None:
        dependency_cache = {}

    # 1. Resolve sub-dependencies recursively
    for sub_dependant in dependant.dependencies:
        sub_dependant_key = _get_cache_key(
            dependant=sub_dependant,
            uses_scopes_cache=uses_scopes_cache,
        )

        # Dependency Reuse Mechanism (Caching)
        if sub_dependant.use_cache and sub_dependant_key in dependency_cache:
            solved_result = dependency_cache[sub_dependant_key]
        else:
            solved_result = await solve_dependencies(
                request=request,
                dependant=sub_dependant,
                body=body,
                background_tasks=background_tasks,
                response=response,
                dependency_overrides_provider=dependency_overrides_provider,
                async_exit_stack=async_exit_stack,
                embed_body_fields=embed_body_fields,
                dependency_cache=dependency_cache,
                async_exit_stack_for_functions=async_exit_stack_for_functions,
            )
            if sub_dependant.use_cache:
                dependency_cache[sub_dependant_key] = solved_result.value

        if sub_dependant.name:
            values[sub_dependant.name] = solved_result.value

    # 2. Extract request field parameters (Path, Query, Headers, Body)
    # ... Validation via Pydantic model fields ...

    # 3. Inject Ambient FastAPI/Starlette context objects
    if dependant.request_param_name:
        values[dependant.request_param_name] = request
    if dependant.response_param_name:
        values[dependant.response_param_name] = response
    if dependant.background_tasks_param_name:
        values[dependant.background_tasks_param_name] = background_tasks

    # 4. Check for Dependency Overrides (e.g., during app.dependency_overrides testing)
    call = dependant.call
    if dependency_overrides_provider and getattr(dependency_overrides_provider, "dependency_overrides", None):
        if dependant.call in dependency_overrides_provider.dependency_overrides:
            call = dependency_overrides_provider.dependency_overrides[dependant.call]

    # 5. Execute node call target
    if call is not None:
        solved = await solve_generator(
            call=call,
            stack=target_stack,
            sub_values=values,
        ) if (_is_gen_callable(call) or _is_async_gen_callable(call)) else await run_callable(
            call=call,
            sub_values=values,
        )
        return SolvedDependency(value=solved, ...)

Understanding Cache Keys: Dependency Sharing

FastAPI guarantees that if multiple sub-dependencies request db: Session = Depends(get_db) within the same request context, get_db() runs only once if use_cache=True (default).

How are dependencies indexed? In fastapi/dependencies/models.py, _get_cache_key() builds a explicit tuple:

def _get_cache_key(
    *,
    dependant: Dependant,
    uses_scopes_cache: _UsesScopesCache | None = None,
) -> DependencyCacheKey:
    scopes_for_cache = (
        tuple(sorted(set(_get_oauth_scopes(dependant=dependant))))
        if _uses_scopes(dependant=dependant, cache=uses_scopes_cache)
        else ()
    )
    return (
        dependant.call,
        scopes_for_cache,
        _get_computed_scope(dependant=dependant) or "",
    )

A dependency's cache key is composed of three elements:

Target Callable Reference (dependant.call): Memory location of the target function or class.
Security Scopes (scopes_for_cache): If the dependency evaluates OAuth2 scopes (SecurityScopes), two dependencies pointing to the same function but requesting different permissions (['read'] vs ['write']) will generate different cache keys and execute independently.
Execution Scope (scope): "function" vs "request" scope isolation.

4. Resource Lifecycle Architecture: The Triple `AsyncExitStack`

Managing teardown logic (such as closing database sessions or network connections) safely across asynchronous contexts is a core challenge in web framework design.

FastAPI uses three scoped AsyncExitStack layers across the ASGI lifespan:

+-------------------------------------------------------------------------------+
| 1. fastapi_middleware_astack (AsyncExitStackMiddleware)                       |
|    Scope: Full ASGI Request-Response cycle                                    |
|    Role: Auto-closing uploaded files / form temp files                       |
+-------------------------------------------------------------------------------+
       |
       v
+-------------------------------------------------------------------------------+
| 2. fastapi_inner_astack (request_response)                                    |
|    Scope: Request execution boundaries & Yield teardown                       |
|    Role: Holds request-scoped & yield dependency context managers             |
+-------------------------------------------------------------------------------+
       |
       v
+-------------------------------------------------------------------------------+
| 3. fastapi_function_astack (request_response)                                 |
|    Scope: Path operation execution scope                                      |
|    Role: Holds function-scoped yield dependencies                             |
+-------------------------------------------------------------------------------+

Layer 1: File Cleanup Middleware

Defined in fastapi/middleware/asyncexitstack.py:

class AsyncExitStackMiddleware:
    def __init__(
        self, app: ASGIApp, context_name: str = "fastapi_middleware_astack"
    ) -> None:
        self.app = app
        self.context_name = context_name

    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
        async with AsyncExitStack() as stack:
            scope[self.context_name] = stack
            await self.app(scope, receive, send)

When multi-part form requests stream uploaded files to disk, Starlette creates temporary spool files. FastAPI registers cleanup handlers (file_stack.push_async_callback(body.close)) on fastapi_middleware_astack. These run after the entire HTTP response has been transmitted to the client.

Layer 2 & 3: Yield Dependencies and Exit Stacks

When a dependency uses yield instead of return, FastAPI converts the generator into an asynchronous context manager at runtime.

In fastapi/routing.py, request_response sets up inner stacks that wrap the response lifecycle:

def request_response(
    func: Callable[[Request], Awaitable[Response] | Response],
) -> ASGIApp:
    async def app(scope: Scope, receive: Receive, send: Send) -> None:
        request = Request(scope, receive, send)

        async def app(scope: Scope, receive: Receive, send: Send) -> None:
            response_awaited = False
            async with AsyncExitStack() as request_stack:
                scope["fastapi_inner_astack"] = request_stack
                async with AsyncExitStack() as function_stack:
                    scope["fastapi_function_astack"] = function_stack
                    response = await f(request)

                # Transmit response to the ASGI HTTP server
                await response(scope, receive, send)
                response_awaited = True

            if not response_awaited:
                raise FastAPIError(
                    "Response not awaited. There's a high chance that the application code "
                    "is raising an exception and a dependency with yield has a block with a "
                    "bare except, or a block with except Exception..."
                )

        await wrap_app_handling_exceptions(app, request)(scope, receive, send)

    return app

Here is the exact step-by-step execution path for a yield dependency (get_db):

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

Initialization: solve_dependencies encounters get_db. It detects a generator via _is_gen_callable(call).
Context Creation: FastAPI wraps the generator using contextmanager (or asynccontextmanager for async yield functions) or converts sync context managers using Starlette's contextmanager_in_threadpool.
Entering Context: FastAPI executes stack.enter_async_context(cm).
Yield Execution: The generator runs up to the yield statement. The yielded value (db) is returned and injected into dependent handlers.
Route Execution: The route handler runs and returns an HTTP Response.
Streaming Response: await response(scope, receive, send) transmits the payload over the socket.
Exiting Context: The async with AsyncExitStack() as request_stack block finishes and closes. The exit stack invokes __aexit__ on all registered context managers, resuming execution in get_db right after yield, which executes the finally: db.close() block.

5. Execution Context Isolation: Async Coroutines vs Sync Threadpools

FastAPI supports both async def and plain def functions for dependencies and route handlers. How does it execute synchronous code without blocking the main event loop?

During graph resolution inside solve_dependencies(), FastAPI routes call targets through concurrency utilities based on their signature classification:

async def run_routine(call: Callable, values: dict):
    if _is_coroutine_callable(call):
        return await call(**values)
    else:
        # Offload sync blocking functions to worker threads
        return await run_in_threadpool(call, **values)

async def dependencies: Executed natively on the main asyncio event loop.
def (sync) dependencies: Wrapped inside starlette.concurrency.run_in_threadpool and executed on an anyio worker threadpool.

This dual-path approach applies to standard return dependencies, yield dependencies, and route endpoint targets alike.

6. Scope Rules and Validation Guardrails

Dependencies in FastAPI can specify execution scopes: scope="function" or scope="request".

A common pitfall occurs when scoping mixed generator dependencies: a request-scoped generator dependency attempting to rely on a function-scoped sub-dependency.

During graph construction in get_dependant(), FastAPI explicitly enforces scope compatibility rules:

if (
    (_is_gen_callable(dependant.call) or _is_async_gen_callable(dependant.call))
    and _get_computed_scope(dependant=dependant) == "request"
    and param_details.depends.scope == "function"
):
    call_name = getattr(dependant.call, "__name__", "<unnamed_callable>")
    raise DependencyScopeError(
        f'The dependency "{call_name}" has a scope of "request", '
        'it cannot depend on dependencies with scope "function".'
    )

Because a request-scoped context outlives a function-scoped context, allowing this relationship would leave the request-scoped dependency referencing torn-down resources. Catching this during compile-time graph construction prevents runtime state corruption.

Visualizing Complex API Graphs in Production

As FastAPI codebases scale to dozens of routers and hundreds of nested Depends() calls, tracing sub-dependency trees manually in your head becomes unsustainable. Debugging execution order, identifying redundant dependency evaluations, and keeping documentation in sync with deep call graphs can drain team velocity.

That's why we built Documentor Pro. It analyzes your routes, resolves nested dependency trees, and produces living architectural diagrams and interactive documentation directly from your codebase, saving your team hours of manual tracing.

👉 Check out Documentor Pro to automatically map and document your FastAPI services.

Conclusion: Why FastAPI's Dependency Injection Engine Excels

FastAPI’s dependency injection system stands out because of its clear separation between compile-time inspection and runtime execution:

Zero Runtime Reflection Overhead: Function signatures, type annotations, and Annotated parameters are unwrapped once at application startup into an optimized Dependant graph.
Deterministic Caching: Dependencies are uniquely keyed via (Callable, SecurityScopes, Scope) tuples, avoiding duplicate work across request processing pipelines.
Robust Resource Teardown: By using layered AsyncExitStack primitives at the ASGI layer, yield dependencies guarantee resource cleanup even when requests fail mid-stream.
Seamless Async/Sync Bridging: Synchronous dependencies run transparently inside thread pools, preventing blocking calls from freezing the main event loop.

By viewing FastAPI's dependency injection as a static graph compiler paired with an AsyncExitStack runtime, backend developers can write cleaner code and build fast, leak-free Python services.

DEV Community: Niraj Matere