Routing

plateforme.core.api.routing

This module provides routing mechanisms for the Plateforme API, extending FastAPI and Starlette features. It includes the standard route decorators for the API route configurations, and a router to organize and manage API endpoints.

APIMethod module-attribute

APIMethod = Literal[
    "DELETE",
    "GET",
    "HEAD",
    "OPTIONS",
    "PATCH",
    "POST",
    "PUT",
    "TRACE",
]

A literal type for the API HTTP methods.

APIMode module-attribute

APIMode = Literal['request', 'websocket']

A literal type for the API modes.

route module-attribute

route = APIRouteDecorator()

The standard decorator for routing operations.

APIBaseRoute

Bases: Protocol

An API base route protocol.

path instance-attribute

path: str

The path for the operation. If not provided, it is automatically generated from the endpoint name.

path_regex instance-attribute

path_regex: Pattern[str]

The path regex for the operation with format /(?P<username>[^/]+)

path_format instance-attribute

path_format: str

The path format for the operation with format /{username}

param_convertors instance-attribute

param_convertors: dict[str, Convertor[Any]]

The path parameter convertors for the operation with format {"username": StringConvertor()}

endpoint instance-attribute

endpoint: Callable[..., Any]

The method endpoint for the path operation.

dependencies instance-attribute

dependencies: list[DependsInfo]

A list of dependencies to be applied to the path operation (using Depends function). Defaults to None.

name instance-attribute

name: str

The name of the path operation. It is used internally to identify the path operation.

operation_id instance-attribute

operation_id: str | None

The operation ID to be used for the 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. Defaults to None.

generate_unique_id_function instance-attribute

generate_unique_id_function: Union[
    APIBaseRouteIdentifier,
    DefaultPlaceholder[APIBaseRouteIdentifier],
]

A function that generates a unique ID for a given route. Defaults to generate_unique_id.

unique_id instance-attribute

unique_id: str

The unique ID for the path operation inferred from the operation ID or the given generate_unique_id_function function.

APIEndpoint

Bases: Protocol, Generic[_P, _R]

An API endpoint protocol.

APIRoute

APIRoute(
    path: str,
    endpoint: Callable[..., Any],
    *,
    response_model: Any = Default(None),
    status_code: int | None = None,
    tags: list[str | Enum] | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = "Successful Response",
    responses: dict[int | str, dict[str, Any]]
    | None = None,
    deprecated: bool | None = None,
    name: str | None = None,
    methods: list[APIMethod] | set[APIMethod] | None = None,
    operation_id: str | None = None,
    response_model_include: IncEx | None = None,
    response_model_exclude: IncEx | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    response_model_serialization: bool = True,
    include_in_schema: bool = True,
    response_class: Union[
        type[Response], DefaultPlaceholder[type[Response]]
    ] = Default(JSONResponse),
    dependency_overrides_provider: Any | None = None,
    callbacks: list[BaseRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
    generate_unique_id_function: Union[
        APIBaseRouteIdentifier,
        DefaultPlaceholder[APIBaseRouteIdentifier],
    ] = Default(generate_unique_id),
)

Bases: APIRoute

An API route.

Initialize an API route.

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

def __init__(
    self,
    path: str,
    endpoint: Callable[..., Any],
    *,
    response_model: Any = Default(None),
    status_code: int | None = None,
    tags: list[str | Enum] | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    summary: str | None = None,
    description: str | None = None,
    response_description: str = 'Successful Response',
    responses: dict[int | str, dict[str, Any]] | None = None,
    deprecated: bool | None = None,
    name: str | None = None,
    methods: list[APIMethod] | set[APIMethod] | None = None,
    operation_id: str | None = None,
    response_model_include: IncEx | None = None,
    response_model_exclude: IncEx | None = None,
    response_model_by_alias: bool = True,
    response_model_exclude_unset: bool = False,
    response_model_exclude_defaults: bool = False,
    response_model_exclude_none: bool = False,
    response_model_serialization: bool = True,
    include_in_schema: bool = True,
    response_class: Union[
        type[Response], DefaultPlaceholder[type[Response]]
    ] = Default(JSONResponse),
    dependency_overrides_provider: Any | None = None,
    callbacks: list[BaseRoute] | None = None,
    openapi_extra: dict[str, Any] | None = None,
    generate_unique_id_function: Union[
        APIBaseRouteIdentifier, DefaultPlaceholder[APIBaseRouteIdentifier]
    ] = Default(generate_unique_id),
) -> None:
    """Initialize an API route."""
    # Wrap endpoint return value in a response model if no serialization
    # is required. This prevents FastAPI from serializing the response
    # model and allows the response model to be used for OpenAPI
    # documentation only.
    if response_model_serialization:
        wrapped_endpoint = endpoint
    else:
        wrapped_endpoint = _wrap_endpoint_with_response(
            endpoint,
            status_code=status_code,
            response_class=response_class,
        )

    # Initialize the API route
    super().__init__(
        path,
        wrapped_endpoint,
        response_model=response_model,
        status_code=status_code,
        tags=tags,
        dependencies=dependencies,
        summary=summary,
        description=description,
        response_description=response_description,
        responses=responses,
        deprecated=deprecated,
        name=name,
        methods={*methods} if methods else None,
        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,
        dependency_overrides_provider=dependency_overrides_provider,
        callbacks=callbacks,
        openapi_extra=openapi_extra,
        generate_unique_id_function=
            generate_unique_id_function,  # type: ignore[arg-type]
    )

    # Update route configuration
    self.name = get_object_name(endpoint, handler=to_name_case) \
        if name is None else name
    self.response_model_serialization = response_model_serialization

APIRouteConfig

APIRouteConfig(
    *args: Any, **kwargs: Unpack[APIRouteConfigDict]
)

Bases: ConfigWrapper

An API route configuration.

Initialize the API route configuration.

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

def __init__(
    self, *args: Any, **kwargs: Unpack[APIRouteConfigDict]
) -> None:
    """Initialize the API route configuration."""
    super().__init__(*args, **kwargs)

alias property

alias: str

The alias for the route configuration.

slug property

slug: str

The slug for the route configuration.

create classmethod

create(
    owner: Any | None = None,
    defaults: dict[str, Any] | None = None,
    partial_init: bool = False,
    *,
    data: dict[str, Any] | None = None,
) -> Self

Create a new configuration instance.

This method is typically used internally to create a new configuration class with a specific owner and partial initialization flag. It is an alternative to the __init__ method for creating a new configuration instance.

Parameters:

Name	Type	Description	Default
owner	Any | None	The owner of the configuration instance.	None
defaults	dict[str, Any] | None	The default values to initialize the configuration instance with. Defaults to None.	None
partial_init	bool	Flag indicating whether to partially initialize the configuration instance. Defaults to False.	False
data	dict[str, Any] | None	The data to initialize the configuration instance with. Defaults to None.	None

Returns:

Type	Description
Self	The new configuration instance created.

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

@classmethod
def create(
    cls,
    owner: Any | None = None,
    defaults: dict[str, Any] | None = None,
    partial_init: bool = False,
    *,
    data: dict[str, Any] | None = None,
) -> Self:
    """Create a new configuration instance.

    This method is typically used internally to create a new configuration
    class with a specific owner and partial initialization flag. It is an
    alternative to the `__init__` method for creating a new configuration
    instance.

    Args:
        owner: The owner of the configuration instance.
        defaults: The default values to initialize the configuration
            instance with. Defaults to ``None``.
        partial_init: Flag indicating whether to partially initialize the
            configuration instance. Defaults to ``False``.
        data: The data to initialize the configuration instance with.
            Defaults to ``None``.

    Returns:
        The new configuration instance created.
    """
    return cls(owner, defaults, partial_init, **(data or {}))

from_meta classmethod

from_meta(
    owner: type[Any],
    bases: tuple[type, ...],
    namespace: dict[str, Any],
    /,
    config_attr: str = "__config__",
    partial_init: bool = False,
    data: dict[str, Any] | None = None,
) -> Self

Create a new configuration instance from a class constructor.

This method is typically used internally to create a new configuration class from the meta configuration of a model, package, resource, or service. It merges the configuration of the given bases, the namespace, and the keyword arguments to create a new configuration class.

Parameters:

Name	Type	Description	Default
owner	type[Any]	The owner of the configuration instance. It should be the class that is being created from the meta configuration.	required
bases	tuple[type, ...]	The configurable base classes to merge.	required
namespace	dict[str, Any]	The configurable namespace to merge.	required
config_attr	str	The configurable attribute name used to extract the configuration dictionary from the bases and the namespace of the configurable class. Defaults to '__config__'.	'__config__'
partial_init	bool	Flag indicating whether to partially initialize the configuration instance. Defaults to False.	False
data	dict[str, Any] | None	The data to initialize the configuration instance with. Defaults to None.	None

Returns:

Type	Description
Self	The new configuration instance created from the given meta
Self	configuration.

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

@classmethod
def from_meta(
    cls,
    owner: type[Any],
    bases: tuple[type, ...],
    namespace: dict[str, Any],
    /,
    config_attr: str = '__config__',
    partial_init: bool = False,
    data: dict[str, Any] | None = None,
) -> Self:
    """Create a new configuration instance from a class constructor.

    This method is typically used internally to create a new configuration
    class from the meta configuration of a model, package, resource, or
    service. It merges the configuration of the given bases, the namespace,
    and the keyword arguments to create a new configuration class.

    Args:
        owner: The owner of the configuration instance. It should be the
            class that is being created from the meta configuration.
        bases: The configurable base classes to merge.
        namespace: The configurable namespace to merge.
        config_attr: The configurable attribute name used to extract the
            configuration dictionary from the bases and the namespace of
            the configurable class. Defaults to ``'__config__'``.
        partial_init: Flag indicating whether to partially initialize the
            configuration instance. Defaults to ``False``.
        data: The data to initialize the configuration instance with.
            Defaults to ``None``.

    Returns:
        The new configuration instance created from the given meta
        configuration.
    """
    with cls.context(allow_mutation=True):
        # Build configuration instance
        config = cls(owner, {}, True)

        for base in bases:
            base_config = getattr(base, config_attr, {})
            if callable(base_config):
                base_config = base_config()
            config.merge(base_config)

        namespace_config = namespace.get(config_attr, {})
        if callable(namespace_config):
            namespace_config = namespace_config()
        config.merge(namespace_config)

        config.merge(data or {})

        # Validate configuration instance
        if not partial_init:
            config.validate()

    return config

validate

validate(
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> None

Validate the configuration instance.

It post-initializes the configuration instance, checks for any missing required fields and validates the assignments of the configuration values based on the configuration fields information and the current validation context. This is performed automatically upon initialization of the configuration instance.

Parameters:

Name	Type	Description	Default
strict	bool | None	Whether to enforce strict validation. Defaults to None.	None
context	dict[str, Any] | None	The context to use for validation. Defaults to None.	None

Raises:

Type	Description
ValueError	If the configuration instance has undefined values for required fields.
ValidationError	If the assignment of a value is invalid based on the configuration fields information and the current validation context.

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

def validate(
    self,
    *,
    strict: bool | None = None,
    context: dict[str, Any] | None = None,
) -> None:
    """Validate the configuration instance.

    It post-initializes the configuration instance, checks for any missing
    required fields and validates the assignments of the configuration
    values based on the configuration fields information and the current
    validation context. This is performed automatically upon initialization
    of the configuration instance.

    Args:
        strict: Whether to enforce strict validation. Defaults to ``None``.
        context: The context to use for validation. Defaults to ``None``.

    Raises:
        ValueError: If the configuration instance has undefined values for
            required fields.
        ValidationError: If the assignment of a value is invalid based on
            the configuration fields information and the current validation
            context.
    """
    # Perform post-initialization
    self.post_init()

    # Validate for missing required fields
    config_missing = [
        key for key, field in self.__config_fields__.items()
        if field.is_required() and self[key] is Undefined
    ]
    if config_missing:
        raise ValueError(
            f"Undefined values for configuration "
            f"{self.__class__.__qualname__!r} required fields: "
            f"{', '.join(config_missing)}."
        )

    # Validate assignments
    for key, value in self.entries(scope='set').items():
        if not strict and value is Deferred:
            continue
        if key in self.__config_validators__:
            validator = self.__config_validators__[key].validate_python
            value = validator(value, strict=strict, context=context)
        self.__dict__[key] = value

context staticmethod

context(
    *, allow_mutation: bool | None = None
) -> Iterator[bool]

Context manager for the configuration instance.

If the frozen mutation flag is not specified, the current frozen mutation flag is used if available, otherwise it defaults to False.

Parameters:

Name	Type	Description	Default
allow_mutation	bool | None	Flag indicating whether to allow frozen mutation of the configuration instance. When set to False, it prevents any changes by setting the frozen flag to True. If not specified, the current frozen mutation flag is used if available, otherwise it resolves to False. Defaults to None.	None

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

@staticmethod
@contextmanager
def context(
    *, allow_mutation: bool | None = None,
) -> Iterator[bool]:
    """Context manager for the configuration instance.

    If the frozen mutation flag is not specified, the current frozen
    mutation flag is used if available, otherwise it defaults to ``False``.

    Args:
        allow_mutation: Flag indicating whether to allow frozen mutation
            of the configuration instance. When set to ``False``, it
            prevents any changes by setting the frozen flag to ``True``.
            If not specified, the current frozen mutation flag is used if
            available, otherwise it resolves to ``False``.
            Defaults to ``None``.
    """
    context = FROZEN_CONTEXT.get()

    # Set frozen mutation flag
    if allow_mutation is None:
        if context is not None:
            frozen = context
        frozen = True
    else:
        frozen = not allow_mutation

    # Yield and reset frozen mutation flag
    token = FROZEN_CONTEXT.set(frozen)
    try:
        yield frozen
    finally:
        FROZEN_CONTEXT.reset(token)

clear

clear() -> None

Clear the configuration dictionary and reset all values.

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

def clear(self) -> None:
    """Clear the configuration dictionary and reset all values."""
    for key in self.__config_fields__:
        self.__dict__.pop(key, None)

copy

copy() -> Self

Return a shallow copy of the configuration dictionary.

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

def copy(self) -> Self:
    """Return a shallow copy of the configuration dictionary."""
    return self.__class__(
        self.__config_owner__,
        self.__config_defaults__.copy(),
        False,
        **self.entries(scope='set')
    )

merge

merge(
    *configs: Self | dict[str, Any],
    setdefault: bool = False,
) -> None

Merge the configuration with other configurations.

It merges the configuration with the provided configuration instances or dictionaries. The precedence of the rightmost configuration is higher than the leftmost configuration. This can be changed by setting the setdefault argument to True.

Parameters:

Name	Type	Description	Default
*configs	Self | dict[str, Any]	The configuration instances or dictionaries to merge with the target configuration dictionary.	()
setdefault	bool	Flag indicating whether to set the default values for the configuration keys if they are not already set. This modifies the behavior of the merge operation, making the precedence of the leftmost configuration higher than the rightmost configuration. Defaults to False (rightmost precedence).	False

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

def merge(
    self,
    *configs: Self | dict[str, Any],
    setdefault: bool = False,
) -> None:
    """Merge the configuration with other configurations.

    It merges the configuration with the provided configuration instances
    or dictionaries. The precedence of the rightmost configuration is
    higher than the leftmost configuration. This can be changed by setting
    the `setdefault` argument to ``True``.

    Args:
        *configs: The configuration instances or dictionaries to merge with
            the target configuration dictionary.
        setdefault: Flag indicating whether to set the default values for
            the configuration keys if they are not already set.
            This modifies the behavior of the merge operation, making the
            precedence of the leftmost configuration higher than the
            rightmost configuration.
            Defaults to ``False`` (rightmost precedence).
    """
    for config in configs:
        # Retrieve the configuration dictionary
        if isinstance(config, self.__class__):
            config_dict = {
                key: value
                for key, value in config.__dict__.items()
                if key in config.__config_fields__
            }
        elif isinstance(config, dict):
            config_dict = config.copy()
        else:
            raise TypeError(
                f"Invalid configuration type {type(config).__name__!r} "
                f"for {self.__class__.__qualname__!r}, it must be a "
                f"dictionary or a configuration instance."
            )
        # Merge with the target configuration dictionary
        if setdefault:
            for key, value in config_dict.items():
                self.setdefault(key, value)
        else:
            self.update(config_dict)

check

check(
    key: str,
    *,
    scope: Literal["all", "default", "set"] = "all",
    raise_errors: bool = True,
) -> bool

Check if the configuration key exists in the given scope.

Parameters:

Name	Type	Description	Default
key	str	The configuration key to check for.	required
scope	Literal['all', 'default', 'set']	The scope to check for the configuration key. It can be either 'all' to check in all configuration entries, 'default' to check in configuration entries with default values not undefined, or 'set' to check in only the configuration entries that have been explicitly set. Defaults to 'all'.	'all'
raise_errors	bool	Flag indicating whether to raise an error if the configuration key is not defined for the configuration wrapper. Defaults to True.	True

Returns:

Type	Description
bool	A boolean indicating whether the configuration key exists in the
bool	specified scope.

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

def check(
    self,
    key: str,
    *,
    scope: Literal['all', 'default', 'set'] = 'all',
    raise_errors: bool = True,
) -> bool:
    """Check if the configuration key exists in the given scope.

    Args:
        key: The configuration key to check for.
        scope: The scope to check for the configuration key. It can be
            either ``'all'`` to check in all configuration entries,
            ``'default'`` to check in configuration entries with default
            values not undefined, or ``'set'`` to check in only the
            configuration entries that have been explicitly set.
            Defaults to ``'all'``.
        raise_errors: Flag indicating whether to raise an error if the
            configuration key is not defined for the configuration wrapper.
            Defaults to ``True``.

    Returns:
        A boolean indicating whether the configuration key exists in the
        specified scope.
    """
    if key not in self.__config_fields__:
        if not raise_errors:
            return False
        raise KeyError(
            f"Configuration key {key!r} cannot be checked as it is not "
            f"defined for wrapper {self.__class__.__qualname__!r}."
        )
    if scope == 'default':
        return key not in self.__dict__
    if scope == 'set':
        return key in self.__dict__
    return True

entries

entries(
    *,
    scope: Literal["all", "default", "set"] = "all",
    default_mode: Literal[
        "preserve", "unwrap", "wrap"
    ] = "unwrap",
    include_keys: Iterable[str] | None = None,
    exclude_keys: Iterable[str] | None = None,
    include_metadata: Iterable[Any] | None = None,
    exclude_metadata: Iterable[Any] | None = None,
) -> dict[str, Any]

Return the configuration dictionary.

It returns the configuration dictionary based on the specified scope, and keys and extra information to filter the configuration dictionary entries.

Parameters:

Name	Type	Description	Default
scope	Literal['all', 'default', 'set']	The scope of the configuration dictionary to return. It can be either 'all' to return all configuration entries, 'default' to return all configuration entries with their default values, or 'set' to return only the configuration entries that have been explicitly set. Defaults to 'all'.	'all'
default_mode	Literal['preserve', 'unwrap', 'wrap']	The default mode to use when returning a default entry from the configuration dictionary. It can be either 'preserve' to keep the default value as is, 'unwrap' to unwrap the default value, or 'wrap' to wrap the default value with a default placeholder. Defaults to 'unwrap'.	'unwrap'
include_keys	Iterable[str] | None	The keys to include from the configuration dictionary entries. Defaults to None.	None
exclude_keys	Iterable[str] | None	The keys to exclude from the configuration dictionary entries. Defaults to None.	None
include_metadata	Iterable[Any] | None	The metadata information to include from the configuration dictionary entries. Defaults to None.	None
exclude_metadata	Iterable[Any] | None	The metadata information to exclude from the configuration dictionary entries. Defaults to None.	None

Returns:

Type	Description
dict[str, Any]	A dictionary containing the configuration entries based on the
dict[str, Any]	specified scope and extra information.

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

def entries(
    self,
    *,
    scope: Literal['all', 'default', 'set'] = 'all',
    default_mode: Literal['preserve', 'unwrap', 'wrap'] = 'unwrap',
    include_keys: Iterable[str] | None = None,
    exclude_keys: Iterable[str] | None = None,
    include_metadata: Iterable[Any] | None = None,
    exclude_metadata: Iterable[Any] | None = None,
) -> dict[str, Any]:
    """Return the configuration dictionary.

    It returns the configuration dictionary based on the specified scope,
    and keys and extra information to filter the configuration dictionary
    entries.

    Args:
        scope: The scope of the configuration dictionary to return. It can
            be either ``'all'`` to return all configuration entries,
            ``'default'`` to return all configuration entries with their
            default values, or ``'set'`` to return only the configuration
            entries that have been explicitly set. Defaults to ``'all'``.
        default_mode: The default mode to use when returning a default
            entry from the configuration dictionary. It can be either
            ``'preserve'`` to keep the default value as is, ``'unwrap'`` to
            unwrap the default value, or ``'wrap'`` to wrap the default
            value with a default placeholder. Defaults to ``'unwrap'``.
        include_keys: The keys to include from the configuration dictionary
            entries. Defaults to ``None``.
        exclude_keys: The keys to exclude from the configuration dictionary
            entries. Defaults to ``None``.
        include_metadata: The metadata information to include from the
            configuration dictionary entries. Defaults to ``None``.
        exclude_metadata: The metadata information to exclude from the
            configuration dictionary entries. Defaults to ``None``.

    Returns:
        A dictionary containing the configuration entries based on the
        specified scope and extra information.
    """
    # Retrieve the configuration dictionary based on the specified scope
    config_dict: dict[str, Any] = {}
    if scope == 'default':
        for key in self.__config_fields__:
            if key in self.__dict__:
                continue
            config_dict[key] = self.get(key, default_mode=default_mode)
    elif scope == 'set':
        for key in self.__config_fields__:
            if key not in self.__dict__:
                continue
            config_dict[key] = self.get(key, default_mode=default_mode)
    else:
        for key in self.__config_fields__:
            config_dict[key] = self.get(key, default_mode=default_mode)

    # Build the keys and metadata sets to include and exclude from the
    # configuration dictionary entries.
    incex_keys = [include_keys, exclude_keys]
    for count, value in enumerate(incex_keys):
        if value is not None:
            if isinstance(value, type) and \
                    issubclass(value, ConfigWrapper):
                value = value.__config_fields__.keys()
            incex_keys[count] = set(value)

    incex_metadata = [include_metadata, exclude_metadata]
    for count, value in enumerate(incex_metadata):
        if value is not None:
            incex_metadata[count] = set(value)

    # Return directly if no keys or metadata filtering is provided.
    if not any(incex_keys) and not any(incex_metadata):
        return config_dict

    # Filter the configuration dictionary based on the information and keys
    # if provided in the "with" arguments.
    for key in list(config_dict.keys()):
        if incex_keys[0] is not None and key not in incex_keys[0]:
            config_dict.pop(key)
        elif incex_keys[1] is not None and key in incex_keys[1]:
            config_dict.pop(key)
        elif incex_metadata[0] is not None and not all(
            metadata in self.__config_fields__[key].metadata
            for metadata in incex_metadata[0]
        ):
            config_dict.pop(key)
        elif incex_metadata[1] is not None and any(
            metadata in self.__config_fields__[key].metadata
            for metadata in incex_metadata[1]
        ):
            config_dict.pop(key)

    return config_dict

keys

keys() -> KeysView[str]

Return the configuration keys.

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

def keys(self) -> KeysView[str]:
    """Return the configuration keys."""
    return KeysView(self.entries())

values

values() -> ValuesView[Any]

Return the configuration values.

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

def values(self) -> ValuesView[Any]:
    """Return the configuration values."""
    return ValuesView(self.entries())

items

items() -> ItemsView[str, Any]

Return the configuration items.

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

def items(self) -> ItemsView[str, Any]:
    """Return the configuration items."""
    return ItemsView(self.entries())

get

get(key: str) -> Any

get(key: str, default: Any) -> Any

get(
    key: str,
    default: Any = Undefined,
    *,
    default_mode: Literal[
        "preserve", "unwrap", "wrap"
    ] = "unwrap",
) -> Any

get(
    key: str,
    default: Any = Undefined,
    *,
    default_mode: Literal[
        "preserve", "unwrap", "wrap"
    ] = "unwrap",
) -> Any

Get the value for the specified key if set otherwise the default.

Parameters:

Name	Type	Description	Default
key	str	The configuration key to get the value for.	required
default	Any	The default value to return if the key is not set.	Undefined
default_mode	Literal['preserve', 'unwrap', 'wrap']	The default mode to use when returning a default value from the configuration dictionary. It can be either 'preserve' to keep the default value as is, 'unwrap' to unwrap the default value, or 'wrap' to wrap the default value with a placeholder. Defaults to 'unwrap'.	'unwrap'

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

def get(
    self, key: str,
    default: Any = Undefined,
    *,
    default_mode: Literal['preserve', 'unwrap', 'wrap'] = 'unwrap',
) -> Any:
    """Get the value for the specified key if set otherwise the default.

    Args:
        key: The configuration key to get the value for.
        default: The default value to return if the key is not set.
        default_mode: The default mode to use when returning a default
            value from the configuration dictionary. It can be either
            ``'preserve'`` to keep the default value as is, ``'unwrap'`` to
            unwrap the default value, or ``'wrap'`` to wrap the default
            value with a placeholder. Defaults to ``'unwrap'``.
    """
    if key not in self.__config_fields__:
        raise KeyError(
            f"Configuration key {key!r} cannot be retrieved as it is not "
            f"defined for wrapper {self.__class__.__qualname__!r}."
        )
    if key in self.__dict__:
        return self.__dict__[key]
    if default is Undefined:
        return self.getdefault(key, mode=default_mode)
    if default_mode == 'wrap':
        return Default(default)
    if default_mode == 'unwrap':
        return get_value_or_default(default)
    return default

pop

pop(key: str) -> Any

pop(key: str, default: Any) -> Any

pop(
    key: str,
    default: Any = Undefined,
    *,
    default_mode: Literal[
        "preserve", "unwrap", "wrap"
    ] = "unwrap",
) -> Any

pop(
    key: str,
    default: Any = Undefined,
    *,
    default_mode: Literal[
        "preserve", "unwrap", "wrap"
    ] = "unwrap",
) -> Any

Pop the specified key if set and return its corresponding value.

Parameters:

Name	Type	Description	Default
key	str	The configuration key to pop the value for.	required
default	Any	The default value to return if the key is not set.	Undefined
default_mode	Literal['preserve', 'unwrap', 'wrap']	The default mode to use when returning a default value from the configuration dictionary. It can be either 'preserve' to keep the default value as is, 'unwrap' to unwrap the default value, or 'wrap' to wrap the default value with a placeholder. Defaults to 'unwrap'.	'unwrap'

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

def pop(
    self,
    key: str,
    default: Any = Undefined,
    *,
    default_mode: Literal['preserve', 'unwrap', 'wrap'] = 'unwrap',
) -> Any:
    """Pop the specified key if set and return its corresponding value.

    Args:
        key: The configuration key to pop the value for.
        default: The default value to return if the key is not set.
        default_mode: The default mode to use when returning a default
            value from the configuration dictionary. It can be either
            ``'preserve'`` to keep the default value as is, ``'unwrap'`` to
            unwrap the default value, or ``'wrap'`` to wrap the default
            value with a placeholder. Defaults to ``'unwrap'``.
    """
    if key not in self.__config_fields__:
        raise KeyError(
            f"Configuration key {key!r} cannot be popped as it is not "
            f"defined for wrapper {self.__class__.__qualname__!r}."
        )
    if key in self.__dict__:
        return self.__dict__.pop(key)
    if default is Undefined:
        return self.getdefault(key, mode=default_mode)
    if default_mode == 'wrap':
        return Default(default)
    if default_mode == 'unwrap':
        return get_value_or_default(default)
    return default

getdefault

getdefault(
    key: str,
    *,
    mode: Literal["preserve", "unwrap", "wrap"] = "unwrap",
) -> Any

Get the default value for the specified key.

Parameters:

Name	Type	Description	Default
key	str	The configuration key to get the default value for.	required
mode	Literal['preserve', 'unwrap', 'wrap']	The mode to use when returning the default value. It can be either 'preserve' to keep the default value as is, 'unwrap' to unwrap the default value, or 'wrap' to wrap the default value with a placeholder. Defaults to 'unwrap'.	'unwrap'

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

def getdefault(
    self,
    key: str,
    *,
    mode: Literal['preserve', 'unwrap', 'wrap'] = 'unwrap',
) -> Any:
    """Get the default value for the specified key.

    Args:
        key: The configuration key to get the default value for.
        mode: The mode to use when returning the default value. It can be
            either ``'preserve'`` to keep the default value as is,
            ``'unwrap'`` to unwrap the default value, or ``'wrap'`` to wrap
            the default value with a placeholder. Defaults to ``'unwrap'``.
    """
    if key not in self.__config_fields__:
        raise KeyError(
            f"Default for configuration key {key!r} cannot be retrieved "
            f"as it is not defined for wrapper "
            f"{self.__class__.__qualname__!r}."
        )
    elif key in self.__config_defaults__:
        default = self.__config_defaults__[key]
    else:
        default = self.__config_fields__[key].get_default()

    if mode == 'wrap':
        return Default(default)
    if mode == 'unwrap':
        return get_value_or_default(default)
    return default

setdefault

setdefault(key: str, default: Any) -> Any

Set the default value for the specified key.

Parameters:

Name	Type	Description	Default
key	str	The configuration key to set the default value for.	required
default	Any	The default value to set for the key.	required

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

def setdefault(self, key: str, default: Any) -> Any:
    """Set the default value for the specified key.

    Args:
        key: The configuration key to set the default value for.
        default: The default value to set for the key.
    """
    if key not in self.__config_fields__:
        raise KeyError(
            f"Default for configuration key {key!r} cannot be set as it "
            f"is not defined for wrapper {self.__class__.__qualname__!r}."
        )
    self.__config_defaults__[key] = default
    return default

update

update(
    *args: tuple[str, Any] | Mapping[str, Any],
    **kwargs: Any,
) -> None

Update the config dictionary with new data.

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

def update(
    self,
    *args: tuple[str, Any] | Mapping[str, Any],
    **kwargs: Any,
) -> None:
    """Update the config dictionary with new data."""
    # Helper function to update configuration entries
    def update_entry(key: str, value: Any) -> None:
        if key not in self.__config_fields__:
            raise KeyError(
                f"Configuration key {key!r} cannot be updated as it is "
                f"not defined for wrapper {self.__class__.__qualname__!r}."
            )
        setattr(self, key, value)

    # Update args data
    for arg in args:
        if isinstance(arg, tuple):
            if len(arg) != 2:
                raise ValueError(
                    f"Configuration update arguments must be provided as "
                    f"key-value pairs. Got: {arg}."
                )
            update_entry(arg[0], arg[1])
        else:
            for key, value in arg.items():
                update_entry(key, value)
    # Update kwargs data
    for key, value in kwargs.items():
        update_entry(key, value)

post_init

post_init() -> None

Post-initialization steps for the API route configuration.

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

def post_init(self) -> None:
    """Post-initialization steps for the API route configuration."""

    # Check if the route mode is valid
    if self.mode not in ('request', 'websocket'):
        raise ValueError(
            f"Invalid route mode {self.mode!r} provided for the route "
            f"configuration. It must be either `request` or `websocket`."
        )

    # Clean up route configuration
    if self.mode == 'request':
        # Pop invalid keys in the request route configuration
        request_keys = (
            APIBaseRouteConfigDict.__annotations__.keys()
            | APIRequestRouteConfigDict.__annotations__.keys()
        )
        for key in self.entries(scope='set'):
            if key not in request_keys:
                self.pop(key)
    else:
        # Pop invalid keys in the websocket route configuration
        websocket_keys = (
            APIBaseRouteConfigDict.__annotations__.keys()
            | APIWebSocketRouteConfigDict.__annotations__.keys()
        )
        for key in self.entries(scope='set'):
            if key not in websocket_keys or key == 'methods':
                self.pop(key)

    # Validate route name
    if self.name and not re.match(RegexPattern.ALIAS, self.name):
        raise PlateformeError(
            f"Invalid route name {self.name!r} provided for the route "
            f"configuration. It must match a specific pattern `ALIAS` "
            f"defined in the framework's regular expressions repository.",
            code='route-invalid-config',
        )

    # Validate route path
    if self.path and not re.match(RegexPattern.PATH, self.path):
        raise PlateformeError(
            f"Invalid route path {self.path!r} provided for the route "
            f"configuration. It must match a specific pattern `PATH` "
            f"defined in the framework's regular expressions repository.",
            code='route-invalid-config',
        )

APIRouteDecorator

APIRouteDecorator(**kwargs: Unpack[APIRouteConfigDict])

A base class for endpoint API route decorators.

Initialize an endpoint API route decorator with default values.

Parameters:

Name	Type	Description	Default
**kwargs	Unpack[APIRouteConfigDict]	The default values to be used for the route configuration. If undefined, the API router defaults will be used instead.	{}

Note

See also the APIRouteConfigDict dictionary for the available configuration options used for the route creation within the API.

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

def __init__(
    self, /, **kwargs: Unpack[APIRouteConfigDict]
) -> None:
    """Initialize an endpoint API route decorator with default values.

    Args:
        **kwargs: The default values to be used for the route
            configuration. If undefined, the API router defaults will be
            used instead.

    Note:
        See also the `APIRouteConfigDict` dictionary for the available
        configuration options used for the route creation within the API.
    """
    self.defaults = APIRouteConfig(**kwargs)

delete

delete(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-DELETE path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-DELETE path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def delete(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-DELETE`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-DELETE`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['DELETE'],
        **kwargs,
    )

get

get(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-GET path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-GET path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def get(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-GET`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-GET`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['GET'],
        **kwargs,
    )

head

head(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-HEAD path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-HEAD path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def head(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-HEAD`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-HEAD`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['HEAD'],
        **kwargs,
    )

options

options(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-OPTIONS path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-OPTIONS path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def options(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-OPTIONS`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-OPTIONS`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['OPTIONS'],
        **kwargs,
    )

patch

patch(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-PATCH path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-PATCH path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def patch(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-PATCH`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-PATCH`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['PATCH'],
        **kwargs,
    )

post

post(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-POST path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-POST path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def post(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-POST`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-POST`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['POST'],
        **kwargs,
    )

put

put(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-PUT path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-PUT path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def put(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-PUT`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-PUT`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['PUT'],
        **kwargs,
    )

trace

trace(
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a HTTP-TRACE path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIRequestRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a HTTP-TRACE path operation.

Note

See also the APIRequestRouteConfigDict dictionary for the available configuration options used for the request route creation within the API.

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

def trace(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIRequestRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a ``HTTP-TRACE`` path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a ``HTTP-TRACE`` path operation.

    Note:
        See also the `APIRequestRouteConfigDict` dictionary for the available
        configuration options used for the request route creation within
        the API.
    """
    return self(
        path=path,
        mode='request',
        methods=['TRACE'],
        **kwargs,
    )

websocket

websocket(
    path: str = Undefined,
    **kwargs: Unpack[APIWebSocketRouteConfigDict],
) -> Callable[[_C], _C]

Decorate a callable with a websocket path operation.

Parameters:

Name	Type	Description	Default
path	str	The path for operation. It is automatically generated from the endpoint name if not provided.	Undefined
**kwargs	Unpack[APIWebSocketRouteConfigDict]	The configuration options for the route operation.	{}

Returns:

Type	Description
Callable[[_C], _C]	A route decorator for a websocket path operation.

Note

See also the APIWebSocketRouteConfigDict dictionary for the available configuration options used for the websocket route creation within the API.

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

def websocket(
    self,
    path: str = Undefined,
    **kwargs: Unpack[APIWebSocketRouteConfigDict],
) -> Callable[[_C], _C]:
    """Decorate a callable with a websocket path operation.

    Args:
        path: The path for operation. It is automatically generated from
            the endpoint name if not provided.
        **kwargs: The configuration options for the route operation.

    Returns:
        A route decorator for a websocket path operation.

    Note:
        See also the `APIWebSocketRouteConfigDict` dictionary for the available
        configuration options used for the websocket route creation within
        the API.
    """
    return self(
        path=path,
        mode='websocket',
        **kwargs,
    )

APIRouter

APIRouter(**kwargs: Unpack[APIRouterConfigDict])

Bases: APIRouter

An API router to group path operations.

It is used to group path operations, for example to structure an app in multiple files. It would then be included in an APIManager class (i.e. a subclass of the FastAPI application), or in another APIRouter class (ultimately included in a manager).

Examples:

>>> from plateforme.api import APIManager, APIRouter
... manager = APIManager()
... router = APIRouter()

>>> @router.get("/users/", tags=["users"])
... async def read_users():
...     return [{"username": "Rick"}, {"username": "Morty"}]

>>> manager.include_router(router)

Note

This class is used internally within the framework and should not be used directly except for advanced use cases.

Initialize an API router.

Parameters:

Name	Type	Description	Default
**kwargs	Unpack[APIRouterConfigDict]	The configuration options for the API router.	{}

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

def __init__(self,  **kwargs: Unpack[APIRouterConfigDict]) -> None:
    """Initialize an API router.

    Args:
        **kwargs: The configuration options for the API router.
    """
    super().__init__(
        prefix=kwargs.get('prefix', ''),
        tags=kwargs.get('tags', None),
        dependencies=kwargs.get('dependencies', None),
        default_response_class=
            kwargs.get('default_response_class', Default(JSONResponse)),
        responses=kwargs.get('responses', None),
        callbacks=kwargs.get('callbacks', None),
        routes=kwargs.get('routes', None),
        redirect_slashes=kwargs.get('redirect_slashes', True),
        default=kwargs.get('default', None),
        dependency_overrides_provider=
            kwargs.get('dependency_overrides_provider', None),
        route_class=kwargs.get('route_class', APIRoute),
        lifespan=kwargs.get('lifespan', None),
        deprecated=kwargs.get('deprecated', None),
        include_in_schema=kwargs.get('include_in_schema', True),
        generate_unique_id_function=kwargs.get(  # type: ignore[arg-type]
            'generate_unique_id_function', Default(generate_unique_id)
        ),
    )

startup async

startup() -> None

Run any .on_startup event handlers.

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

async def startup(self) -> None:
    """
    Run any `.on_startup` event handlers.
    """
    for handler in self.on_startup:
        if is_async_callable(handler):
            await handler()
        else:
            handler()

shutdown async

shutdown() -> None

Run any .on_shutdown event handlers.

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

async def shutdown(self) -> None:
    """
    Run any `.on_shutdown` event handlers.
    """
    for handler in self.on_shutdown:
        if is_async_callable(handler):
            await handler()
        else:
            handler()

lifespan async

lifespan(
    scope: Scope, receive: Receive, send: Send
) -> None

Handle ASGI lifespan messages, which allows us to manage application startup and shutdown events.

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

async def lifespan(self, scope: Scope, receive: Receive, send: Send) -> None:
    """
    Handle ASGI lifespan messages, which allows us to manage application
    startup and shutdown events.
    """
    started = False
    app: typing.Any = scope.get("app")
    await receive()
    try:
        async with self.lifespan_context(app) as maybe_state:
            if maybe_state is not None:
                if "state" not in scope:
                    raise RuntimeError(
                        'The server does not support "state" in the lifespan scope.'
                    )
                scope["state"].update(maybe_state)
            await send({"type": "lifespan.startup.complete"})
            started = True
            await receive()
    except BaseException:
        exc_text = traceback.format_exc()
        if started:
            await send({"type": "lifespan.shutdown.failed", "message": exc_text})
        else:
            await send({"type": "lifespan.startup.failed", "message": exc_text})
        raise
    else:
        await send({"type": "lifespan.shutdown.complete"})

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 router.

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/routing.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 router.

    `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).
    """

    def decorator(func: DecoratedCallable) -> DecoratedCallable:
        self.add_event_handler(event_type, func)
        return func

    return decorator

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

Example

from fastapi import APIRouter, FastAPI, WebSocket

app = FastAPI()
router = APIRouter()

@router.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}")

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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**

    ## Example

    ```python
    from fastapi import APIRouter, FastAPI, WebSocket

    app = FastAPI()
    router = APIRouter()

    @router.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}")

    app.include_router(router)
    ```
    """

    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 APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["GET"],
        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 APIRouter, FastAPI
from pydantic import BaseModel

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

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI
    from pydantic import BaseModel

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

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["PUT"],
        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 APIRouter, FastAPI
from pydantic import BaseModel

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

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI
    from pydantic import BaseModel

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

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["POST"],
        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 APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["DELETE"],
        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 APIRouter, FastAPI

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["OPTIONS"],
        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 APIRouter, FastAPI
from pydantic import BaseModel

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

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI
    from pydantic import BaseModel

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

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["HEAD"],
        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 APIRouter, FastAPI
from pydantic import BaseModel

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

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI
    from pydantic import BaseModel

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

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["PATCH"],
        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 APIRouter, FastAPI
from pydantic import BaseModel

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

app = FastAPI()
router = APIRouter()

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

app.include_router(router)

Source code in .venv/lib/python3.12/site-packages/fastapi/routing.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[params.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[[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 APIRouter, FastAPI
    from pydantic import BaseModel

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

    app = FastAPI()
    router = APIRouter()

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

    app.include_router(router)
    ```
    """
    return self.api_route(
        path=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,
        methods=["TRACE"],
        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,
    )

add_api_websocket_route

add_api_websocket_route(
    path: str,
    endpoint: Callable[..., Any],
    *,
    name: str | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    operation_id: str | None = None,
    generate_unique_id_function: Union[
        APIBaseRouteIdentifier,
        DefaultPlaceholder[APIBaseRouteIdentifier],
    ] = Default(generate_unique_id),
    force_resolution: bool = False,
) -> None

Add a websocket route to the router.

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

def add_api_websocket_route(  # type: ignore[override, unused-ignore]
    self,
    path: str,
    endpoint: Callable[..., Any],
    *,
    name: str | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    operation_id: str | None = None,
    generate_unique_id_function: Union[
        APIBaseRouteIdentifier, DefaultPlaceholder[APIBaseRouteIdentifier]
    ] = Default(generate_unique_id),
    force_resolution: bool = False,
) -> None:
    """Add a websocket route to the router."""
    current_dependencies = self.dependencies.copy()
    if dependencies:
        current_dependencies.extend(dependencies)
    if force_resolution:
        endpoint = resolve_bulk_middleware(endpoint)

    route = APIWebSocketRoute(
        self.prefix + path,
        endpoint,
        name=name,
        dependencies=current_dependencies,
        dependency_overrides_provider=self.dependency_overrides_provider,
        operation_id=operation_id,
        generate_unique_id_function=generate_unique_id_function,
    )

    self.routes.append(route)

include_endpoints

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

Include configured endpoints within the router.

It is used to include within the 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 router.

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

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

    It is used to include within the 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 router.
    """
    for endpoint in endpoints:
        # Check if the endpoint is valid
        if not isinstance(endpoint, APIEndpoint):
            raise PlateformeError(
                f"Route configuration is missing for the provided "
                f"endpoint. (i.e. the endpoint callable does not have a "
                f"`__config_route__` attribute). Please use a routing "
                f"decorator to define a route configuration for the "
                f"endpoint or use directly an appropriate routing method "
                f"(e.g. `add_api_route` or `add_api_websocket_route`). "
                f"Got: {endpoint!r}",
                code='route-invalid-config',
            )

        # Retrieve the endpoint route configuration
        config: APIRouteConfig = getattr(endpoint, '__config_route__')
        config_dict = config.entries(default_mode='preserve')

        # Retrieve the endpoint route mode
        config_mode = config_dict.pop('mode', None)
        if config_mode not in ('request', 'websocket'):
            raise PlateformeError(
                f"Invalid route configuration. The route `mode` is "
                f"missing or invalid. Got: {config_mode!r}",
                code='route-invalid-config',
            )

        # Combine common configuration options
        path = kwargs.pop('prefix', '') + config_dict.pop('path', '')
        dependencies = [
            *(kwargs.pop('dependencies', None) or []),
            *(config_dict.pop('dependencies', None) or []),
        ]
        generate_unique_id = get_value_or_default(
            config_dict.pop('generate_unique_id_function'),
            kwargs.pop('generate_unique_id_function', None)
                or self.generate_unique_id_function,
        )

        # Add the endpoint route to the new router
        if config_mode == 'request':
            tags = [
                *(kwargs.pop('tags', None) or []),
                *(config_dict.pop('tags', None) or []),
            ]
            response_class = get_value_or_default(
                config_dict.pop('response_class'),
                kwargs.pop('default_response_class', None)
                    or self.default_response_class,
            )
            response = {
                **(kwargs.pop('responses', None) or {}),
                **(config_dict.pop('responses', None) or {}),
            }
            callbacks = [
                *(kwargs.pop('callbacks', None) or []),
                *(config_dict.pop('callbacks', None) or []),
            ]
            deprecated = (
                config_dict.pop('deprecated', None)
                or kwargs.pop('deprecated', None)
                or self.deprecated
            )
            include_in_schema = (
                config_dict.pop('include_in_schema', True)
                and kwargs.pop('include_in_schema', True)
                and self.include_in_schema
            )
            self.add_api_route(
                path,
                endpoint,
                tags=tags,
                dependencies=dependencies,
                response_class=response_class,
                responses=response,
                callbacks=callbacks,
                deprecated=deprecated,
                include_in_schema=include_in_schema,
                generate_unique_id_function=generate_unique_id,
                force_resolution=force_resolution,
                **config_dict,
            )
        else:
            self.add_api_websocket_route(
                path,
                endpoint,
                dependencies=dependencies,
                generate_unique_id_function=generate_unique_id,
                force_resolution=force_resolution,
                **config_dict,
            )

        route_id = getattr(self.routes[-1], 'unique_id')

        logger.debug(f"api:{route_id} -> added ")

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/routing.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.
    """
    # Collect all configured endpoints from the object
    endpoints = [
        member for _, member in inspect.getmembers(obj)
        if isinstance(member, APIEndpoint)
    ]

    # Include endpoints within the router
    self.include_endpoints(
        *endpoints,
        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/routing.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]
    )

APIWebSocketRoute

APIWebSocketRoute(
    path: str,
    endpoint: Callable[..., Any],
    *,
    name: str | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    dependency_overrides_provider: Any | None = None,
    operation_id: str | None = None,
    generate_unique_id_function: Union[
        APIBaseRouteIdentifier,
        DefaultPlaceholder[APIBaseRouteIdentifier],
    ] = Default(generate_unique_id),
)

Bases: APIWebSocketRoute

An API websocket route.

Initialize an API websocket route.

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

def __init__(
    self,
    path: str,
    endpoint: Callable[..., Any],
    *,
    name: str | None = None,
    dependencies: Sequence[DependsInfo] | None = None,
    dependency_overrides_provider: Any | None = None,
    operation_id: str | None = None,
    generate_unique_id_function: Union[
        APIBaseRouteIdentifier, DefaultPlaceholder[APIBaseRouteIdentifier]
    ] = Default(generate_unique_id),
) -> None:
    """Initialize an API websocket route."""
    super().__init__(
        path,
        endpoint,
        name=name,
        dependencies=dependencies,
        dependency_overrides_provider=dependency_overrides_provider,
    )

    # Update route configuration
    self.name = get_object_name(endpoint, handler=to_name_case) \
        if name is None else name
    self.operation_id = operation_id
    self.generate_unique_id_function = generate_unique_id_function
    self.unique_id = self.operation_id or \
        get_value_or_default(generate_unique_id_function)(self)

BaseRoute

Route

Route(
    path: str,
    endpoint: Callable[..., Any],
    *,
    methods: list[str] | None = None,
    name: str | None = None,
    include_in_schema: bool = True,
    middleware: Sequence[Middleware] | None = None,
)

Bases: BaseRoute

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

def __init__(
    self,
    path: str,
    endpoint: typing.Callable[..., typing.Any],
    *,
    methods: list[str] | None = None,
    name: str | None = None,
    include_in_schema: bool = True,
    middleware: typing.Sequence[Middleware] | None = None,
) -> None:
    assert path.startswith("/"), "Routed paths must start with '/'"
    self.path = path
    self.endpoint = endpoint
    self.name = get_name(endpoint) if name is None else name
    self.include_in_schema = include_in_schema

    endpoint_handler = endpoint
    while isinstance(endpoint_handler, functools.partial):
        endpoint_handler = endpoint_handler.func
    if inspect.isfunction(endpoint_handler) or inspect.ismethod(endpoint_handler):
        # Endpoint is function or method. Treat it as `func(request) -> response`.
        self.app = request_response(endpoint)
        if methods is None:
            methods = ["GET"]
    else:
        # Endpoint is a class. Treat it as ASGI.
        self.app = endpoint

    if middleware is not None:
        for cls, args, kwargs in reversed(middleware):
            self.app = cls(app=self.app, *args, **kwargs)

    if methods is None:
        self.methods = None
    else:
        self.methods = {method.upper() for method in methods}
        if "GET" in self.methods:
            self.methods.add("HEAD")

    self.path_regex, self.path_format, self.param_convertors = compile_path(path)

APIRouteConfigDict

Bases: APIBaseRouteConfigDict, APIRequestRouteConfigDict, APIWebSocketRouteConfigDict

An API route configuration dictionary.

This configuration extends the APIBaseRouteConfigDict, APIRequestRouteConfigDict, and APIWebSocketRouteConfigDict dictionaries to provide a common configuration for both request and websocket API routes.

dependencies instance-attribute

dependencies: Sequence[DependsInfo] | None

A list of dependencies to be applied to the path operation (using Depends function). Defaults to None.

name instance-attribute

name: str | None

The name of the path operation. It is used internally to identify the path operation. Defaults to None.

tags instance-attribute

tags: list[str | Enum] | None

A list of tags to be applied to the path operation. Defaults to None.

summary instance-attribute

summary: str | None

A summary for the path operation. Defaults to None.

description instance-attribute

description: str | None

A description for the path operation. Defaults to None.

status_code instance-attribute

status_code: int | None

The default status code to be used for the response. Defaults to None.

response_description instance-attribute

response_description: str

The description for the default response. Defaults to "Successful Response".

responses instance-attribute

responses: dict[int | str, dict[str, Any]] | None

Additional responses that could be returned by the path operation. Defaults to None.

deprecated instance-attribute

deprecated: bool | None

Mark this path operation as deprecated. Defaults to None.

response_class instance-attribute

response_class: Union[
    type[Response], DefaultPlaceholder[type[Response]]
]

Response class to be used for this path operation. Defaults to JSONResponse.

response_model instance-attribute

response_model: Any

The type to use for the response. Defaults to None.

response_model_include instance-attribute

response_model_include: IncEx | None

Configuration passed to the model to include only certain fields in the response data. Defaults to None.

response_model_exclude instance-attribute

response_model_exclude: IncEx | None

Configuration passed to the model to exclude certain fields in the response data. Defaults to None.

response_model_by_alias instance-attribute

response_model_by_alias: bool

Configuration passed to the model to define if the response model should be serialized by alias when an alias is used. Defaults to True.

response_model_exclude_unset instance-attribute

response_model_exclude_unset: bool

Configuration passed to the model to define if the response data should have all the fields, including the ones that were not set and have their default values. Defaults to False.

response_model_exclude_defaults instance-attribute

response_model_exclude_defaults: bool

Configuration passed to the model to define if the response data should have all the fields, including the ones that have the same value as the default. Defaults to False.

response_model_exclude_none instance-attribute

response_model_exclude_none: bool

Configuration passed to the model to define if the response data should exclude fields set to None. Defaults to False.

response_model_serialization instance-attribute

response_model_serialization: bool

Whether to serialize the response model. When disabled, the response model configuration is only used for specification purposes and is ignored when generating the response. This is useful when the response model is needed for OpenAPI documentation but the response data should not be serialized. Defaults to True.

callbacks instance-attribute

callbacks: list[BaseRoute] | None

List of path operations that will be used as OpenAPI callbacks. Defaults to None.

include_in_schema instance-attribute

include_in_schema: bool

Include this path operation in the generated OpenAPI schema. Defaults to True.

openapi_extra instance-attribute

openapi_extra: dict[str, Any] | None

Extra metadata to be included in the OpenAPI schema for this path operation. Defaults to None.

path instance-attribute

path: str | None

The path for the operation. If not provided, it is automatically generated from the endpoint name. Defaults to None.

mode instance-attribute

mode: APIMode

The mode used for the path operation. Can be either request or websocket. Defaults to request.

methods instance-attribute

methods: list[APIMethod] | set[APIMethod] | None

A list of HTTP methods to be used for the path operation (e.g. GET, POST, PUT, DELETE, etc.). Defaults to None.

operation_id instance-attribute

operation_id: str | None

The operation ID to be used for the 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. Defaults to None.

generate_unique_id_function instance-attribute

generate_unique_id_function: Union[
    APIBaseRouteIdentifier,
    DefaultPlaceholder[APIBaseRouteIdentifier],
]

A function that generates a unique ID for a given route. Defaults to generate_unique_id.

APIBaseRouterConfigDict

Bases: TypedDict

A base API router configuration dictionary.

prefix instance-attribute

prefix: str

An optional path prefix for the router. Defaults to an empty string ''.

tags instance-attribute

tags: list[str | Enum] | None

A list of tags to be applied to all the path operations in this router. Defaults to None.

dependencies instance-attribute

dependencies: Sequence[DependsInfo] | None

A collection of dependencies to be applied to all the path operations in this router (using Depends). Defaults to None.

default_response_class instance-attribute

default_response_class: type[Response]

The default response class to be used. Defaults to JSONResponse.

responses instance-attribute

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.

callbacks instance-attribute

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.

deprecated instance-attribute

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.

include_in_schema instance-attribute

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.

generate_unique_id_function instance-attribute

generate_unique_id_function: APIBaseRouteIdentifier

A function that generates a unique ID for a given route. Defaults to generate_unique_id.

APIRequestRouteConfigDict

Bases: TypedDict

A request API route configuration dictionary.

dependencies instance-attribute

dependencies: Sequence[DependsInfo] | None

A list of dependencies to be applied to the path operation (using Depends function). Defaults to None.

tags instance-attribute

tags: list[str | Enum] | None

A list of tags to be applied to the path operation. Defaults to None.

summary instance-attribute

summary: str | None

A summary for the path operation. Defaults to None.

description instance-attribute

description: str | None

A description for the path operation. Defaults to None.

status_code instance-attribute

status_code: int | None

The default status code to be used for the response. Defaults to None.

response_description instance-attribute

response_description: str

The description for the default response. Defaults to "Successful Response".

responses instance-attribute

responses: dict[int | str, dict[str, Any]] | None

Additional responses that could be returned by the path operation. Defaults to None.

deprecated instance-attribute

deprecated: bool | None

Mark this path operation as deprecated. Defaults to None.

response_class instance-attribute

response_class: Union[
    type[Response], DefaultPlaceholder[type[Response]]
]

Response class to be used for this path operation. Defaults to JSONResponse.

response_model instance-attribute

response_model: Any

The type to use for the response. Defaults to None.

response_model_include instance-attribute

response_model_include: IncEx | None

Configuration passed to the model to include only certain fields in the response data. Defaults to None.

response_model_exclude instance-attribute

response_model_exclude: IncEx | None

Configuration passed to the model to exclude certain fields in the response data. Defaults to None.

response_model_by_alias instance-attribute

response_model_by_alias: bool

Configuration passed to the model to define if the response model should be serialized by alias when an alias is used. Defaults to True.

response_model_exclude_unset instance-attribute

response_model_exclude_unset: bool

Configuration passed to the model to define if the response data should have all the fields, including the ones that were not set and have their default values. Defaults to False.

response_model_exclude_defaults instance-attribute

response_model_exclude_defaults: bool

Configuration passed to the model to define if the response data should have all the fields, including the ones that have the same value as the default. Defaults to False.

response_model_exclude_none instance-attribute

response_model_exclude_none: bool

Configuration passed to the model to define if the response data should exclude fields set to None. Defaults to False.

response_model_serialization instance-attribute

response_model_serialization: bool

Whether to serialize the response model. When disabled, the response model configuration is only used for specification purposes and is ignored when generating the response. This is useful when the response model is needed for OpenAPI documentation but the response data should not be serialized. Defaults to True.

callbacks instance-attribute

callbacks: list[BaseRoute] | None

List of path operations that will be used as OpenAPI callbacks. Defaults to None.

include_in_schema instance-attribute

include_in_schema: bool

Include this path operation in the generated OpenAPI schema. Defaults to True.

name instance-attribute

name: str | None

The name of the path operation. It is used internally to identify the path operation. Defaults to None.

openapi_extra instance-attribute

openapi_extra: dict[str, Any] | None

Extra metadata to be included in the OpenAPI schema for this path operation. Defaults to None.

APIWebSocketRouteConfigDict

Bases: TypedDict

A websocket API route configuration dictionary.

dependencies instance-attribute

dependencies: Sequence[DependsInfo] | None

A list of dependencies to be applied to the path operation (using Depends function). Defaults to None.

name instance-attribute

name: str | None

The name of the path operation. It is used internally to identify the path operation. Defaults to None.

APIRouterConfigDict

Bases: APIBaseRouterConfigDict, APIExtraRouterConfigDict

An API router configuration dictionary.

This configuration extends the APIBaseRouterConfigDict and APIExtraRouterConfigDict dictionaries to provide a configuration for the API router initialization method.

routes instance-attribute

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.

redirect_slashes instance-attribute

redirect_slashes: bool

Whether to redirect requests with a trailing slash to the same path without the trailing slash. Defaults to True.

default instance-attribute

default: ASGIApp | None

The default function handler to be used for the router. It is used to handle 404 Not Found errors. Defaults to None.

dependency_overrides_provider instance-attribute

dependency_overrides_provider: Any

An optional dependency overrides provider used internally by the router. Defaults to None.

route_class instance-attribute

route_class: type[APIRoute]

The request route class to be used for the router. Defaults to APIRoute.

lifespan instance-attribute

lifespan: Lifespan[Any] | 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.

prefix instance-attribute

prefix: str

An optional path prefix for the router. Defaults to an empty string ''.

tags instance-attribute

tags: list[str | Enum] | None

A list of tags to be applied to all the path operations in this router. Defaults to None.

dependencies instance-attribute

dependencies: Sequence[DependsInfo] | None

A collection of dependencies to be applied to all the path operations in this router (using Depends). Defaults to None.

default_response_class instance-attribute

default_response_class: type[Response]

The default response class to be used. Defaults to JSONResponse.

responses instance-attribute

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.

callbacks instance-attribute

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.

deprecated instance-attribute

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.

include_in_schema instance-attribute

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.

generate_unique_id_function instance-attribute

generate_unique_id_function: APIBaseRouteIdentifier

A function that generates a unique ID for a given route. Defaults to generate_unique_id.

APIBaseRouterConfigDict

Bases: TypedDict

A base API router configuration dictionary.

prefix instance-attribute

prefix: str

An optional path prefix for the router. Defaults to an empty string ''.

tags instance-attribute

tags: list[str | Enum] | None

A list of tags to be applied to all the path operations in this router. Defaults to None.

dependencies instance-attribute

dependencies: Sequence[DependsInfo] | None

A collection of dependencies to be applied to all the path operations in this router (using Depends). Defaults to None.

default_response_class instance-attribute

default_response_class: type[Response]

The default response class to be used. Defaults to JSONResponse.

responses instance-attribute

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.

callbacks instance-attribute

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.

deprecated instance-attribute

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.

include_in_schema instance-attribute

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.

generate_unique_id_function instance-attribute

generate_unique_id_function: APIBaseRouteIdentifier

A function that generates a unique ID for a given route. Defaults to generate_unique_id.

APIExtraRouterConfigDict

Bases: TypedDict

An extra API router configuration dictionary.

routes instance-attribute

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.

redirect_slashes instance-attribute

redirect_slashes: bool

Whether to redirect requests with a trailing slash to the same path without the trailing slash. Defaults to True.

default instance-attribute

default: ASGIApp | None

The default function handler to be used for the router. It is used to handle 404 Not Found errors. Defaults to None.

dependency_overrides_provider instance-attribute

dependency_overrides_provider: Any

An optional dependency overrides provider used internally by the router. Defaults to None.

route_class instance-attribute

route_class: type[APIRoute]

The request route class to be used for the router. Defaults to APIRoute.

lifespan instance-attribute

lifespan: Lifespan[Any] | 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.