Dependencies - `Depends()` and `Security()`¶

`Depends()`¶

Dependencies are handled mainly with the special function Depends() that takes a callable.

Here is the reference for it and its parameters.

You can import it directly from fastapi:

from fastapi import Depends

fastapi.Depends ¶

Depends(
    dependency=None,
    *,
    use_cache=True,
    dependency_scope="endpoint"
)

Declare a FastAPI dependency.

It takes a single "dependable" callable (like a function).

Don't call it directly, FastAPI will call it for you.

Read more about it in the FastAPI docs for Dependencies.

Example

from typing import Annotated

from fastapi import Depends, FastAPI

app = FastAPI()


async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
    return {"q": q, "skip": skip, "limit": limit}


@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
    return commons

PARAMETER	DESCRIPTION
`dependency`	A "dependable" callable (like a function). Don't call it directly, FastAPI will call it for you, just pass the object directly. TYPE: `Optional[Callable[..., Any]]` DEFAULT: `None`
`use_cache`	By default, after a dependency is called the first time in a request, if the dependency is declared again for the rest of the request (for example if the dependency is needed by several dependencies), the value will be re-used for the rest of the request. Set `use_cache` to `False` to disable this behavior and ensure the dependency is called again (if declared more than once) in the same request. TYPE: `bool` DEFAULT: `True`
`dependency_scope`	The scope in which the dependency value should be evaluated. Can be either `"endpoint"` or `"lifespan"`. If `dependency_scope` is set to "endpoint" (the default), the dependency will be setup and teardown for every request. If `dependency_scope` is set to `"lifespan"` the dependency would be setup at the start of the entire application's lifespan. The evaluated dependency would be then reused across all endpoints. The dependency would be teared down as a part of the application's shutdown process. Note that dependencies defined with the `"endpoint"` scope may use sub-dependencies defined with the `"lifespan"` scope, but not the other way around; Dependencies defined with the `"lifespan"` scope may not use sub-dependencies with `"endpoint"` scope, nor can they use other "endpoint scoped" arguments such as "Path", "Body", "Query", or any other annotation which does not make sense in a scope of an application's entire lifespan. TYPE: `DependencyScope` DEFAULT: `'endpoint'`

Source code in fastapi/param_functions.py

def Depends(  # noqa: N802
    dependency: Annotated[
        Optional[Callable[..., Any]],
        Doc(
            """
            A "dependable" callable (like a function).

            Don't call it directly, FastAPI will call it for you, just pass the object
            directly.
            """
        ),
    ] = None,
    *,
    use_cache: Annotated[
        bool,
        Doc(
            """
            By default, after a dependency is called the first time in a request, if
            the dependency is declared again for the rest of the request (for example
            if the dependency is needed by several dependencies), the value will be
            re-used for the rest of the request.

            Set `use_cache` to `False` to disable this behavior and ensure the
            dependency is called again (if declared more than once) in the same request.
            """
        ),
    ] = True,
    dependency_scope: Annotated[
        DependencyScope,
        Doc(
            """
            The scope in which the dependency value should be evaluated. Can be
            either `"endpoint"` or `"lifespan"`.

            If `dependency_scope` is set to "endpoint" (the default), the
            dependency will be setup and teardown for every request.

            If `dependency_scope` is set to `"lifespan"` the dependency would
            be setup at the start of the entire application's lifespan. The
            evaluated dependency would be then reused across all endpoints.
            The dependency would be teared down as a part of the application's
            shutdown process.

            Note that dependencies defined with the `"endpoint"` scope may use
            sub-dependencies defined with the `"lifespan"` scope, but not the
            other way around;
            Dependencies defined with the `"lifespan"` scope may not use
            sub-dependencies with `"endpoint"` scope, nor can they use
            other "endpoint scoped" arguments such as "Path", "Body", "Query",
            or any other annotation which does not make sense in a scope of an
            application's entire lifespan.
            """
        ),
    ] = "endpoint",
) -> Any:
    """
    Declare a FastAPI dependency.

    It takes a single "dependable" callable (like a function).

    Don't call it directly, FastAPI will call it for you.

    Read more about it in the
    [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/).

    **Example**

    ```python
    from typing import Annotated

    from fastapi import Depends, FastAPI

    app = FastAPI()


    async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
        return {"q": q, "skip": skip, "limit": limit}


    @app.get("/items/")
    async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
        return commons
    ```
    """
    return params.Depends(
        dependency=dependency, use_cache=use_cache, dependency_scope=dependency_scope
    )

`Security()`¶

For many scenarios, you can handle security (authorization, authentication, etc.) with dependencies, using Depends().

But when you want to also declare OAuth2 scopes, you can use Security() instead of Depends().

You can import Security() directly from fastapi:

from fastapi import Security

fastapi.Security ¶

Security(dependency=None, *, scopes=None, use_cache=True)

Declare a FastAPI Security dependency.

The only difference with a regular dependency is that it can declare OAuth2 scopes that will be integrated with OpenAPI and the automatic UI docs (by default at /docs).

It takes a single "dependable" callable (like a function).

Don't call it directly, FastAPI will call it for you.

Read more about it in the FastAPI docs for Security and in the FastAPI docs for OAuth2 scopes.