Managers

plateforme.core.api.base

This module provides the foundational components for creating the API of the Plateforme framework using FastAPI and Starlette features. It includes classes and utilities for API management and interaction.

APIManagerType module-attribute

APIManagerType = TypeVar(
    "APIManagerType", bound="APIManager"
)

A type variable for the API manager.

APIManager

APIManager(
    *,
    debug: bool = False,
    routes: list[BaseRoute] | None = None,
    title: str | None = None,
    summary: str | None = None,
    description: str | None = None,
    version: str | None = None,
    openapi_url: str | None = "/openapi.json",
    openapi_tags: list[dict[str, Any]] | None = None,
    servers: list[dict[str, Any]] | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    default_response_class: type[Response] = Default(
        JSONResponse
    ),
    redirect_slashes: bool = True,
    docs_url: str | None = "/docs",
    redoc_url: str | None = "/redoc",
    swagger_ui_oauth2_redirect_url: str
    | None = "/docs/oauth2-redirect",
    swagger_ui_init_oauth: dict[str, Any] | None = None,
    middleware: Sequence[Middleware] | None = None,
    exception_handlers: dict[
        int | type[Exception],
        Callable[
            [Request, Any], Coroutine[Any, Any, Response]
        ],
    ]
    | None = None,
    lifespan: Lifespan[APIManagerType] | None = None,
    terms_of_service: str | None = None,
    contact: dict[str, Any] | None = None,
    license_info: dict[str, Any] | None = None,
    openapi_prefix: str = "",
    root_path: str = "",
    root_path_in_servers: bool = True,
    responses: dict[int | str, dict[str, Any]]
    | None = None,
    callbacks: list[BaseRoute] | None = None,
    webhooks: APIRouter | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    swagger_ui_parameters: dict[str, Any] | None = None,
    generate_unique_id_function: APIBaseRouteIdentifier = Default(
        generate_unique_id
    ),
    separate_input_output_schemas: bool = True,
    **extra: Any,
)

Bases: FastAPI

A manager for the API.

Manages API settings, routes, and lifecycle events for Plateforme. It inherits from Starlette and FastAPI to utilize their core features while adding custom management capabilities specific to Plateforme's API requirements.

Initialize the API manager.

FIXME: Override routing methods (see router).

Parameters:

Name	Type	Description	Default
debug	bool	Boolean indicating if debug tracebacks should be returned on server errors. Defaults to False.	False
routes	list[BaseRoute] | None	A collection of routes to be included in the router to serve incoming HTTP and WebSocket requests. This is not recommended for general use, as it bypasses the traditional routing system. Defaults to None.	None
title	str | None	The title of the API. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to 'Plateforme'.	None
summary	str | None	A short summary of the API. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
description	str | None	A description of the API. Supports Markdown (using CommonMark syntax). It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to an empty string ''.	None
version	str | None	The version of the API. This is the version of your application, not the version of the OpenAPI specification nor the version of Plateforme being used. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to '0.1.0'.	None
openapi_url	str | None	The URL where the OpenAPI schema will be served from. If you set it to None, no OpenAPI schema will be served publicly, and the default automatic endpoints /docs and /redoc will also be disabled. Defaults to '/openapi.json'.	'/openapi.json'
openapi_tags	list[dict[str, Any]] | None	A list of tags used by OpenAPI, these are the same tags you can set in the path operations. The order of the tags can be used to specify the order shown in tools like Swagger UI, used in the automatic path /docs. It's not required to specify all the tags used. The tags that are not declared MAY be organized randomly or based on the tool's logic. Each tag name in the list MUST be unique. The value of each item is a dict containing: - name: The name of the tag. - description: A short description of the tag. CommonMark syntax MAY be used for rich text representation. - externalDocs: Additional external documentation for this tag. If provided, it would contain a dict with: - description: A short description of the target documentation. CommonMark syntax MAY be used for rich text representation. - url: The URL for the target documentation. Value MUST be in the form of a URL. Defaults to None.	None
servers	list[dict[str, Any]] | None	A list of dicts with connectivity information to a target server. You would use it, for example, if your application is served from different domains and you want to use the same Swagger UI in the browser to interact with each of them (instead of having multiple browser tabs open). Or if you want to leave fixed the possible URLs. If the servers list is not provided, or is an empty list, the default value would be a dict with a url value of /. Each item in the list is a dict containing: - url: A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named inside brackets {}. - description: An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation. - variables: A dict between a variable name and its value. The value is used for substitution in the server's URL template. Defaults to None.	None
dependencies	Sequence[DependsInfo] | None	A list of global dependencies, they will be applied to each path operation, including in sub-routers. Defaults to None.	None
default_response_class	type[Response]	The default response class to be used. Defaults to JSONResponse.	Default(JSONResponse)
redirect_slashes	bool	Whether to detect and redirect slashes in URLs when the client doesn't use the same format. Defaults to True.	True
docs_url	str | None	The path to the automatic interactive API documentation. It is handled in the browser by Swagger UI. The default URL is /docs. You can disable it by setting it to None. If openapi_url is set to None, this will be automatically disabled. Defaults to '/docs'.	'/docs'
redoc_url	str | None	The path to the alternative automatic interactive API documentation provided by ReDoc. The default URL is /redoc. You can disable it by setting it to None. If openapi_url is set to None, this will be automatically disabled. Defaults to '/redoc'.	'/redoc'
swagger_ui_oauth2_redirect_url	str | None	The OAuth2 redirect endpoint for the Swagger UI. By default it is /docs/oauth2-redirect. This is only used if you use OAuth2 (with the "Authorize" button) with Swagger UI. Defaults to '/docs/oauth2-redirect'.	'/docs/oauth2-redirect'
swagger_ui_init_oauth	dict[str, Any] | None	OAuth2 configuration for the Swagger UI, by default shown at /docs. Defaults to None.	None
middleware	Sequence[Middleware] | None	List of middleware to be added when creating the application. You can do this with api.add_middleware() instead. Defaults to None.	None
exception_handlers	dict[int | type[Exception], Callable[[Request, Any], Coroutine[Any, Any, Response]]] | None	A dictionary with handlers for exceptions. You can use the decorator @api.exception_handler() instead. Defaults to None.	None
lifespan	Lifespan[APIManagerType] | None	The Lifespan context manager handler for events to be executed when the router starts up and shuts down. It defines a collection of on_startup and on_shutdown events. Defaults to None.	None
terms_of_service	str | None	A URL to the Terms of Service for your API. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
contact	dict[str, Any] | None	A dictionary with the contact information for the exposed API. It can contain several fields: - name: (str) The name of the contact person/organization. - url: (str) A URL pointing to the contact information. It MUST be in the format of a URL. - email: (str) The email address of the contact person/organization. It MUST be in the format of an email address. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
license_info	dict[str, Any] | None	A dictionary with the license information for the exposed API. It can contain several fields: - name: (str) REQUIRED (if a license_info is set). The license name used for the API. - identifier: (str) An SPDX license expression for the API. The identifier field is mutually exclusive of the url field. Available since OpenAPI 3.1.0. - url: (str) A URL to the license used for the API. This MUST be the format of a URL. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
openapi_prefix	str	A URL prefix for the OpenAPI URL. Defaults to an empty string ''.	''
root_path	str	A path prefix handled by a proxy that is not seen by the application but is seen by external clients, which affects things like Swagger UI. Defaults to an empty string ''.	''
root_path_in_servers	bool	To disable automatically generating the URLs in the servers field in the autogenerated OpenAPI using the root_path. Defaults to True.	True
responses	dict[int | str, dict[str, Any]] | None	Additional responses to be shown in OpenAPI. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
callbacks	list[BaseRoute] | None	OpenAPI callbacks that should apply to all path operations. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
webhooks	APIRouter | None	Add OpenAPI webhooks. This is similar to callbacks but it doesn't require a response. Defaults to None.	None
deprecated	bool | None	Boolean indicating if the API is deprecated. Defaults to None.	None
include_in_schema	bool	Boolean indicating if the API should be included in the OpenAPI schema. Defaults to True.	True
swagger_ui_parameters	dict[str, Any] | None	Additional parameters to pass to the Swagger UI. Defaults to None.	None
generate_unique_id_function	APIBaseRouteIdentifier	A function that generates a unique ID for a given route. Defaults to generate_unique_id.	Default(generate_unique_id)
separate_input_output_schemas	bool	Boolean indicating if input and output schemas should be separate. Defaults to True.	True
**extra	Any	Additional parameters to pass to the application.	{}

Source code in .venv/lib/python3.12/site-packages/plateforme/core/api/base.py

def __init__(
    self: APIManagerType,
    *,
    debug: bool = False,
    routes: list[BaseRoute] | None = None,
    title: str | None = None,
    summary: str | None = None,
    description: str | None = None,
    version: str | None = None,
    openapi_url: str | None = '/openapi.json',
    openapi_tags: list[dict[str, Any]] | None = None,
    servers: list[dict[str, Any]] | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    default_response_class: type[Response] = Default(JSONResponse),
    redirect_slashes: bool = True,
    docs_url: str | None = '/docs',
    redoc_url: str | None = '/redoc',
    swagger_ui_oauth2_redirect_url: str | None = '/docs/oauth2-redirect',
    swagger_ui_init_oauth: dict[str, Any] | None = None,
    middleware: Sequence[Middleware] | None = None,
    exception_handlers: dict[
        int | type[Exception],
        Callable[[Request, Any], Coroutine[Any, Any, Response]],
    ] | None = None,
    lifespan: Lifespan[APIManagerType] | None = None,
    terms_of_service: str | None = None,
    contact: dict[str, Any] | None = None,
    license_info: dict[str, Any] | None = None,
    openapi_prefix: str = '',
    root_path: str = '',
    root_path_in_servers: bool = True,
    responses: dict[int | str, dict[str, Any]] | None = None,
    callbacks: list[BaseRoute] | None = None,
    webhooks: APIRouter | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    swagger_ui_parameters: dict[str, Any] | None = None,
    generate_unique_id_function: APIBaseRouteIdentifier = \
        Default(generate_unique_id),
    separate_input_output_schemas: bool = True,
    **extra: Any,
) -> None:
    """Initialize the API manager.

    FIXME: Override routing methods (see router).

    Args:
        debug: Boolean indicating if debug tracebacks should be returned on
            server errors. Defaults to ``False``.
        routes: A collection of routes to be included in the router to
            serve incoming HTTP and WebSocket requests. This is not
            recommended for general use, as it bypasses the traditional
            routing system. Defaults to ``None``.
        title: The title of the API. It will be added to the generated
            OpenAPI (e.g. visible at ``/docs``).
            Defaults to ``'Plateforme'``.
        summary: A short summary of the API. It will be added to the
            generated OpenAPI (e.g. visible at ``/docs``).
            Defaults to ``None``.
        description: A description of the API. Supports Markdown (using
            CommonMark syntax). It will be added to the generated OpenAPI
            (e.g. visible at ``/docs``).
            Defaults to an empty string ``''``.
        version: The version of the API. This is the version of your
            application, not the version of the OpenAPI specification nor
            the version of Plateforme being used. It will be added to the
            generated OpenAPI (e.g. visible at ``/docs``).
            Defaults to ``'0.1.0'``.
        openapi_url: The URL where the OpenAPI schema will be served from.
            If you set it to ``None``, no OpenAPI schema will be served
            publicly, and the default automatic endpoints ``/docs`` and
            ``/redoc`` will also be disabled.
            Defaults to ``'/openapi.json'``.
        openapi_tags: A list of tags used by OpenAPI, these are the same
            ``tags`` you can set in the path operations. The order of the
            tags can be used to specify the order shown in tools like
            Swagger UI, used in the automatic path ``/docs``. It's not
            required to specify all the tags used. The tags that are not
            declared MAY be organized randomly or based on the tool's
            logic. Each tag name in the list MUST be unique. The value of
            each item is a dict containing:
            - ``name``: The name of the tag.
            - ``description``: A short description of the tag. CommonMark
                syntax MAY be used for rich text representation.
            - ``externalDocs``: Additional external documentation for this
                tag. If provided, it would contain a dict with:
                - ``description``: A short description of the target
                    documentation. CommonMark syntax MAY be used for rich
                    text representation.
                - ``url``: The URL for the target documentation. Value MUST
                    be in the form of a URL.
            Defaults to ``None``.
        servers: A list of dicts with connectivity information to a target
            server. You would use it, for example, if your application is
            served from different domains and you want to use the same
            Swagger UI in the browser to interact with each of them
            (instead of having multiple browser tabs open). Or if you want
            to leave fixed the possible URLs. If the servers list is not
            provided, or is an empty list, the default value would be a
            dict with a ``url`` value of ``/``. Each item in the list is a
            dict containing:
            - ``url``: A URL to the target host. This URL supports Server
                Variables and MAY be relative, to indicate that the host
                location is relative to the location where the OpenAPI
                document is being served. Variable substitutions will be
                made when a variable is named inside brackets ``{}``.
            - ``description``: An optional string describing the host
                designated by the URL. CommonMark syntax MAY be used for
                rich text representation.
            - ``variables``: A dict between a variable name and its value.
                The value is used for substitution in the server's URL
                template.
            Defaults to ``None``.
        dependencies: A list of global dependencies, they will be applied
            to each path operation, including in sub-routers.
            Defaults to ``None``.
        default_response_class: The default response class to be used.
            Defaults to ``JSONResponse``.
        redirect_slashes: Whether to detect and redirect slashes in URLs
            when the client doesn't use the same format.
            Defaults to ``True``.
        docs_url: The path to the automatic interactive API documentation.
            It is handled in the browser by Swagger UI. The default URL is
            ``/docs``. You can disable it by setting it to ``None``. If
            ``openapi_url`` is set to ``None``, this will be automatically
            disabled. Defaults to ``'/docs'``.
        redoc_url: The path to the alternative automatic interactive API
            documentation provided by ReDoc. The default URL is ``/redoc``.
            You can disable it by setting it to ``None``. If
            ``openapi_url`` is set to ``None``, this will be automatically
            disabled. Defaults to ``'/redoc'``.
        swagger_ui_oauth2_redirect_url: The OAuth2 redirect endpoint for
            the Swagger UI. By default it is ``/docs/oauth2-redirect``.
            This is only used if you use OAuth2 (with the "Authorize"
            button) with Swagger UI.
            Defaults to ``'/docs/oauth2-redirect'``.
        swagger_ui_init_oauth: OAuth2 configuration for the Swagger UI, by
            default shown at ``/docs``. Defaults to ``None``.
        middleware: List of middleware to be added when creating the
            application. You can do this with ``api.add_middleware()``
            instead. Defaults to ``None``.
        exception_handlers: A dictionary with handlers for exceptions. You
            can use the decorator ``@api.exception_handler()`` instead.
            Defaults to ``None``.
        lifespan: The `Lifespan` context manager handler for events to be
            executed when the router starts up and shuts down. It defines
            a collection of ``on_startup`` and ``on_shutdown`` events.
            Defaults to ``None``.
        terms_of_service: A URL to the Terms of Service for your API. It
            will be added to the generated OpenAPI (e.g. visible at
            ``/docs``). Defaults to ``None``.
        contact: A dictionary with the contact information for the exposed
            API. It can contain several fields:
            - ``name``: (str) The name of the contact person/organization.
            - ``url``: (str) A URL pointing to the contact information.
                It MUST be in the format of a URL.
            - ``email``: (str) The email address of the contact
                person/organization. It MUST be in the format of an email
                address. It will be added to the generated OpenAPI (e.g.
                visible at ``/docs``). Defaults to ``None``.
        license_info: A dictionary with the license information for the
            exposed API. It can contain several fields:
            - ``name``: (str) **REQUIRED** (if a ``license_info`` is set).
                The license name used for the API.
            - ``identifier``: (str) An SPDX license expression for the API.
                The ``identifier`` field is mutually exclusive of the
                ``url`` field. Available since OpenAPI 3.1.0.
            - ``url``: (str) A URL to the license used for the API. This
                MUST be the format of a URL. It will be added to the
                generated OpenAPI (e.g. visible at ``/docs``).
                Defaults to ``None``.
        openapi_prefix: A URL prefix for the OpenAPI URL. Defaults to an
            empty string ``''``.
        root_path: A path prefix handled by a proxy that is not seen by the
            application but is seen by external clients, which affects
            things like Swagger UI. Defaults to an empty string ``''``.
        root_path_in_servers: To disable automatically generating the URLs
            in the ``servers`` field in the autogenerated OpenAPI using the
            ``root_path``. Defaults to ``True``.
        responses: Additional responses to be shown in OpenAPI. It will be
            added to the generated OpenAPI (e.g. visible at ``/docs``).
            Defaults to ``None``.
        callbacks: OpenAPI callbacks that should apply to all path
            operations. It will be added to the generated OpenAPI (e.g.
            visible at ``/docs``). Defaults to ``None``.
        webhooks: Add OpenAPI webhooks. This is similar to ``callbacks``
            but it doesn't require a response. Defaults to ``None``.
        deprecated: Boolean indicating if the API is deprecated.
            Defaults to ``None``.
        include_in_schema: Boolean indicating if the API should be included
            in the OpenAPI schema. Defaults to ``True``.
        swagger_ui_parameters: Additional parameters to pass to the Swagger
            UI. Defaults to ``None``.
        generate_unique_id_function: A function that generates a unique ID
            for a given route. Defaults to ``generate_unique_id``.
        separate_input_output_schemas: Boolean indicating if input and
            output schemas should be separate. Defaults to ``True``.
        **extra: Additional parameters to pass to the application.
    """
    # Handle default values
    title = title or 'Plateforme'
    description = description or ''
    version = version or '0.1.0'

    # Initialize the FastAPI application.
    super().__init__(
        debug=debug,
        routes=routes,
        title=title,
        summary=summary,
        description=description,
        version=version,
        openapi_url=openapi_url,
        openapi_tags=openapi_tags,
        servers=servers,
        dependencies=dependencies,
        default_response_class=default_response_class,
        redirect_slashes=redirect_slashes,
        docs_url=docs_url,
        redoc_url=redoc_url,
        swagger_ui_oauth2_redirect_url=swagger_ui_oauth2_redirect_url,
        swagger_ui_init_oauth=swagger_ui_init_oauth,
        middleware=middleware,
        exception_handlers=exception_handlers,
        lifespan=lifespan,
        terms_of_service=terms_of_service,
        contact=contact,
        license_info=license_info,
        openapi_prefix=openapi_prefix,
        root_path=root_path,
        root_path_in_servers=root_path_in_servers,
        responses=responses,
        callbacks=callbacks,
        webhooks=webhooks,
        deprecated=deprecated,
        include_in_schema=include_in_schema,
        swagger_ui_parameters=swagger_ui_parameters,
        generate_unique_id_function=
            generate_unique_id_function,  # type: ignore[arg-type]
        separate_input_output_schemas=separate_input_output_schemas,
        **extra,
    )

    # Initialize the manager router.
    self.router: APIRouter = APIRouter(
        routes=self.routes,
        redirect_slashes=redirect_slashes,
        dependency_overrides_provider=self,
        lifespan=lifespan,
        default_response_class=default_response_class,
        dependencies=dependencies,
        callbacks=callbacks,
        deprecated=deprecated,
        include_in_schema=include_in_schema,
        responses=responses,
        generate_unique_id_function=generate_unique_id_function,
    )

on_event

on_event(
    event_type: Annotated[
        str,
        Doc(
            "\n                The type of event. `startup` or `shutdown`.\n                "
        ),
    ],
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add an event handler for the application.

on_event is deprecated, use lifespan event handlers instead.

Read more about it in the FastAPI docs for Lifespan Events.

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

@deprecated(
    """
    on_event is deprecated, use lifespan event handlers instead.

    Read more about it in the
    [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
    """
)
def on_event(
    self,
    event_type: Annotated[
        str,
        Doc(
            """
            The type of event. `startup` or `shutdown`.
            """
        ),
    ],
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add an event handler for the application.

    `on_event` is deprecated, use `lifespan` event handlers instead.

    Read more about it in the
    [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated).
    """
    return self.router.on_event(event_type)

exception_handler

exception_handler(
    exc_class_or_status_code: Annotated[
        Union[int, Type[Exception]],
        Doc(
            "\n                The Exception class this would handle, or a status code.\n                "
        ),
    ],
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add an exception handler to the app.

Read more about it in the FastAPI docs for Handling Errors.

Example

from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse


class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name


app = FastAPI()


@app.exception_handler(UnicornException)
async def unicorn_exception_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
    )

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def exception_handler(
    self,
    exc_class_or_status_code: Annotated[
        Union[int, Type[Exception]],
        Doc(
            """
            The Exception class this would handle, or a status code.
            """
        ),
    ],
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add an exception handler to the app.

    Read more about it in the
    [FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/).

    ## Example

    ```python
    from fastapi import FastAPI, Request
    from fastapi.responses import JSONResponse


    class UnicornException(Exception):
        def __init__(self, name: str):
            self.name = name


    app = FastAPI()


    @app.exception_handler(UnicornException)
    async def unicorn_exception_handler(request: Request, exc: UnicornException):
        return JSONResponse(
            status_code=418,
            content={"message": f"Oops! {exc.name} did something. There goes a rainbow..."},
        )
    ```
    """

    def decorator(func: DecoratedCallable) -> DecoratedCallable:
        self.add_exception_handler(exc_class_or_status_code, func)
        return func

    return decorator

route

route(
    path: str,
    methods: list[str] | None = None,
    name: str | None = None,
    include_in_schema: bool = True,
) -> Callable

We no longer document this decorator style API, and its usage is discouraged. Instead you should use the following approach:

routes = [Route(path, endpoint=...), ...] app = Starlette(routes=routes)

Source code in .venv/lib/python3.12/site-packages/starlette/applications.py

def route(
    self,
    path: str,
    methods: list[str] | None = None,
    name: str | None = None,
    include_in_schema: bool = True,
) -> typing.Callable:  # type: ignore[type-arg]
    """
    We no longer document this decorator style API, and its usage is discouraged.
    Instead you should use the following approach:

    >>> routes = [Route(path, endpoint=...), ...]
    >>> app = Starlette(routes=routes)
    """
    warnings.warn(
        "The `route` decorator is deprecated, and will be removed in version 1.0.0. "  # noqa: E501
        "Refer to https://www.starlette.io/routing/ for the recommended approach.",  # noqa: E501
        DeprecationWarning,
    )

    def decorator(func: typing.Callable) -> typing.Callable:  # type: ignore[type-arg]  # noqa: E501
        self.router.add_route(
            path,
            func,
            methods=methods,
            name=name,
            include_in_schema=include_in_schema,
        )
        return func

    return decorator

middleware

middleware(
    middleware_type: Annotated[
        str,
        Doc(
            "\n                The type of middleware. Currently only supports `http`.\n                "
        ),
    ],
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a middleware to the application.

Read more about it in the FastAPI docs for Middleware.

Example

import time

from fastapi import FastAPI, Request

app = FastAPI()


@app.middleware("http")
async def add_process_time_header(request: Request, call_next):
    start_time = time.time()
    response = await call_next(request)
    process_time = time.time() - start_time
    response.headers["X-Process-Time"] = str(process_time)
    return response

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def middleware(
    self,
    middleware_type: Annotated[
        str,
        Doc(
            """
            The type of middleware. Currently only supports `http`.
            """
        ),
    ],
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a middleware to the application.

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

    ## Example

    ```python
    import time

    from fastapi import FastAPI, Request

    app = FastAPI()


    @app.middleware("http")
    async def add_process_time_header(request: Request, call_next):
        start_time = time.time()
        response = await call_next(request)
        process_time = time.time() - start_time
        response.headers["X-Process-Time"] = str(process_time)
        return response
    ```
    """

    def decorator(func: DecoratedCallable) -> DecoratedCallable:
        self.add_middleware(BaseHTTPMiddleware, dispatch=func)
        return func

    return decorator

openapi

openapi() -> Dict[str, Any]

Generate the OpenAPI schema of the application. This is called by FastAPI internally.

The first time it is called it stores the result in the attribute app.openapi_schema, and next times it is called, it just returns that same result. To avoid the cost of generating the schema every time.

If you need to modify the generated OpenAPI schema, you could modify it.

Read more in the FastAPI docs for OpenAPI.

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def openapi(self) -> Dict[str, Any]:
    """
    Generate the OpenAPI schema of the application. This is called by FastAPI
    internally.

    The first time it is called it stores the result in the attribute
    `app.openapi_schema`, and next times it is called, it just returns that same
    result. To avoid the cost of generating the schema every time.

    If you need to modify the generated OpenAPI schema, you could modify it.

    Read more in the
    [FastAPI docs for OpenAPI](https://fastapi.tiangolo.com/how-to/extending-openapi/).
    """
    if not self.openapi_schema:
        self.openapi_schema = get_openapi(
            title=self.title,
            version=self.version,
            openapi_version=self.openapi_version,
            summary=self.summary,
            description=self.description,
            terms_of_service=self.terms_of_service,
            contact=self.contact,
            license_info=self.license_info,
            routes=self.routes,
            webhooks=self.webhooks.routes,
            tags=self.openapi_tags,
            servers=self.servers,
            separate_input_output_schemas=self.separate_input_output_schemas,
        )
    return self.openapi_schema

websocket

websocket(
    path: Annotated[
        str,
        Doc(
            "\n                WebSocket path.\n                "
        ),
    ],
    name: Annotated[
        Optional[str],
        Doc(
            "\n                A name for the WebSocket. Only used internally.\n                "
        ),
    ] = None,
    *,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be used for this\n                WebSocket.\n\n                Read more about it in the\n                [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).\n                "
        ),
    ] = None,
) -> Callable[[DecoratedCallable], DecoratedCallable]

Decorate a WebSocket function.

Read more about it in the FastAPI docs for WebSockets.

Example

from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Message text was: {data}")

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def websocket(
    self,
    path: Annotated[
        str,
        Doc(
            """
            WebSocket path.
            """
        ),
    ],
    name: Annotated[
        Optional[str],
        Doc(
            """
            A name for the WebSocket. Only used internally.
            """
        ),
    ] = None,
    *,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be used for this
            WebSocket.

            Read more about it in the
            [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).
            """
        ),
    ] = None,
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Decorate a WebSocket function.

    Read more about it in the
    [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).

    **Example**

    ```python
    from fastapi import FastAPI, WebSocket

    app = FastAPI()

    @app.websocket("/ws")
    async def websocket_endpoint(websocket: WebSocket):
        await websocket.accept()
        while True:
            data = await websocket.receive_text()
            await websocket.send_text(f"Message text was: {data}")
    ```
    """

    def decorator(func: DecoratedCallable) -> DecoratedCallable:
        self.add_api_websocket_route(
            path,
            func,
            name=name,
            dependencies=dependencies,
        )
        return func

    return decorator

get

get(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP GET operation.

Example

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/")
def read_items():
    return [{"name": "Empanada"}, {"name": "Arepa"}]

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def get(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP GET operation.

    ## Example

    ```python
    from fastapi import FastAPI

    app = FastAPI()

    @app.get("/items/")
    def read_items():
        return [{"name": "Empanada"}, {"name": "Arepa"}]
    ```
    """
    return self.router.get(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

put

put(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP PUT operation.

Example

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None

app = FastAPI()

@app.put("/items/{item_id}")
def replace_item(item_id: str, item: Item):
    return {"message": "Item replaced", "id": item_id}

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def put(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP PUT operation.

    ## Example

    ```python
    from fastapi import FastAPI
    from pydantic import BaseModel

    class Item(BaseModel):
        name: str
        description: str | None = None

    app = FastAPI()

    @app.put("/items/{item_id}")
    def replace_item(item_id: str, item: Item):
        return {"message": "Item replaced", "id": item_id}
    ```
    """
    return self.router.put(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

post

post(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP POST operation.

Example

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None

app = FastAPI()

@app.post("/items/")
def create_item(item: Item):
    return {"message": "Item created"}

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def post(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP POST operation.

    ## Example

    ```python
    from fastapi import FastAPI
    from pydantic import BaseModel

    class Item(BaseModel):
        name: str
        description: str | None = None

    app = FastAPI()

    @app.post("/items/")
    def create_item(item: Item):
        return {"message": "Item created"}
    ```
    """
    return self.router.post(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

delete

delete(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP DELETE operation.

Example

from fastapi import FastAPI

app = FastAPI()

@app.delete("/items/{item_id}")
def delete_item(item_id: str):
    return {"message": "Item deleted"}

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def delete(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP DELETE operation.

    ## Example

    ```python
    from fastapi import FastAPI

    app = FastAPI()

    @app.delete("/items/{item_id}")
    def delete_item(item_id: str):
        return {"message": "Item deleted"}
    ```
    """
    return self.router.delete(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

options

options(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP OPTIONS operation.

Example

from fastapi import FastAPI

app = FastAPI()

@app.options("/items/")
def get_item_options():
    return {"additions": ["Aji", "Guacamole"]}

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def options(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP OPTIONS operation.

    ## Example

    ```python
    from fastapi import FastAPI

    app = FastAPI()

    @app.options("/items/")
    def get_item_options():
        return {"additions": ["Aji", "Guacamole"]}
    ```
    """
    return self.router.options(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

head

head(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP HEAD operation.

Example

from fastapi import FastAPI, Response

app = FastAPI()

@app.head("/items/", status_code=204)
def get_items_headers(response: Response):
    response.headers["X-Cat-Dog"] = "Alone in the world"

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def head(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP HEAD operation.

    ## Example

    ```python
    from fastapi import FastAPI, Response

    app = FastAPI()

    @app.head("/items/", status_code=204)
    def get_items_headers(response: Response):
        response.headers["X-Cat-Dog"] = "Alone in the world"
    ```
    """
    return self.router.head(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

patch

patch(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP PATCH operation.

Example

from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None

app = FastAPI()

@app.patch("/items/")
def update_item(item: Item):
    return {"message": "Item updated in place"}

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def patch(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP PATCH operation.

    ## Example

    ```python
    from fastapi import FastAPI
    from pydantic import BaseModel

    class Item(BaseModel):
        name: str
        description: str | None = None

    app = FastAPI()

    @app.patch("/items/")
    def update_item(item: Item):
        return {"message": "Item updated in place"}
    ```
    """
    return self.router.patch(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

trace

trace(
    path: Annotated[
        str,
        Doc(
            "\n                The URL path to be used for this *path operation*.\n\n                For example, in `http://example.com/items`, the path is `/items`.\n                "
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            "\n                The type to use for the response.\n\n                It could be any valid Pydantic *field* type. So, it doesn't have to\n                be a Pydantic model, it could be other things, like a `list`, `dict`,\n                etc.\n\n                It will be used for:\n\n                * Documentation: the generated OpenAPI (and the UI at `/docs`) will\n                    show it as the response (JSON Schema).\n                * Serialization: you could return an arbitrary object and the\n                    `response_model` would be used to serialize that object into the\n                    corresponding JSON.\n                * Filtering: the JSON sent to the client will only contain the data\n                    (fields) defined in the `response_model`. If you returned an object\n                    that contains an attribute `password` but the `response_model` does\n                    not include that field, the JSON sent to the client would not have\n                    that `password`.\n                * Validation: whatever you return will be serialized with the\n                    `response_model`, converting any data as necessary to generate the\n                    corresponding JSON. But if the data in the object returned is not\n                    valid, that would mean a violation of the contract with the client,\n                    so it's an error from the API developer. So, FastAPI will raise an\n                    error and return a 500 error code (Internal Server Error).\n\n                Read more about it in the\n                [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).\n                "
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            "\n                The default status code to be used for the response.\n\n                You could override the status code by returning a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).\n                "
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            "\n                A list of tags to be applied to the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).\n                "
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            "\n                A list of dependencies (using `Depends()`) to be applied to the\n                *path operation*.\n\n                Read more about it in the\n                [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).\n                "
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            "\n                A summary for the *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            "\n                A description for the *path operation*.\n\n                If not provided, it will be extracted automatically from the docstring\n                of the *path operation function*.\n\n                It can contain Markdown.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).\n                "
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            "\n                The description for the default response.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            "\n                Additional responses that could be returned by this *path operation*.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            "\n                Mark this *path operation* as deprecated.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n                "
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            "\n                Custom operation ID to be used by this *path operation*.\n\n                By default, it is generated automatically.\n\n                If you provide a custom operation ID, you need to make sure it is\n                unique for the whole API.\n\n                You can customize the\n                operation ID generation with the parameter\n                `generate_unique_id_function` in the `FastAPI` class.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to include only certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            "\n                Configuration passed to Pydantic to exclude certain fields in the\n                response data.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response model\n                should be serialized by alias when an alias is used.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).\n                "
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that were not set and\n                have their default values. This is different from\n                `response_model_exclude_defaults` in that if the fields are set,\n                they will be included in the response, even if the value is the same\n                as the default.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data\n                should have all the fields, including the ones that have the same value\n                as the default. This is different from `response_model_exclude_unset`\n                in that if the fields are set but contain the same default values,\n                they will be excluded from the response.\n\n                When `True`, default values are omitted from the response.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).\n                "
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            "\n                Configuration passed to Pydantic to define if the response data should\n                exclude fields set to `None`.\n\n                This is much simpler (less smart) than `response_model_exclude_unset`\n                and `response_model_exclude_defaults`. You probably want to use one of\n                those two instead of this one, as those allow returning `None` values\n                when it makes sense.\n\n                Read more about it in the\n                [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).\n                "
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            "\n                Include this *path operation* in the generated OpenAPI schema.\n\n                This affects the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).\n                "
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            "\n                Response class to be used for this *path operation*.\n\n                This will not be used if you return a response directly.\n\n                Read more about it in the\n                [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).\n                "
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            "\n                Name for this *path operation*. Only used internally.\n                "
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            "\n                List of *path operations* that will be used as OpenAPI callbacks.\n\n                This is only for OpenAPI documentation, the callbacks won't be used\n                directly.\n\n                It will be added to the generated OpenAPI (e.g. visible at `/docs`).\n\n                Read more about it in the\n                [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).\n                "
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            "\n                Extra metadata to be included in the OpenAPI schema for this *path\n                operation*.\n\n                Read more about it in the\n                [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).\n                "
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[APIRoute], str],
        Doc(
            "\n                Customize the function used to generate unique IDs for the *path\n                operations* shown in the generated OpenAPI.\n\n                This is particularly useful when automatically generating clients or\n                SDKs for your API.\n\n                Read more about it in the\n                [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).\n                "
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]

Add a path operation using an HTTP TRACE operation.

Example

from fastapi import FastAPI

app = FastAPI()

@app.put("/items/{item_id}")
def trace_item(item_id: str):
    return None

Source code in .venv/lib/python3.12/site-packages/fastapi/applications.py

def trace(
    self,
    path: Annotated[
        str,
        Doc(
            """
            The URL path to be used for this *path operation*.

            For example, in `http://example.com/items`, the path is `/items`.
            """
        ),
    ],
    *,
    response_model: Annotated[
        Any,
        Doc(
            """
            The type to use for the response.

            It could be any valid Pydantic *field* type. So, it doesn't have to
            be a Pydantic model, it could be other things, like a `list`, `dict`,
            etc.

            It will be used for:

            * Documentation: the generated OpenAPI (and the UI at `/docs`) will
                show it as the response (JSON Schema).
            * Serialization: you could return an arbitrary object and the
                `response_model` would be used to serialize that object into the
                corresponding JSON.
            * Filtering: the JSON sent to the client will only contain the data
                (fields) defined in the `response_model`. If you returned an object
                that contains an attribute `password` but the `response_model` does
                not include that field, the JSON sent to the client would not have
                that `password`.
            * Validation: whatever you return will be serialized with the
                `response_model`, converting any data as necessary to generate the
                corresponding JSON. But if the data in the object returned is not
                valid, that would mean a violation of the contract with the client,
                so it's an error from the API developer. So, FastAPI will raise an
                error and return a 500 error code (Internal Server Error).

            Read more about it in the
            [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
            """
        ),
    ] = Default(None),
    status_code: Annotated[
        Optional[int],
        Doc(
            """
            The default status code to be used for the response.

            You could override the status code by returning a response directly.

            Read more about it in the
            [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
            """
        ),
    ] = None,
    tags: Annotated[
        Optional[List[Union[str, Enum]]],
        Doc(
            """
            A list of tags to be applied to the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
            """
        ),
    ] = None,
    dependencies: Annotated[
        Optional[Sequence[Depends]],
        Doc(
            """
            A list of dependencies (using `Depends()`) to be applied to the
            *path operation*.

            Read more about it in the
            [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
            """
        ),
    ] = None,
    summary: Annotated[
        Optional[str],
        Doc(
            """
            A summary for the *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    description: Annotated[
        Optional[str],
        Doc(
            """
            A description for the *path operation*.

            If not provided, it will be extracted automatically from the docstring
            of the *path operation function*.

            It can contain Markdown.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
            """
        ),
    ] = None,
    response_description: Annotated[
        str,
        Doc(
            """
            The description for the default response.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = "Successful Response",
    responses: Annotated[
        Optional[Dict[Union[int, str], Dict[str, Any]]],
        Doc(
            """
            Additional responses that could be returned by this *path operation*.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    deprecated: Annotated[
        Optional[bool],
        Doc(
            """
            Mark this *path operation* as deprecated.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).
            """
        ),
    ] = None,
    operation_id: Annotated[
        Optional[str],
        Doc(
            """
            Custom operation ID to be used by this *path operation*.

            By default, it is generated automatically.

            If you provide a custom operation ID, you need to make sure it is
            unique for the whole API.

            You can customize the
            operation ID generation with the parameter
            `generate_unique_id_function` in the `FastAPI` class.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = None,
    response_model_include: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to include only certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_exclude: Annotated[
        Optional[IncEx],
        Doc(
            """
            Configuration passed to Pydantic to exclude certain fields in the
            response data.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = None,
    response_model_by_alias: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response model
            should be serialized by alias when an alias is used.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
            """
        ),
    ] = True,
    response_model_exclude_unset: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that were not set and
            have their default values. This is different from
            `response_model_exclude_defaults` in that if the fields are set,
            they will be included in the response, even if the value is the same
            as the default.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_defaults: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data
            should have all the fields, including the ones that have the same value
            as the default. This is different from `response_model_exclude_unset`
            in that if the fields are set but contain the same default values,
            they will be excluded from the response.

            When `True`, default values are omitted from the response.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
            """
        ),
    ] = False,
    response_model_exclude_none: Annotated[
        bool,
        Doc(
            """
            Configuration passed to Pydantic to define if the response data should
            exclude fields set to `None`.

            This is much simpler (less smart) than `response_model_exclude_unset`
            and `response_model_exclude_defaults`. You probably want to use one of
            those two instead of this one, as those allow returning `None` values
            when it makes sense.

            Read more about it in the
            [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
            """
        ),
    ] = False,
    include_in_schema: Annotated[
        bool,
        Doc(
            """
            Include this *path operation* in the generated OpenAPI schema.

            This affects the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi).
            """
        ),
    ] = True,
    response_class: Annotated[
        Type[Response],
        Doc(
            """
            Response class to be used for this *path operation*.

            This will not be used if you return a response directly.

            Read more about it in the
            [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
            """
        ),
    ] = Default(JSONResponse),
    name: Annotated[
        Optional[str],
        Doc(
            """
            Name for this *path operation*. Only used internally.
            """
        ),
    ] = None,
    callbacks: Annotated[
        Optional[List[BaseRoute]],
        Doc(
            """
            List of *path operations* that will be used as OpenAPI callbacks.

            This is only for OpenAPI documentation, the callbacks won't be used
            directly.

            It will be added to the generated OpenAPI (e.g. visible at `/docs`).

            Read more about it in the
            [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
            """
        ),
    ] = None,
    openapi_extra: Annotated[
        Optional[Dict[str, Any]],
        Doc(
            """
            Extra metadata to be included in the OpenAPI schema for this *path
            operation*.

            Read more about it in the
            [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
            """
        ),
    ] = None,
    generate_unique_id_function: Annotated[
        Callable[[routing.APIRoute], str],
        Doc(
            """
            Customize the function used to generate unique IDs for the *path
            operations* shown in the generated OpenAPI.

            This is particularly useful when automatically generating clients or
            SDKs for your API.

            Read more about it in the
            [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
            """
        ),
    ] = Default(generate_unique_id),
) -> Callable[[DecoratedCallable], DecoratedCallable]:
    """
    Add a *path operation* using an HTTP TRACE operation.

    ## Example

    ```python
    from fastapi import FastAPI

    app = FastAPI()

    @app.put("/items/{item_id}")
    def trace_item(item_id: str):
        return None
    ```
    """
    return self.router.trace(
        path,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        operation_id=operation_id,
        response_model_include=response_model_include,
        response_model_exclude=response_model_exclude,
        response_model_by_alias=response_model_by_alias,
        response_model_exclude_unset=response_model_exclude_unset,
        response_model_exclude_defaults=response_model_exclude_defaults,
        response_model_exclude_none=response_model_exclude_none,
        include_in_schema=include_in_schema,
        response_class=response_class,
        name=name,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=generate_unique_id_function,
    )

include_endpoints

include_endpoints(
    *endpoints: APIEndpoint[Any, Any],
    force_resolution: bool = False,
    **kwargs: Unpack[APIBaseRouterConfigDict],
) -> None

Include configured endpoints within the manager router.

It is used to include within the manager router the configured endpoint. The specified endpoints must be callables with a valid route configuration set within the __config_route__ attribute.

Parameters:

Name	Type	Description	Default
*endpoints	APIEndpoint[Any, Any]	The endpoints to include within the router. It must be an iterable of callables with a valid route configuration (i.e. it must have a __config_route__ attribute).	()
force_resolution	bool	Whether to force the resolution of the endpoint resource type annotated arguments and keyword arguments against the database. Defaults to False.	False
**kwargs	Unpack[APIBaseRouterConfigDict]	The configuration options for the API router.	{}

Raises:

Type	Description
PlateformeError	If the route configuration is missing, invalid, or the mode key is missing.

Note

This method is used internally to include configured endpoints in the manager router. It should not be used directly.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/api/base.py

def include_endpoints(
    self,
    *endpoints: APIEndpoint[Any, Any],
    force_resolution: bool = False,
    **kwargs: Unpack[APIBaseRouterConfigDict],
) -> None:
    """Include configured endpoints within the manager router.

    It is used to include within the manager router the configured
    endpoint. The specified endpoints must be callables with a valid route
    configuration set within the ``__config_route__`` attribute.

    Args:
        *endpoints: The endpoints to include within the router. It must be
            an iterable of callables with a valid route configuration (i.e.
            it must have a ``__config_route__`` attribute).
        force_resolution: Whether to force the resolution of the endpoint
            resource type annotated arguments and keyword arguments against
            the database. Defaults to ``False``.
        **kwargs: The configuration options for the API router.

    Raises:
        PlateformeError: If the route configuration is missing, invalid, or
            the ``mode`` key is missing.

    Note:
        This method is used internally to include configured endpoints in
        the manager router. It should not be used directly.
    """
    self.router.include_endpoints(
        *endpoints,
        force_resolution=force_resolution,
        **kwargs,
    )

include_object

include_object(
    obj: object,
    force_resolution: bool = False,
    **kwargs: Unpack[APIBaseRouterConfigDict],
) -> None

Include a type or an instance object within the router.

It is used to include within the router the configured endpoint members of a type or an instance object. Each callable member of the object implementing a configured route will be included within the router as an API route.

Parameters:

Name	Type	Description	Default
obj	object	The object for which to include the configured endpoints. It can be a type or an instance object.	required
force_resolution	bool	Whether to force the resolution of the endpoint resource type annotated arguments and keyword arguments against the database. Defaults to False.	False
**kwargs	Unpack[APIBaseRouterConfigDict]	The configuration options for the API router.	{}

Raises:

Type	Description
PlateformeError	If the route configuration is missing, invalid, or the mode key is missing.

Note

This method is used internally to include configured endpoints in the router. It should not be used directly.

Source code in .venv/lib/python3.12/site-packages/plateforme/core/api/base.py

def include_object(
    self,
    obj: object,
    force_resolution: bool = False,
    **kwargs: Unpack[APIBaseRouterConfigDict],
) -> None:
    """Include a type or an instance object within the router.

    It is used to include within the router the configured endpoint members
    of a type or an instance object. Each callable member of the object
    implementing a configured route will be included within the router as
    an API route.

    Args:
        obj: The object for which to include the configured endpoints.
            It can be a type or an instance object.
        force_resolution: Whether to force the resolution of the endpoint
            resource type annotated arguments and keyword arguments against
            the database. Defaults to ``False``.
        **kwargs: The configuration options for the API router.

    Raises:
        PlateformeError: If the route configuration is missing, invalid, or
            the ``mode`` key is missing.

    Note:
        This method is used internally to include configured endpoints in
        the router. It should not be used directly.
    """
    self.router.include_object(
        obj,
        force_resolution=force_resolution,
        **kwargs,
    )

include_router

include_router(
    router: APIRouter,
    *,
    prefix: str = "",
    tags: list[str | Enum] | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    default_response_class: type[Response] = Default(
        JSONResponse
    ),
    responses: dict[int | str, dict[str, Any]]
    | None = None,
    callbacks: list[BaseRoute] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    generate_unique_id_function: APIBaseRouteIdentifier = Default(
        generate_unique_id
    ),
) -> None

Include another router within the current router.

It is used to include within the router an existing APIRouter. Each route operation within the included router will be added to the current router.

FIXME: MyPy crashes when using kwargs unpacking with inheritance. FIXME: FastAPI does not implement generate_unique_id_function function within websockets.

Parameters:

Name	Type	Description	Default
router	APIRouter	The APIRouter to include.	required
prefix	str	An optional path prefix for the router. Defaults to an empty string ''.	''
tags	list[str | Enum] | None	A list of tags to be applied to all the path operations in this router. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
dependencies	Sequence[DependsInfo] | None	A collection of dependencies to be applied to all the path operations in this router (using Depends). Defaults to None.	None
default_response_class	type[Response]	The default response class to be used. Defaults to JSONResponse.	Default(JSONResponse)
responses	dict[int | str, dict[str, Any]] | None	Additional responses to be shown in OpenAPI. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
callbacks	list[BaseRoute] | None	OpenAPI callbacks that should apply to all path operations in this router. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
deprecated	bool | None	Mark all path operations in this router as deprecated. It will be added to the generated OpenAPI (e.g. visible at /docs). Defaults to None.	None
include_in_schema	bool	Include (or not) all the path operations in this router in the generated OpenAPI schema. This affects the generated OpenAPI (e.g. visible at /docs). Defaults to True.	True
generate_unique_id_function	APIBaseRouteIdentifier	A function that generates a unique ID for a given route. Defaults to generate_unique_id.	Default(generate_unique_id)

Source code in .venv/lib/python3.12/site-packages/plateforme/core/api/base.py

def include_router(  # type: ignore[override, unused-ignore]
    self,
    router: 'APIRouter',
    *,
    prefix: str = '',
    tags: list[str | Enum] | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    default_response_class: type[Response] = Default(JSONResponse),
    responses: dict[int | str, dict[str, Any]] | None = None,
    callbacks: list[BaseRoute] | None = None,
    deprecated: bool | None = None,
    include_in_schema: bool = True,
    generate_unique_id_function: APIBaseRouteIdentifier = \
        Default(generate_unique_id),
) -> None:
    """Include another router within the current router.

    It is used to include within the router an existing `APIRouter`. Each
    route operation within the included router will be added to the current
    router.

    FIXME: MyPy crashes when using kwargs unpacking with inheritance.
    FIXME: FastAPI does not implement `generate_unique_id_function`
    function within websockets.

    Args:
        router: The `APIRouter` to include.
        prefix: An optional path prefix for the router. Defaults to an
            empty string ``''``.
        tags: A list of tags to be applied to all the path operations in
            this router. It will be added to the generated OpenAPI (e.g.
            visible at ``/docs``). Defaults to ``None``.
        dependencies: A collection of dependencies to be applied to all the
            path operations in this router (using `Depends`).
            Defaults to ``None``.
        default_response_class: The default response class to be used.
            Defaults to `JSONResponse`.
        responses: Additional responses to be shown in OpenAPI. It will be
            added to the generated OpenAPI (e.g. visible at ``/docs``).
            Defaults to ``None``.
        callbacks: OpenAPI callbacks that should apply to all path
            operations in this router. It will be added to the generated
            OpenAPI (e.g. visible at ``/docs``). Defaults to ``None``.
        deprecated: Mark all path operations in this router as deprecated.
            It will be added to the generated OpenAPI (e.g. visible at
            ``/docs``). Defaults to ``None``.
        include_in_schema: Include (or not) all the path operations in this
            router in the generated OpenAPI schema. This affects the
            generated OpenAPI (e.g. visible at ``/docs``).
            Defaults to ``True``.
        generate_unique_id_function: A function that generates a unique ID
            for a given route. Defaults to ``generate_unique_id``.
    """
    # Include endpoints within the router
    super().include_router(
        router,
        prefix=prefix,
        tags=tags,
        dependencies=dependencies,
        default_response_class=default_response_class,
        responses=responses,
        callbacks=callbacks,
        deprecated=deprecated,
        include_in_schema=include_in_schema,
        generate_unique_id_function=
            generate_unique_id_function,  # type: ignore[arg-type]
    )