back to Reference (Gold) summary
Reference (Gold): fastapi
Pytest Summary for test tests
| status | count |
|---|---|
| passed | 2013 |
| skipped | 75 |
| failed | 1 |
| total | 2089 |
| collected | 2089 |
Failed pytests:
test_openapi_examples.py::test_openapi_schema
test_openapi_examples.py::test_openapi_schema
def test_openapi_schema():
response = client.get("/openapi.json")
assert response.status_code == 200, response.text
> assert response.json() == {
"openapi": "3.1.0",
"info": {"title": "FastAPI", "version": "0.1.0"},
"paths": {
"/examples/": {
"post": {
"summary": "Examples",
"operationId": "examples_examples__post",
"requestBody": {
"content": {
"application/json": {
"schema": {
"allOf": [{"$ref": "#/components/schemas/Item"}],
"title": "Item",
"examples": [
{"data": "Data in Body examples, example1"}
],
},
"examples": {
"Example One": {
"summary": "Example One Summary",
"description": "Example One Description",
"value": {
"data": "Data in Body examples, example1"
},
},
"Example Two": {
"value": {
"data": "Data in Body examples, example2"
}
},
},
}
},
"required": True,
},
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
"/path_examples/{item_id}": {
"get": {
"summary": "Path Examples",
"operationId": "path_examples_path_examples__item_id__get",
"parameters": [
{
"name": "item_id",
"in": "path",
"required": True,
"schema": {
"type": "string",
"examples": [
"json_schema_item_1",
"json_schema_item_2",
],
"title": "Item Id",
},
"examples": {
"Path One": {
"summary": "Path One Summary",
"description": "Path One Description",
"value": "item_1",
},
"Path Two": {"value": "item_2"},
},
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
"/query_examples/": {
"get": {
"summary": "Query Examples",
"operationId": "query_examples_query_examples__get",
"parameters": [
{
"name": "data",
"in": "query",
"required": False,
"schema": IsDict(
{
"anyOf": [{"type": "string"}, {"type": "null"}],
"examples": [
"json_schema_query1",
"json_schema_query2",
],
"title": "Data",
}
)
| IsDict(
# TODO: remove when deprecating Pydantic v1
{
"examples": [
"json_schema_query1",
"json_schema_query2",
],
"type": "string",
"title": "Data",
}
),
"examples": {
"Query One": {
"summary": "Query One Summary",
"description": "Query One Description",
"value": "query1",
},
"Query Two": {"value": "query2"},
},
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
"/header_examples/": {
"get": {
"summary": "Header Examples",
"operationId": "header_examples_header_examples__get",
"parameters": [
{
"name": "data",
"in": "header",
"required": False,
"schema": IsDict(
{
"anyOf": [{"type": "string"}, {"type": "null"}],
"examples": [
"json_schema_header1",
"json_schema_header2",
],
"title": "Data",
}
)
| IsDict(
# TODO: remove when deprecating Pydantic v1
{
"type": "string",
"examples": [
"json_schema_header1",
"json_schema_header2",
],
"title": "Data",
}
),
"examples": {
"Header One": {
"summary": "Header One Summary",
"description": "Header One Description",
"value": "header1",
},
"Header Two": {"value": "header2"},
},
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
"/cookie_examples/": {
"get": {
"summary": "Cookie Examples",
"operationId": "cookie_examples_cookie_examples__get",
"parameters": [
{
"name": "data",
"in": "cookie",
"required": False,
"schema": IsDict(
{
"anyOf": [{"type": "string"}, {"type": "null"}],
"examples": [
"json_schema_cookie1",
"json_schema_cookie2",
],
"title": "Data",
}
)
| IsDict(
# TODO: remove when deprecating Pydantic v1
{
"type": "string",
"examples": [
"json_schema_cookie1",
"json_schema_cookie2",
],
"title": "Data",
}
),
"examples": {
"Cookie One": {
"summary": "Cookie One Summary",
"description": "Cookie One Description",
"value": "cookie1",
},
"Cookie Two": {"value": "cookie2"},
},
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {"application/json": {"schema": {}}},
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
},
},
},
}
},
},
"components": {
"schemas": {
"HTTPValidationError": {
"properties": {
"detail": {
"items": {"$ref": "#/components/schemas/ValidationError"},
"type": "array",
"title": "Detail",
}
},
"type": "object",
"title": "HTTPValidationError",
},
"Item": {
"properties": {"data": {"type": "string", "title": "Data"}},
"type": "object",
"required": ["data"],
"title": "Item",
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [{"type": "string"}, {"type": "integer"}]
},
"type": "array",
"title": "Location",
},
"msg": {"type": "string", "title": "Message"},
"type": {"type": "string", "title": "Error Type"},
},
"type": "object",
"required": ["loc", "msg", "type"],
"title": "ValidationError",
},
}
},
}
E AssertionError: assert {'components'...ples'}}, ...}} == {'components'...ples'}}, ...}}
E
E Omitting 3 identical items, use -vv to show
E Differing items:
E {'paths': {'/cookie_examples/': {'get': {'operationId': 'cookie_examples_cookie_examples__get', 'parameters': [{'examp...ccessful Response'}, '422': {'content': {...}, 'description': 'Validation Error'}}, 'summary': 'Path Examples'}}, ...}} != {'paths': {'/cookie_examples/': {'get': {'operationId': 'cookie_examples_cookie_examples__get', 'parameters': [{'examp...ccessful Response'}, '422': {'content': {...}, 'description': 'Validation Error'}}, 'summary': 'Path Examples'}}, ...}}
E Use -v to get more diff
tests/test_openapi_examples.py:147: AssertionError
Patch diff
diff --git a/fastapi/_compat.py b/fastapi/_compat.py
index 99ee773b..06b847b4 100644
--- a/fastapi/_compat.py
+++ b/fastapi/_compat.py
@@ -2,24 +2,56 @@ from collections import deque
from copy import copy
from dataclasses import dataclass, is_dataclass
from enum import Enum
-from typing import Any, Callable, Deque, Dict, FrozenSet, List, Mapping, Sequence, Set, Tuple, Type, Union
+from typing import (
+ Any,
+ Callable,
+ Deque,
+ Dict,
+ FrozenSet,
+ List,
+ Mapping,
+ Sequence,
+ Set,
+ Tuple,
+ Type,
+ Union,
+)
+
from fastapi.exceptions import RequestErrorModel
from fastapi.types import IncEx, ModelNameMap, UnionType
from pydantic import BaseModel, create_model
from pydantic.version import VERSION as P_VERSION
from starlette.datastructures import UploadFile
from typing_extensions import Annotated, Literal, get_args, get_origin
+
+# Reassign variable to make it reexported for mypy
PYDANTIC_VERSION = P_VERSION
-PYDANTIC_V2 = PYDANTIC_VERSION.startswith('2.')
-sequence_annotation_to_type = {Sequence: list, List: list, list: list,
- Tuple: tuple, tuple: tuple, Set: set, set: set, FrozenSet: frozenset,
- frozenset: frozenset, Deque: deque, deque: deque}
+PYDANTIC_V2 = PYDANTIC_VERSION.startswith("2.")
+
+
+sequence_annotation_to_type = {
+ Sequence: list,
+ List: list,
+ list: list,
+ Tuple: tuple,
+ tuple: tuple,
+ Set: set,
+ set: set,
+ FrozenSet: frozenset,
+ frozenset: frozenset,
+ Deque: deque,
+ deque: deque,
+}
+
sequence_types = tuple(sequence_annotation_to_type.keys())
+
if PYDANTIC_V2:
from pydantic import PydanticSchemaGenerationError as PydanticSchemaGenerationError
from pydantic import TypeAdapter
from pydantic import ValidationError as ValidationError
- from pydantic._internal._schema_generation_shared import GetJsonSchemaHandler as GetJsonSchemaHandler
+ from pydantic._internal._schema_generation_shared import ( # type: ignore[attr-defined]
+ GetJsonSchemaHandler as GetJsonSchemaHandler,
+ )
from pydantic._internal._typing_extra import eval_type_lenient
from pydantic._internal._utils import lenient_issubclass as lenient_issubclass
from pydantic.fields import FieldInfo
@@ -28,68 +60,577 @@ if PYDANTIC_V2:
from pydantic_core import CoreSchema as CoreSchema
from pydantic_core import PydanticUndefined, PydanticUndefinedType
from pydantic_core import Url as Url
+
try:
- from pydantic_core.core_schema import with_info_plain_validator_function as with_info_plain_validator_function
- except ImportError:
- from pydantic_core.core_schema import general_plain_validator_function as with_info_plain_validator_function
+ from pydantic_core.core_schema import (
+ with_info_plain_validator_function as with_info_plain_validator_function,
+ )
+ except ImportError: # pragma: no cover
+ from pydantic_core.core_schema import (
+ general_plain_validator_function as with_info_plain_validator_function, # noqa: F401
+ )
+
Required = PydanticUndefined
Undefined = PydanticUndefined
UndefinedType = PydanticUndefinedType
evaluate_forwardref = eval_type_lenient
Validator = Any
-
class BaseConfig:
pass
-
class ErrorWrapper(Exception):
pass
-
@dataclass
class ModelField:
field_info: FieldInfo
name: str
- mode: Literal['validation', 'serialization'] = 'validation'
+ mode: Literal["validation", "serialization"] = "validation"
- def __post_init__(self) ->None:
- self._type_adapter: TypeAdapter[Any] = TypeAdapter(Annotated[
- self.field_info.annotation, self.field_info])
+ @property
+ def alias(self) -> str:
+ a = self.field_info.alias
+ return a if a is not None else self.name
- def __hash__(self) ->int:
+ @property
+ def required(self) -> bool:
+ return self.field_info.is_required()
+
+ @property
+ def default(self) -> Any:
+ return self.get_default()
+
+ @property
+ def type_(self) -> Any:
+ return self.field_info.annotation
+
+ def __post_init__(self) -> None:
+ self._type_adapter: TypeAdapter[Any] = TypeAdapter(
+ Annotated[self.field_info.annotation, self.field_info]
+ )
+
+ def get_default(self) -> Any:
+ if self.field_info.is_required():
+ return Undefined
+ return self.field_info.get_default(call_default_factory=True)
+
+ def validate(
+ self,
+ value: Any,
+ values: Dict[str, Any] = {}, # noqa: B006
+ *,
+ loc: Tuple[Union[int, str], ...] = (),
+ ) -> Tuple[Any, Union[List[Dict[str, Any]], None]]:
+ try:
+ return (
+ self._type_adapter.validate_python(value, from_attributes=True),
+ None,
+ )
+ except ValidationError as exc:
+ return None, _regenerate_error_with_loc(
+ errors=exc.errors(include_url=False), loc_prefix=loc
+ )
+
+ def serialize(
+ self,
+ value: Any,
+ *,
+ mode: Literal["json", "python"] = "json",
+ include: Union[IncEx, None] = None,
+ exclude: Union[IncEx, None] = None,
+ by_alias: bool = True,
+ exclude_unset: bool = False,
+ exclude_defaults: bool = False,
+ exclude_none: bool = False,
+ ) -> Any:
+ # What calls this code passes a value that already called
+ # self._type_adapter.validate_python(value)
+ return self._type_adapter.dump_python(
+ value,
+ mode=mode,
+ include=include,
+ exclude=exclude,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ )
+
+ def __hash__(self) -> int:
+ # Each ModelField is unique for our purposes, to allow making a dict from
+ # ModelField to its JSON Schema.
return id(self)
+
+ def get_annotation_from_field_info(
+ annotation: Any, field_info: FieldInfo, field_name: str
+ ) -> Any:
+ return annotation
+
+ def _normalize_errors(errors: Sequence[Any]) -> List[Dict[str, Any]]:
+ return errors # type: ignore[return-value]
+
+ def _model_rebuild(model: Type[BaseModel]) -> None:
+ model.model_rebuild()
+
+ def _model_dump(
+ model: BaseModel, mode: Literal["json", "python"] = "json", **kwargs: Any
+ ) -> Any:
+ return model.model_dump(mode=mode, **kwargs)
+
+ def _get_model_config(model: BaseModel) -> Any:
+ return model.model_config
+
+ def get_schema_from_model_field(
+ *,
+ field: ModelField,
+ schema_generator: GenerateJsonSchema,
+ model_name_map: ModelNameMap,
+ field_mapping: Dict[
+ Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
+ ],
+ separate_input_output_schemas: bool = True,
+ ) -> Dict[str, Any]:
+ override_mode: Union[Literal["validation"], None] = (
+ None if separate_input_output_schemas else "validation"
+ )
+ # This expects that GenerateJsonSchema was already used to generate the definitions
+ json_schema = field_mapping[(field, override_mode or field.mode)]
+ if "$ref" not in json_schema:
+ # TODO remove when deprecating Pydantic v1
+ # Ref: https://github.com/pydantic/pydantic/blob/d61792cc42c80b13b23e3ffa74bc37ec7c77f7d1/pydantic/schema.py#L207
+ json_schema["title"] = (
+ field.field_info.title or field.alias.title().replace("_", " ")
+ )
+ return json_schema
+
+ def get_compat_model_name_map(fields: List[ModelField]) -> ModelNameMap:
+ return {}
+
+ def get_definitions(
+ *,
+ fields: List[ModelField],
+ schema_generator: GenerateJsonSchema,
+ model_name_map: ModelNameMap,
+ separate_input_output_schemas: bool = True,
+ ) -> Tuple[
+ Dict[
+ Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
+ ],
+ Dict[str, Dict[str, Any]],
+ ]:
+ override_mode: Union[Literal["validation"], None] = (
+ None if separate_input_output_schemas else "validation"
+ )
+ inputs = [
+ (field, override_mode or field.mode, field._type_adapter.core_schema)
+ for field in fields
+ ]
+ field_mapping, definitions = schema_generator.generate_definitions(
+ inputs=inputs
+ )
+ return field_mapping, definitions # type: ignore[return-value]
+
+ def is_scalar_field(field: ModelField) -> bool:
+ from fastapi import params
+
+ return field_annotation_is_scalar(
+ field.field_info.annotation
+ ) and not isinstance(field.field_info, params.Body)
+
+ def is_sequence_field(field: ModelField) -> bool:
+ return field_annotation_is_sequence(field.field_info.annotation)
+
+ def is_scalar_sequence_field(field: ModelField) -> bool:
+ return field_annotation_is_scalar_sequence(field.field_info.annotation)
+
+ def is_bytes_field(field: ModelField) -> bool:
+ return is_bytes_or_nonable_bytes_annotation(field.type_)
+
+ def is_bytes_sequence_field(field: ModelField) -> bool:
+ return is_bytes_sequence_annotation(field.type_)
+
+ def copy_field_info(*, field_info: FieldInfo, annotation: Any) -> FieldInfo:
+ cls = type(field_info)
+ merged_field_info = cls.from_annotation(annotation)
+ new_field_info = copy(field_info)
+ new_field_info.metadata = merged_field_info.metadata
+ new_field_info.annotation = merged_field_info.annotation
+ return new_field_info
+
+ def serialize_sequence_value(*, field: ModelField, value: Any) -> Sequence[Any]:
+ origin_type = (
+ get_origin(field.field_info.annotation) or field.field_info.annotation
+ )
+ assert issubclass(origin_type, sequence_types) # type: ignore[arg-type]
+ return sequence_annotation_to_type[origin_type](value) # type: ignore[no-any-return]
+
+ def get_missing_field_error(loc: Tuple[str, ...]) -> Dict[str, Any]:
+ error = ValidationError.from_exception_data(
+ "Field required", [{"type": "missing", "loc": loc, "input": {}}]
+ ).errors(include_url=False)[0]
+ error["input"] = None
+ return error # type: ignore[return-value]
+
+ def create_body_model(
+ *, fields: Sequence[ModelField], model_name: str
+ ) -> Type[BaseModel]:
+ field_params = {f.name: (f.field_info.annotation, f.field_info) for f in fields}
+ BodyModel: Type[BaseModel] = create_model(model_name, **field_params) # type: ignore[call-overload]
+ return BodyModel
+
else:
from fastapi.openapi.constants import REF_PREFIX as REF_PREFIX
- from pydantic import AnyUrl as Url
- from pydantic import BaseConfig as BaseConfig
- from pydantic import ValidationError as ValidationError
- from pydantic.class_validators import Validator as Validator
- from pydantic.error_wrappers import ErrorWrapper as ErrorWrapper
+ from pydantic import AnyUrl as Url # noqa: F401
+ from pydantic import ( # type: ignore[assignment]
+ BaseConfig as BaseConfig, # noqa: F401
+ )
+ from pydantic import ValidationError as ValidationError # noqa: F401
+ from pydantic.class_validators import ( # type: ignore[no-redef]
+ Validator as Validator, # noqa: F401
+ )
+ from pydantic.error_wrappers import ( # type: ignore[no-redef]
+ ErrorWrapper as ErrorWrapper, # noqa: F401
+ )
from pydantic.errors import MissingError
- from pydantic.fields import SHAPE_FROZENSET, SHAPE_LIST, SHAPE_SEQUENCE, SHAPE_SET, SHAPE_SINGLETON, SHAPE_TUPLE, SHAPE_TUPLE_ELLIPSIS
+ from pydantic.fields import ( # type: ignore[attr-defined]
+ SHAPE_FROZENSET,
+ SHAPE_LIST,
+ SHAPE_SEQUENCE,
+ SHAPE_SET,
+ SHAPE_SINGLETON,
+ SHAPE_TUPLE,
+ SHAPE_TUPLE_ELLIPSIS,
+ )
from pydantic.fields import FieldInfo as FieldInfo
- from pydantic.fields import ModelField as ModelField
- from pydantic.fields import Required as Required
- from pydantic.fields import Undefined as Undefined
- from pydantic.fields import UndefinedType as UndefinedType
- from pydantic.schema import field_schema, get_flat_models_from_fields, get_model_name_map, model_process_schema
- from pydantic.schema import get_annotation_from_field_info as get_annotation_from_field_info
- from pydantic.typing import evaluate_forwardref as evaluate_forwardref
- from pydantic.utils import lenient_issubclass as lenient_issubclass
- GetJsonSchemaHandler = Any
- JsonSchemaValue = Dict[str, Any]
- CoreSchema = Any
- sequence_shapes = {SHAPE_LIST, SHAPE_SET, SHAPE_FROZENSET, SHAPE_TUPLE,
- SHAPE_SEQUENCE, SHAPE_TUPLE_ELLIPSIS}
- sequence_shape_to_type = {SHAPE_LIST: list, SHAPE_SET: set, SHAPE_TUPLE:
- tuple, SHAPE_SEQUENCE: list, SHAPE_TUPLE_ELLIPSIS: list}
+ from pydantic.fields import ( # type: ignore[no-redef,attr-defined]
+ ModelField as ModelField, # noqa: F401
+ )
+ from pydantic.fields import ( # type: ignore[no-redef,attr-defined]
+ Required as Required, # noqa: F401
+ )
+ from pydantic.fields import ( # type: ignore[no-redef,attr-defined]
+ Undefined as Undefined,
+ )
+ from pydantic.fields import ( # type: ignore[no-redef, attr-defined]
+ UndefinedType as UndefinedType, # noqa: F401
+ )
+ from pydantic.schema import (
+ field_schema,
+ get_flat_models_from_fields,
+ get_model_name_map,
+ model_process_schema,
+ )
+ from pydantic.schema import ( # type: ignore[no-redef] # noqa: F401
+ get_annotation_from_field_info as get_annotation_from_field_info,
+ )
+ from pydantic.typing import ( # type: ignore[no-redef]
+ evaluate_forwardref as evaluate_forwardref, # noqa: F401
+ )
+ from pydantic.utils import ( # type: ignore[no-redef]
+ lenient_issubclass as lenient_issubclass, # noqa: F401
+ )
+
+ GetJsonSchemaHandler = Any # type: ignore[assignment,misc]
+ JsonSchemaValue = Dict[str, Any] # type: ignore[misc]
+ CoreSchema = Any # type: ignore[assignment,misc]
+ sequence_shapes = {
+ SHAPE_LIST,
+ SHAPE_SET,
+ SHAPE_FROZENSET,
+ SHAPE_TUPLE,
+ SHAPE_SEQUENCE,
+ SHAPE_TUPLE_ELLIPSIS,
+ }
+ sequence_shape_to_type = {
+ SHAPE_LIST: list,
+ SHAPE_SET: set,
+ SHAPE_TUPLE: tuple,
+ SHAPE_SEQUENCE: list,
+ SHAPE_TUPLE_ELLIPSIS: list,
+ }
@dataclass
- class GenerateJsonSchema:
+ class GenerateJsonSchema: # type: ignore[no-redef]
ref_template: str
-
- class PydanticSchemaGenerationError(Exception):
+ class PydanticSchemaGenerationError(Exception): # type: ignore[no-redef]
pass
+
+ def with_info_plain_validator_function( # type: ignore[misc]
+ function: Callable[..., Any],
+ *,
+ ref: Union[str, None] = None,
+ metadata: Any = None,
+ serialization: Any = None,
+ ) -> Any:
+ return {}
+
+ def get_model_definitions(
+ *,
+ flat_models: Set[Union[Type[BaseModel], Type[Enum]]],
+ model_name_map: Dict[Union[Type[BaseModel], Type[Enum]], str],
+ ) -> Dict[str, Any]:
+ definitions: Dict[str, Dict[str, Any]] = {}
+ for model in flat_models:
+ m_schema, m_definitions, m_nested_models = model_process_schema(
+ model, model_name_map=model_name_map, ref_prefix=REF_PREFIX
+ )
+ definitions.update(m_definitions)
+ model_name = model_name_map[model]
+ if "description" in m_schema:
+ m_schema["description"] = m_schema["description"].split("\f")[0]
+ definitions[model_name] = m_schema
+ return definitions
+
+ def is_pv1_scalar_field(field: ModelField) -> bool:
+ from fastapi import params
+
+ field_info = field.field_info
+ if not (
+ field.shape == SHAPE_SINGLETON # type: ignore[attr-defined]
+ and not lenient_issubclass(field.type_, BaseModel)
+ and not lenient_issubclass(field.type_, dict)
+ and not field_annotation_is_sequence(field.type_)
+ and not is_dataclass(field.type_)
+ and not isinstance(field_info, params.Body)
+ ):
+ return False
+ if field.sub_fields: # type: ignore[attr-defined]
+ if not all(
+ is_pv1_scalar_field(f)
+ for f in field.sub_fields # type: ignore[attr-defined]
+ ):
+ return False
+ return True
+
+ def is_pv1_scalar_sequence_field(field: ModelField) -> bool:
+ if (field.shape in sequence_shapes) and not lenient_issubclass( # type: ignore[attr-defined]
+ field.type_, BaseModel
+ ):
+ if field.sub_fields is not None: # type: ignore[attr-defined]
+ for sub_field in field.sub_fields: # type: ignore[attr-defined]
+ if not is_pv1_scalar_field(sub_field):
+ return False
+ return True
+ if _annotation_is_sequence(field.type_):
+ return True
+ return False
+
+ def _normalize_errors(errors: Sequence[Any]) -> List[Dict[str, Any]]:
+ use_errors: List[Any] = []
+ for error in errors:
+ if isinstance(error, ErrorWrapper):
+ new_errors = ValidationError( # type: ignore[call-arg]
+ errors=[error], model=RequestErrorModel
+ ).errors()
+ use_errors.extend(new_errors)
+ elif isinstance(error, list):
+ use_errors.extend(_normalize_errors(error))
+ else:
+ use_errors.append(error)
+ return use_errors
+
+ def _model_rebuild(model: Type[BaseModel]) -> None:
+ model.update_forward_refs()
+
+ def _model_dump(
+ model: BaseModel, mode: Literal["json", "python"] = "json", **kwargs: Any
+ ) -> Any:
+ return model.dict(**kwargs)
+
+ def _get_model_config(model: BaseModel) -> Any:
+ return model.__config__ # type: ignore[attr-defined]
+
+ def get_schema_from_model_field(
+ *,
+ field: ModelField,
+ schema_generator: GenerateJsonSchema,
+ model_name_map: ModelNameMap,
+ field_mapping: Dict[
+ Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
+ ],
+ separate_input_output_schemas: bool = True,
+ ) -> Dict[str, Any]:
+ # This expects that GenerateJsonSchema was already used to generate the definitions
+ return field_schema( # type: ignore[no-any-return]
+ field, model_name_map=model_name_map, ref_prefix=REF_PREFIX
+ )[0]
+
+ def get_compat_model_name_map(fields: List[ModelField]) -> ModelNameMap:
+ models = get_flat_models_from_fields(fields, known_models=set())
+ return get_model_name_map(models) # type: ignore[no-any-return]
+
+ def get_definitions(
+ *,
+ fields: List[ModelField],
+ schema_generator: GenerateJsonSchema,
+ model_name_map: ModelNameMap,
+ separate_input_output_schemas: bool = True,
+ ) -> Tuple[
+ Dict[
+ Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
+ ],
+ Dict[str, Dict[str, Any]],
+ ]:
+ models = get_flat_models_from_fields(fields, known_models=set())
+ return {}, get_model_definitions(
+ flat_models=models, model_name_map=model_name_map
+ )
+
+ def is_scalar_field(field: ModelField) -> bool:
+ return is_pv1_scalar_field(field)
+
+ def is_sequence_field(field: ModelField) -> bool:
+ return field.shape in sequence_shapes or _annotation_is_sequence(field.type_) # type: ignore[attr-defined]
+
+ def is_scalar_sequence_field(field: ModelField) -> bool:
+ return is_pv1_scalar_sequence_field(field)
+
+ def is_bytes_field(field: ModelField) -> bool:
+ return lenient_issubclass(field.type_, bytes)
+
+ def is_bytes_sequence_field(field: ModelField) -> bool:
+ return field.shape in sequence_shapes and lenient_issubclass(field.type_, bytes) # type: ignore[attr-defined]
+
+ def copy_field_info(*, field_info: FieldInfo, annotation: Any) -> FieldInfo:
+ return copy(field_info)
+
+ def serialize_sequence_value(*, field: ModelField, value: Any) -> Sequence[Any]:
+ return sequence_shape_to_type[field.shape](value) # type: ignore[no-any-return,attr-defined]
+
+ def get_missing_field_error(loc: Tuple[str, ...]) -> Dict[str, Any]:
+ missing_field_error = ErrorWrapper(MissingError(), loc=loc) # type: ignore[call-arg]
+ new_error = ValidationError([missing_field_error], RequestErrorModel)
+ return new_error.errors()[0] # type: ignore[return-value]
+
+ def create_body_model(
+ *, fields: Sequence[ModelField], model_name: str
+ ) -> Type[BaseModel]:
+ BodyModel = create_model(model_name)
+ for f in fields:
+ BodyModel.__fields__[f.name] = f # type: ignore[index]
+ return BodyModel
+
+
+def _regenerate_error_with_loc(
+ *, errors: Sequence[Any], loc_prefix: Tuple[Union[str, int], ...]
+) -> List[Dict[str, Any]]:
+ updated_loc_errors: List[Any] = [
+ {**err, "loc": loc_prefix + err.get("loc", ())}
+ for err in _normalize_errors(errors)
+ ]
+
+ return updated_loc_errors
+
+
+def _annotation_is_sequence(annotation: Union[Type[Any], None]) -> bool:
+ if lenient_issubclass(annotation, (str, bytes)):
+ return False
+ return lenient_issubclass(annotation, sequence_types)
+
+
+def field_annotation_is_sequence(annotation: Union[Type[Any], None]) -> bool:
+ return _annotation_is_sequence(annotation) or _annotation_is_sequence(
+ get_origin(annotation)
+ )
+
+
+def value_is_sequence(value: Any) -> bool:
+ return isinstance(value, sequence_types) and not isinstance(value, (str, bytes)) # type: ignore[arg-type]
+
+
+def _annotation_is_complex(annotation: Union[Type[Any], None]) -> bool:
+ return (
+ lenient_issubclass(annotation, (BaseModel, Mapping, UploadFile))
+ or _annotation_is_sequence(annotation)
+ or is_dataclass(annotation)
+ )
+
+
+def field_annotation_is_complex(annotation: Union[Type[Any], None]) -> bool:
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ return any(field_annotation_is_complex(arg) for arg in get_args(annotation))
+
+ return (
+ _annotation_is_complex(annotation)
+ or _annotation_is_complex(origin)
+ or hasattr(origin, "__pydantic_core_schema__")
+ or hasattr(origin, "__get_pydantic_core_schema__")
+ )
+
+
+def field_annotation_is_scalar(annotation: Any) -> bool:
+ # handle Ellipsis here to make tuple[int, ...] work nicely
+ return annotation is Ellipsis or not field_annotation_is_complex(annotation)
+
+
+def field_annotation_is_scalar_sequence(annotation: Union[Type[Any], None]) -> bool:
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ at_least_one_scalar_sequence = False
+ for arg in get_args(annotation):
+ if field_annotation_is_scalar_sequence(arg):
+ at_least_one_scalar_sequence = True
+ continue
+ elif not field_annotation_is_scalar(arg):
+ return False
+ return at_least_one_scalar_sequence
+ return field_annotation_is_sequence(annotation) and all(
+ field_annotation_is_scalar(sub_annotation)
+ for sub_annotation in get_args(annotation)
+ )
+
+
+def is_bytes_or_nonable_bytes_annotation(annotation: Any) -> bool:
+ if lenient_issubclass(annotation, bytes):
+ return True
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ for arg in get_args(annotation):
+ if lenient_issubclass(arg, bytes):
+ return True
+ return False
+
+
+def is_uploadfile_or_nonable_uploadfile_annotation(annotation: Any) -> bool:
+ if lenient_issubclass(annotation, UploadFile):
+ return True
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ for arg in get_args(annotation):
+ if lenient_issubclass(arg, UploadFile):
+ return True
+ return False
+
+
+def is_bytes_sequence_annotation(annotation: Any) -> bool:
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ at_least_one = False
+ for arg in get_args(annotation):
+ if is_bytes_sequence_annotation(arg):
+ at_least_one = True
+ continue
+ return at_least_one
+ return field_annotation_is_sequence(annotation) and all(
+ is_bytes_or_nonable_bytes_annotation(sub_annotation)
+ for sub_annotation in get_args(annotation)
+ )
+
+
+def is_uploadfile_sequence_annotation(annotation: Any) -> bool:
+ origin = get_origin(annotation)
+ if origin is Union or origin is UnionType:
+ at_least_one = False
+ for arg in get_args(annotation):
+ if is_uploadfile_sequence_annotation(arg):
+ at_least_one = True
+ continue
+ return at_least_one
+ return field_annotation_is_sequence(annotation) and all(
+ is_uploadfile_or_nonable_uploadfile_annotation(sub_annotation)
+ for sub_annotation in get_args(annotation)
+ )
diff --git a/fastapi/applications.py b/fastapi/applications.py
index 265d637e..4f5e6f1d 100644
--- a/fastapi/applications.py
+++ b/fastapi/applications.py
@@ -1,11 +1,32 @@
from enum import Enum
-from typing import Any, Awaitable, Callable, Coroutine, Dict, List, Optional, Sequence, Type, TypeVar, Union
+from typing import (
+ Any,
+ Awaitable,
+ Callable,
+ Coroutine,
+ Dict,
+ List,
+ Optional,
+ Sequence,
+ Type,
+ TypeVar,
+ Union,
+)
+
from fastapi import routing
from fastapi.datastructures import Default, DefaultPlaceholder
-from fastapi.exception_handlers import http_exception_handler, request_validation_exception_handler, websocket_request_validation_exception_handler
+from fastapi.exception_handlers import (
+ http_exception_handler,
+ request_validation_exception_handler,
+ websocket_request_validation_exception_handler,
+)
from fastapi.exceptions import RequestValidationError, WebSocketRequestValidationError
from fastapi.logger import logger
-from fastapi.openapi.docs import get_redoc_html, get_swagger_ui_html, get_swagger_ui_oauth2_redirect_html
+from fastapi.openapi.docs import (
+ get_redoc_html,
+ get_swagger_ui_html,
+ get_swagger_ui_oauth2_redirect_html,
+)
from fastapi.openapi.utils import get_openapi
from fastapi.params import Depends
from fastapi.types import DecoratedCallable, IncEx
@@ -20,7 +41,8 @@ from starlette.responses import HTMLResponse, JSONResponse, Response
from starlette.routing import BaseRoute
from starlette.types import ASGIApp, Lifespan, Receive, Scope, Send
from typing_extensions import Annotated, Doc, deprecated
-AppType = TypeVar('AppType', bound='FastAPI')
+
+AppType = TypeVar("AppType", bound="FastAPI")
class FastAPI(Starlette):
@@ -39,16 +61,25 @@ class FastAPI(Starlette):
```
"""
- def __init__(self: AppType, *, debug: Annotated[bool, Doc(
- """
+ def __init__(
+ self: AppType,
+ *,
+ debug: Annotated[
+ bool,
+ Doc(
+ """
Boolean indicating if debug tracebacks should be returned on server
errors.
Read more in the
[Starlette docs for Applications](https://www.starlette.io/applications/#instantiating-the-application).
"""
- )]=False, routes: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = False,
+ routes: Annotated[
+ Optional[List[BaseRoute]],
+ Doc(
+ """
**Note**: you probably shouldn't use this parameter, it is inherited
from Starlette and supported for compatibility.
@@ -56,16 +87,21 @@ class FastAPI(Starlette):
A list of routes to serve incoming HTTP and WebSocket requests.
"""
- ), deprecated(
- """
+ ),
+ deprecated(
+ """
You normally wouldn't use this parameter with FastAPI, it is inherited
from Starlette and supported for compatibility.
In FastAPI, you normally would use the *path operation methods*,
like `app.get()`, `app.post()`, etc.
"""
- )]=None, title: Annotated[str, Doc(
- """
+ ),
+ ] = None,
+ title: Annotated[
+ str,
+ Doc(
+ """
The title of the API.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -81,8 +117,12 @@ class FastAPI(Starlette):
app = FastAPI(title="ChimichangApp")
```
"""
- )]='FastAPI', summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = "FastAPI",
+ summary: Annotated[
+ Optional[str],
+ Doc(
+ """
A short summary of the API.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -98,8 +138,12 @@ class FastAPI(Starlette):
app = FastAPI(summary="Deadpond's favorite app. Nuff said.")
```
"""
- )]=None, description: Annotated[str, Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ str,
+ Doc(
+ '''
A description of the API. Supports Markdown (using
[CommonMark syntax](https://commonmark.org/)).
@@ -114,7 +158,7 @@ class FastAPI(Starlette):
from fastapi import FastAPI
app = FastAPI(
- description=""\"
+ description="""
ChimichangApp API helps you do awesome stuff. 🚀
## Items
@@ -128,12 +172,16 @@ class FastAPI(Starlette):
* **Create users** (_not implemented_).
* **Read users** (_not implemented_).
- ""\"
+ """
)
```
+ '''
+ ),
+ ] = "",
+ version: Annotated[
+ str,
+ Doc(
"""
- )]='', version: Annotated[str, Doc(
- """
The version of the API.
**Note** This is the version of your application, not the version of
@@ -152,8 +200,12 @@ class FastAPI(Starlette):
app = FastAPI(version="0.0.1")
```
"""
- )]='0.1.0', openapi_url: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = "0.1.0",
+ openapi_url: Annotated[
+ Optional[str],
+ Doc(
+ """
The URL where the OpenAPI schema will be served from.
If you set it to `None`, no OpenAPI schema will be served publicly, and
@@ -171,9 +223,12 @@ class FastAPI(Starlette):
app = FastAPI(openapi_url="/api/v1/openapi.json")
```
"""
- )]='/openapi.json', openapi_tags: Annotated[Optional[List[Dict[str,
- Any]]], Doc(
- """
+ ),
+ ] = "/openapi.json",
+ openapi_tags: Annotated[
+ Optional[List[Dict[str, Any]]],
+ Doc(
+ """
A list of tags used by OpenAPI, these are the same `tags` you can set
in the *path operations*, like:
@@ -228,9 +283,12 @@ class FastAPI(Starlette):
app = FastAPI(openapi_tags=tags_metadata)
```
"""
- )]=None, servers: Annotated[Optional[List[Dict[str, Union[str, Any]
- ]]], Doc(
- """
+ ),
+ ] = None,
+ servers: Annotated[
+ Optional[List[Dict[str, Union[str, Any]]]],
+ Doc(
+ """
A `list` of `dict`s with connectivity information to a target server.
You would use it, for example, if your application is served from
@@ -269,8 +327,12 @@ class FastAPI(Starlette):
)
```
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of global dependencies, they will be applied to each
*path operation*, including in sub-routers.
@@ -287,8 +349,12 @@ class FastAPI(Starlette):
app = FastAPI(dependencies=[Depends(func_dep_1), Depends(func_dep_2)])
```
"""
- )]=None, default_response_class: Annotated[Type[Response], Doc(
- """
+ ),
+ ] = None,
+ default_response_class: Annotated[
+ Type[Response],
+ Doc(
+ """
The default response class to be used.
Read more in the
@@ -303,8 +369,12 @@ class FastAPI(Starlette):
app = FastAPI(default_response_class=ORJSONResponse)
```
"""
- )]=Default(JSONResponse), redirect_slashes: Annotated[bool, Doc(
- """
+ ),
+ ] = Default(JSONResponse),
+ redirect_slashes: Annotated[
+ bool,
+ Doc(
+ """
Whether to detect and redirect slashes in URLs when the client doesn't
use the same format.
@@ -324,8 +394,12 @@ class FastAPI(Starlette):
they will be automatically redirected with an HTTP status code of 307
to `/items/`.
"""
- )]=True, docs_url: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = True,
+ docs_url: Annotated[
+ Optional[str],
+ Doc(
+ """
The path to the automatic interactive API documentation.
It is handled in the browser by Swagger UI.
@@ -344,8 +418,12 @@ class FastAPI(Starlette):
app = FastAPI(docs_url="/documentation", redoc_url=None)
```
"""
- )]='/docs', redoc_url: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = "/docs",
+ redoc_url: Annotated[
+ Optional[str],
+ Doc(
+ """
The path to the alternative automatic interactive API documentation
provided by ReDoc.
@@ -364,9 +442,12 @@ class FastAPI(Starlette):
app = FastAPI(docs_url="/documentation", redoc_url="redocumentation")
```
"""
- )]='/redoc', swagger_ui_oauth2_redirect_url: Annotated[Optional[str
- ], Doc(
- """
+ ),
+ ] = "/redoc",
+ swagger_ui_oauth2_redirect_url: Annotated[
+ Optional[str],
+ Doc(
+ """
The OAuth2 redirect endpoint for the Swagger UI.
By default it is `/docs/oauth2-redirect`.
@@ -374,16 +455,23 @@ class FastAPI(Starlette):
This is only used if you use OAuth2 (with the "Authorize" button)
with Swagger UI.
"""
- )]='/docs/oauth2-redirect', swagger_ui_init_oauth: Annotated[
- Optional[Dict[str, Any]], Doc(
- """
+ ),
+ ] = "/docs/oauth2-redirect",
+ swagger_ui_init_oauth: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
OAuth2 configuration for the Swagger UI, by default shown at `/docs`.
Read more about the available configuration options in the
[Swagger UI docs](https://swagger.io/docs/open-source-tools/swagger-ui/usage/oauth2/).
"""
- )]=None, middleware: Annotated[Optional[Sequence[Middleware]], Doc(
- """
+ ),
+ ] = None,
+ middleware: Annotated[
+ Optional[Sequence[Middleware]],
+ Doc(
+ """
List of middleware to be added when creating the application.
In FastAPI you would normally do this with `app.add_middleware()`
@@ -392,10 +480,17 @@ class FastAPI(Starlette):
Read more in the
[FastAPI docs for Middleware](https://fastapi.tiangolo.com/tutorial/middleware/).
"""
- )]=None, exception_handlers: Annotated[Optional[Dict[Union[int,
- Type[Exception]], Callable[[Request, Any], Coroutine[Any, Any,
- Response]]]], Doc(
- """
+ ),
+ ] = None,
+ exception_handlers: Annotated[
+ Optional[
+ Dict[
+ Union[int, Type[Exception]],
+ Callable[[Request, Any], Coroutine[Any, Any, Response]],
+ ]
+ ],
+ Doc(
+ """
A dictionary with handlers for exceptions.
In FastAPI, you would normally use the decorator
@@ -404,18 +499,24 @@ class FastAPI(Starlette):
Read more in the
[FastAPI docs for Handling Errors](https://fastapi.tiangolo.com/tutorial/handling-errors/).
"""
- )]=None, on_startup: Annotated[Optional[Sequence[Callable[[], Any]]
- ], Doc(
- """
+ ),
+ ] = None,
+ on_startup: Annotated[
+ Optional[Sequence[Callable[[], Any]]],
+ Doc(
+ """
A list of startup event handler functions.
You should instead use the `lifespan` handlers.
Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
"""
- )]=None, on_shutdown: Annotated[Optional[Sequence[Callable[[], Any]
- ]], Doc(
- """
+ ),
+ ] = None,
+ on_shutdown: Annotated[
+ Optional[Sequence[Callable[[], Any]]],
+ Doc(
+ """
A list of shutdown event handler functions.
You should instead use the `lifespan` handlers.
@@ -423,16 +524,24 @@ class FastAPI(Starlette):
Read more in the
[FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
"""
- )]=None, lifespan: Annotated[Optional[Lifespan[AppType]], Doc(
- """
+ ),
+ ] = None,
+ lifespan: Annotated[
+ Optional[Lifespan[AppType]],
+ Doc(
+ """
A `Lifespan` context manager handler. This replaces `startup` and
`shutdown` functions with a single context manager.
Read more in the
[FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
"""
- )]=None, terms_of_service: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ terms_of_service: Annotated[
+ Optional[str],
+ Doc(
+ """
A URL to the Terms of Service for your API.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -446,9 +555,12 @@ class FastAPI(Starlette):
app = FastAPI(terms_of_service="http://example.com/terms/")
```
"""
- )]=None, contact: Annotated[Optional[Dict[str, Union[str, Any]]],
- Doc(
- """
+ ),
+ ] = None,
+ contact: Annotated[
+ Optional[Dict[str, Union[str, Any]]],
+ Doc(
+ """
A dictionary with the contact information for the exposed API.
It can contain several fields.
@@ -476,9 +588,12 @@ class FastAPI(Starlette):
)
```
"""
- )]=None, license_info: Annotated[Optional[Dict[str, Union[str, Any]
- ]], Doc(
- """
+ ),
+ ] = None,
+ license_info: Annotated[
+ Optional[Dict[str, Union[str, Any]]],
+ Doc(
+ """
A dictionary with the license information for the exposed API.
It can contain several fields.
@@ -507,18 +622,27 @@ class FastAPI(Starlette):
)
```
"""
- )]=None, openapi_prefix: Annotated[str, Doc(
- """
+ ),
+ ] = None,
+ openapi_prefix: Annotated[
+ str,
+ Doc(
+ """
A URL prefix for the OpenAPI URL.
"""
- ), deprecated(
- """
+ ),
+ deprecated(
+ """
"openapi_prefix" has been deprecated in favor of "root_path", which
follows more closely the ASGI standard, is simpler, and more
automatic.
"""
- )]='', root_path: Annotated[str, Doc(
- """
+ ),
+ ] = "",
+ root_path: Annotated[
+ str,
+ Doc(
+ """
A path prefix handled by a proxy that is not seen by the application
but is seen by external clients, which affects things like Swagger UI.
@@ -533,8 +657,12 @@ class FastAPI(Starlette):
app = FastAPI(root_path="/api/v1")
```
"""
- )]='', root_path_in_servers: Annotated[bool, Doc(
- """
+ ),
+ ] = "",
+ root_path_in_servers: Annotated[
+ bool,
+ Doc(
+ """
To disable automatically generating the URLs in the `servers` field
in the autogenerated OpenAPI using the `root_path`.
@@ -549,9 +677,12 @@ class FastAPI(Starlette):
app = FastAPI(root_path_in_servers=False)
```
"""
- )]=True, responses: Annotated[Optional[Dict[Union[int, str], Dict[
- str, Any]]], Doc(
- """
+ ),
+ ] = True,
+ responses: Annotated[
+ Optional[Dict[Union[int, str], Dict[str, Any]]],
+ Doc(
+ """
Additional responses to be shown in OpenAPI.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -562,8 +693,12 @@ class FastAPI(Starlette):
And in the
[FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = None,
+ callbacks: Annotated[
+ Optional[List[BaseRoute]],
+ Doc(
+ """
OpenAPI callbacks that should apply to all *path operations*.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -571,8 +706,12 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
"""
- )]=None, webhooks: Annotated[Optional[routing.APIRouter], Doc(
- """
+ ),
+ ] = None,
+ webhooks: Annotated[
+ Optional[routing.APIRouter],
+ Doc(
+ """
Add OpenAPI webhooks. This is similar to `callbacks` but it doesn't
depend on specific *path operations*.
@@ -583,8 +722,12 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/).
"""
- )]=None, deprecated: Annotated[Optional[bool], Doc(
- """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Optional[bool],
+ Doc(
+ """
Mark all *path operations* as deprecated. You probably don't need it,
but it's available.
@@ -593,8 +736,12 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
"""
- )]=None, include_in_schema: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
To include (or not) all the *path operations* in the generated OpenAPI.
You probably don't need it, but it's available.
@@ -603,18 +750,24 @@ class FastAPI(Starlette):
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, swagger_ui_parameters: Annotated[Optional[Dict[str, Any]],
- Doc(
- """
+ ),
+ ] = True,
+ swagger_ui_parameters: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Parameters to configure Swagger UI, the autogenerated interactive API
documentation (by default at `/docs`).
Read more about it in the
[FastAPI docs about how to Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -624,9 +777,12 @@ class FastAPI(Starlette):
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), separate_input_output_schemas:
- Annotated[bool, Doc(
- """
+ ),
+ ] = Default(generate_unique_id),
+ separate_input_output_schemas: Annotated[
+ bool,
+ Doc(
+ """
Whether to generate separate OpenAPI schemas for request body and
response body when the results would be more precise.
@@ -652,12 +808,18 @@ class FastAPI(Starlette):
In this case, there would be two different schemas, one for input and
another one for output.
"""
- )]=True, **extra: Annotated[Any, Doc(
- """
+ ),
+ ] = True,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
Extra keyword arguments to be stored in the app, not used by FastAPI
anywhere.
"""
- )]) ->None:
+ ),
+ ],
+ ) -> None:
self.debug = debug
self.title = title
self.summary = summary
@@ -677,8 +839,10 @@ class FastAPI(Starlette):
self.servers = servers or []
self.separate_input_output_schemas = separate_input_output_schemas
self.extra = extra
- self.openapi_version: Annotated[str, Doc(
- """
+ self.openapi_version: Annotated[
+ str,
+ Doc(
+ """
The version string of OpenAPI.
FastAPI will generate OpenAPI version 3.1.0, and will output that as
@@ -704,27 +868,37 @@ class FastAPI(Starlette):
app.openapi_version = "3.0.2"
```
"""
- )] = '3.1.0'
+ ),
+ ] = "3.1.0"
self.openapi_schema: Optional[Dict[str, Any]] = None
if self.openapi_url:
assert self.title, "A title must be provided for OpenAPI, e.g.: 'My API'"
assert self.version, "A version must be provided for OpenAPI, e.g.: '2.1.0'"
+ # TODO: remove when discarding the openapi_prefix parameter
if openapi_prefix:
logger.warning(
- '"openapi_prefix" has been deprecated in favor of "root_path", which follows more closely the ASGI standard, is simpler, and more automatic. Check the docs at https://fastapi.tiangolo.com/advanced/sub-applications/'
- )
- self.webhooks: Annotated[routing.APIRouter, Doc(
- """
+ '"openapi_prefix" has been deprecated in favor of "root_path", which '
+ "follows more closely the ASGI standard, is simpler, and more "
+ "automatic. Check the docs at "
+ "https://fastapi.tiangolo.com/advanced/sub-applications/"
+ )
+ self.webhooks: Annotated[
+ routing.APIRouter,
+ Doc(
+ """
The `app.webhooks` attribute is an `APIRouter` with the *path
operations* that will be used just for documentation of webhooks.
Read more about it in the
[FastAPI docs for OpenAPI Webhooks](https://fastapi.tiangolo.com/advanced/openapi-webhooks/).
"""
- )] = webhooks or routing.APIRouter()
+ ),
+ ] = webhooks or routing.APIRouter()
self.root_path = root_path or openapi_prefix
- self.state: Annotated[State, Doc(
- """
+ self.state: Annotated[
+ State,
+ Doc(
+ """
A state object for the application. This is the same object for the
entire application, it doesn't change from request to request.
@@ -736,10 +910,12 @@ class FastAPI(Starlette):
Read more about it in the
[Starlette docs for Applications](https://www.starlette.io/applications/#storing-state-on-the-app-instance).
"""
- )] = State()
- self.dependency_overrides: Annotated[Dict[Callable[..., Any],
- Callable[..., Any]], Doc(
- """
+ ),
+ ] = State()
+ self.dependency_overrides: Annotated[
+ Dict[Callable[..., Any], Callable[..., Any]],
+ Doc(
+ """
A dictionary with overrides for the dependencies.
Each key is the original dependency callable, and the value is the
@@ -751,30 +927,43 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Testing Dependencies with Overrides](https://fastapi.tiangolo.com/advanced/testing-dependencies/).
"""
- )] = {}
- self.router: routing.APIRouter = routing.APIRouter(routes=routes,
+ ),
+ ] = {}
+ self.router: routing.APIRouter = routing.APIRouter(
+ routes=routes,
redirect_slashes=redirect_slashes,
- dependency_overrides_provider=self, on_startup=on_startup,
- on_shutdown=on_shutdown, lifespan=lifespan,
- default_response_class=default_response_class, dependencies=
- dependencies, callbacks=callbacks, deprecated=deprecated,
- include_in_schema=include_in_schema, responses=responses,
- generate_unique_id_function=generate_unique_id_function)
- self.exception_handlers: Dict[Any, Callable[[Request, Any], Union[
- Response, Awaitable[Response]]]] = {
- } if exception_handlers is None else dict(exception_handlers)
- self.exception_handlers.setdefault(HTTPException,
- http_exception_handler)
- self.exception_handlers.setdefault(RequestValidationError,
- request_validation_exception_handler)
- self.exception_handlers.setdefault(WebSocketRequestValidationError,
- websocket_request_validation_exception_handler)
- self.user_middleware: List[Middleware] = [
- ] if middleware is None else list(middleware)
+ dependency_overrides_provider=self,
+ on_startup=on_startup,
+ on_shutdown=on_shutdown,
+ lifespan=lifespan,
+ default_response_class=default_response_class,
+ dependencies=dependencies,
+ callbacks=callbacks,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ responses=responses,
+ generate_unique_id_function=generate_unique_id_function,
+ )
+ self.exception_handlers: Dict[
+ Any, Callable[[Request, Any], Union[Response, Awaitable[Response]]]
+ ] = {} if exception_handlers is None else dict(exception_handlers)
+ self.exception_handlers.setdefault(HTTPException, http_exception_handler)
+ self.exception_handlers.setdefault(
+ RequestValidationError, request_validation_exception_handler
+ )
+ self.exception_handlers.setdefault(
+ WebSocketRequestValidationError,
+ # Starlette still has incorrect type specification for the handlers
+ websocket_request_validation_exception_handler, # type: ignore
+ )
+
+ self.user_middleware: List[Middleware] = (
+ [] if middleware is None else list(middleware)
+ )
self.middleware_stack: Union[ASGIApp, None] = None
self.setup()
- def openapi(self) ->Dict[str, Any]:
+ def openapi(self) -> Dict[str, Any]:
"""
Generate the OpenAPI schema of the application. This is called by FastAPI
internally.
@@ -788,32 +977,248 @@ class FastAPI(Starlette):
Read more in the
[FastAPI docs for OpenAPI](https://fastapi.tiangolo.com/how-to/extending-openapi/).
"""
- pass
+ if not self.openapi_schema:
+ self.openapi_schema = get_openapi(
+ title=self.title,
+ version=self.version,
+ openapi_version=self.openapi_version,
+ summary=self.summary,
+ description=self.description,
+ terms_of_service=self.terms_of_service,
+ contact=self.contact,
+ license_info=self.license_info,
+ routes=self.routes,
+ webhooks=self.webhooks.routes,
+ tags=self.openapi_tags,
+ servers=self.servers,
+ separate_input_output_schemas=self.separate_input_output_schemas,
+ )
+ return self.openapi_schema
+
+ def setup(self) -> None:
+ if self.openapi_url:
+ urls = (server_data.get("url") for server_data in self.servers)
+ server_urls = {url for url in urls if url}
+
+ async def openapi(req: Request) -> JSONResponse:
+ root_path = req.scope.get("root_path", "").rstrip("/")
+ if root_path not in server_urls:
+ if root_path and self.root_path_in_servers:
+ self.servers.insert(0, {"url": root_path})
+ server_urls.add(root_path)
+ return JSONResponse(self.openapi())
+
+ self.add_route(self.openapi_url, openapi, include_in_schema=False)
+ if self.openapi_url and self.docs_url:
+
+ async def swagger_ui_html(req: Request) -> HTMLResponse:
+ root_path = req.scope.get("root_path", "").rstrip("/")
+ openapi_url = root_path + self.openapi_url
+ oauth2_redirect_url = self.swagger_ui_oauth2_redirect_url
+ if oauth2_redirect_url:
+ oauth2_redirect_url = root_path + oauth2_redirect_url
+ return get_swagger_ui_html(
+ openapi_url=openapi_url,
+ title=f"{self.title} - Swagger UI",
+ oauth2_redirect_url=oauth2_redirect_url,
+ init_oauth=self.swagger_ui_init_oauth,
+ swagger_ui_parameters=self.swagger_ui_parameters,
+ )
+
+ self.add_route(self.docs_url, swagger_ui_html, include_in_schema=False)
+
+ if self.swagger_ui_oauth2_redirect_url:
+
+ async def swagger_ui_redirect(req: Request) -> HTMLResponse:
+ return get_swagger_ui_oauth2_redirect_html()
+
+ self.add_route(
+ self.swagger_ui_oauth2_redirect_url,
+ swagger_ui_redirect,
+ include_in_schema=False,
+ )
+ if self.openapi_url and self.redoc_url:
+
+ async def redoc_html(req: Request) -> HTMLResponse:
+ root_path = req.scope.get("root_path", "").rstrip("/")
+ openapi_url = root_path + self.openapi_url
+ return get_redoc_html(
+ openapi_url=openapi_url, title=f"{self.title} - ReDoc"
+ )
- async def __call__(self, scope: Scope, receive: Receive, send: Send
- ) ->None:
+ self.add_route(self.redoc_url, redoc_html, include_in_schema=False)
+
+ async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
if self.root_path:
- scope['root_path'] = self.root_path
+ scope["root_path"] = self.root_path
await super().__call__(scope, receive, send)
- def websocket(self, path: Annotated[str, Doc(
- """
+ def add_api_route(
+ self,
+ path: str,
+ endpoint: Callable[..., Coroutine[Any, Any, Response]],
+ *,
+ response_model: Any = Default(None),
+ status_code: Optional[int] = None,
+ tags: Optional[List[Union[str, Enum]]] = None,
+ dependencies: Optional[Sequence[Depends]] = None,
+ summary: Optional[str] = None,
+ description: Optional[str] = None,
+ response_description: str = "Successful Response",
+ responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
+ deprecated: Optional[bool] = None,
+ methods: Optional[List[str]] = None,
+ operation_id: Optional[str] = None,
+ response_model_include: Optional[IncEx] = None,
+ response_model_exclude: Optional[IncEx] = 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,
+ include_in_schema: bool = True,
+ response_class: Union[Type[Response], DefaultPlaceholder] = Default(
+ JSONResponse
+ ),
+ name: Optional[str] = None,
+ openapi_extra: Optional[Dict[str, Any]] = None,
+ generate_unique_id_function: Callable[[routing.APIRoute], str] = Default(
+ generate_unique_id
+ ),
+ ) -> None:
+ self.router.add_api_route(
+ path,
+ endpoint=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,
+ methods=methods,
+ 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,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
+
+ def api_route(
+ self,
+ path: str,
+ *,
+ response_model: Any = Default(None),
+ status_code: Optional[int] = None,
+ tags: Optional[List[Union[str, Enum]]] = None,
+ dependencies: Optional[Sequence[Depends]] = None,
+ summary: Optional[str] = None,
+ description: Optional[str] = None,
+ response_description: str = "Successful Response",
+ responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
+ deprecated: Optional[bool] = None,
+ methods: Optional[List[str]] = None,
+ operation_id: Optional[str] = None,
+ response_model_include: Optional[IncEx] = None,
+ response_model_exclude: Optional[IncEx] = 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,
+ include_in_schema: bool = True,
+ response_class: Type[Response] = Default(JSONResponse),
+ name: Optional[str] = None,
+ openapi_extra: Optional[Dict[str, Any]] = None,
+ generate_unique_id_function: Callable[[routing.APIRoute], str] = Default(
+ generate_unique_id
+ ),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.router.add_api_route(
+ path,
+ func,
+ 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=methods,
+ 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,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
+ return func
+
+ return decorator
+
+ def add_api_websocket_route(
+ self,
+ path: str,
+ endpoint: Callable[..., Any],
+ name: Optional[str] = None,
+ *,
+ dependencies: Optional[Sequence[Depends]] = None,
+ ) -> None:
+ self.router.add_api_websocket_route(
+ path,
+ endpoint,
+ name=name,
+ dependencies=dependencies,
+ )
+
+ def websocket(
+ self,
+ path: Annotated[
+ str,
+ Doc(
+ """
WebSocket path.
- """)], name:
- Annotated[Optional[str], Doc(
- """
+ """
+ ),
+ ],
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
A name for the WebSocket. Only used internally.
"""
- )]=None, *, dependencies: Annotated[Optional[Sequence[Depends]],
- Doc(
- """
+ ),
+ ] = None,
+ *,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be used for this
WebSocket.
Read more about it in the
[FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).
"""
- )]=None) ->Callable[[DecoratedCallable], DecoratedCallable]:
+ ),
+ ] = None,
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Decorate a WebSocket function.
@@ -835,13 +1240,27 @@ class FastAPI(Starlette):
await websocket.send_text(f"Message text was: {data}")
```
"""
- pass
- def include_router(self, router: Annotated[routing.APIRouter, Doc(
- 'The `APIRouter` to include.')], *, prefix: Annotated[str, Doc(
- 'An optional path prefix for the router.')]='', tags: Annotated[
- Optional[List[Union[str, Enum]]], Doc(
- """
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_api_websocket_route(
+ path,
+ func,
+ name=name,
+ dependencies=dependencies,
+ )
+ return func
+
+ return decorator
+
+ def include_router(
+ self,
+ router: Annotated[routing.APIRouter, Doc("The `APIRouter` to include.")],
+ *,
+ prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "",
+ tags: Annotated[
+ Optional[List[Union[str, Enum]]],
+ Doc(
+ """
A list of tags to be applied to all the *path operations* in this
router.
@@ -850,8 +1269,12 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to all the
*path operations* in this router.
@@ -874,9 +1297,12 @@ class FastAPI(Starlette):
)
```
"""
- )]=None, responses: Annotated[Optional[Dict[Union[int, str], Dict[
- str, Any]]], Doc(
- """
+ ),
+ ] = None,
+ responses: Annotated[
+ Optional[Dict[Union[int, str], Dict[str, Any]]],
+ Doc(
+ """
Additional responses to be shown in OpenAPI.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -887,8 +1313,12 @@ class FastAPI(Starlette):
And in the
[FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
"""
- )]=None, deprecated: Annotated[Optional[bool], Doc(
- """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Optional[bool],
+ Doc(
+ """
Mark all the *path operations* in this router as deprecated.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -908,8 +1338,12 @@ class FastAPI(Starlette):
)
```
"""
- )]=None, include_in_schema: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
Include (or not) all the *path operations* in this router in the
generated OpenAPI schema.
@@ -930,8 +1364,12 @@ class FastAPI(Starlette):
)
```
"""
- )]=True, default_response_class: Annotated[Type[Response], Doc(
- """
+ ),
+ ] = True,
+ default_response_class: Annotated[
+ Type[Response],
+ Doc(
+ """
Default response class to be used for the *path operations* in this
router.
@@ -954,9 +1392,12 @@ class FastAPI(Starlette):
)
```
"""
- )]=Default(JSONResponse), callbacks: Annotated[Optional[List[
- BaseRoute]], Doc(
- """
+ ),
+ ] = Default(JSONResponse),
+ 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
@@ -967,9 +1408,12 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -979,7 +1423,9 @@ class FastAPI(Starlette):
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)) ->None:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> None:
"""
Include an `APIRouter` in the same app.
@@ -998,16 +1444,36 @@ class FastAPI(Starlette):
app.include_router(users_router)
```
"""
- pass
+ self.router.include_router(
+ router,
+ prefix=prefix,
+ tags=tags,
+ dependencies=dependencies,
+ responses=responses,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ default_response_class=default_response_class,
+ callbacks=callbacks,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def get(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1036,8 +1502,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1045,8 +1515,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1054,16 +1528,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -1071,8 +1553,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1085,27 +1571,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1120,32 +1621,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1158,8 +1675,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -1171,8 +1692,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -1184,8 +1709,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1193,8 +1722,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1202,12 +1735,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -1218,17 +1759,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -1238,8 +1786,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP GET operation.
@@ -1255,16 +1804,49 @@ class FastAPI(Starlette):
return [{"name": "Empanada"}, {"name": "Arepa"}]
```
"""
- pass
+ return self.router.get(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def put(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1293,8 +1875,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1302,8 +1888,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1311,16 +1901,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -1328,8 +1926,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1342,27 +1944,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1377,32 +1994,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1415,8 +2048,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -1428,8 +2065,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -1441,8 +2082,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1450,8 +2095,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1459,12 +2108,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -1475,17 +2132,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -1495,8 +2159,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP PUT operation.
@@ -1517,16 +2182,49 @@ class FastAPI(Starlette):
return {"message": "Item replaced", "id": item_id}
```
"""
- pass
+ return self.router.put(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def post(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1555,8 +2253,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1564,8 +2266,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1573,16 +2279,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -1590,8 +2304,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1604,27 +2322,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1639,32 +2372,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1677,8 +2426,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -1690,8 +2443,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -1703,8 +2460,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1712,8 +2473,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1721,12 +2486,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -1737,17 +2510,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -1757,8 +2537,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP POST operation.
@@ -1779,16 +2560,49 @@ class FastAPI(Starlette):
return {"message": "Item created"}
```
"""
- pass
+ return self.router.post(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def delete(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1817,8 +2631,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1826,8 +2644,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1835,16 +2657,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -1852,8 +2682,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1866,27 +2700,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1901,32 +2750,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1939,8 +2804,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -1952,8 +2821,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -1965,8 +2838,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -1974,8 +2851,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -1983,12 +2864,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -1999,17 +2888,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -2019,8 +2915,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP DELETE operation.
@@ -2036,16 +2933,49 @@ class FastAPI(Starlette):
return {"message": "Item deleted"}
```
"""
- pass
+ return self.router.delete(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def options(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -2074,8 +3004,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -2083,8 +3017,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -2092,16 +3030,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -2109,8 +3055,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -2123,27 +3073,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -2158,32 +3123,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -2196,8 +3177,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -2209,8 +3194,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -2222,8 +3211,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -2231,8 +3224,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -2240,12 +3237,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -2256,17 +3261,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -2276,8 +3288,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP OPTIONS operation.
@@ -2293,16 +3306,49 @@ class FastAPI(Starlette):
return {"additions": ["Aji", "Guacamole"]}
```
"""
- pass
+ return self.router.options(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def head(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -2331,8 +3377,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -2340,8 +3390,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -2349,16 +3403,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -2366,8 +3428,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -2380,27 +3446,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -2415,32 +3496,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -2453,8 +3550,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -2466,8 +3567,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -2479,8 +3584,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -2488,8 +3597,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -2497,12 +3610,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -2513,17 +3634,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -2533,8 +3661,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP HEAD operation.
@@ -2550,16 +3679,49 @@ class FastAPI(Starlette):
response.headers["X-Cat-Dog"] = "Alone in the world"
```
"""
- pass
+ return self.router.head(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def patch(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -2588,8 +3750,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -2597,8 +3763,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -2606,16 +3776,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -2623,8 +3801,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -2637,27 +3819,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -2672,32 +3869,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -2710,8 +3923,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -2723,8 +3940,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -2736,8 +3957,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -2745,8 +3970,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -2754,12 +3983,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -2770,17 +4007,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -2790,8 +4034,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP PATCH operation.
@@ -2812,16 +4057,49 @@ class FastAPI(Starlette):
return {"message": "Item updated in place"}
```
"""
- pass
+ return self.router.patch(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
- def trace(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -2850,8 +4128,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -2859,8 +4141,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -2868,16 +4154,24 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[Depends]], Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to the
*path operation*.
Read more about it in the
[FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
"""
- )]=None, summary: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = 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`).
@@ -2885,8 +4179,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -2899,27 +4197,42 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -2934,32 +4247,48 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -2972,8 +4301,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`
@@ -2985,8 +4318,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -2998,8 +4335,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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`).
@@ -3007,8 +4348,12 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = 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.
@@ -3016,12 +4361,20 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -3032,17 +4385,24 @@ class FastAPI(Starlette):
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(
- """
+ ),
+ ] = None,
+ openapi_extra: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Extra metadata to be included in the OpenAPI schema for this *path
operation*.
Read more about it in the
[FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
"""
- )]=None, generate_unique_id_function: Annotated[Callable[[routing.
- APIRoute], str], Doc(
- """
+ ),
+ ] = None,
+ generate_unique_id_function: Annotated[
+ Callable[[routing.APIRoute], str],
+ Doc(
+ """
Customize the function used to generate unique IDs for the *path
operations* shown in the generated OpenAPI.
@@ -3052,8 +4412,9 @@ class FastAPI(Starlette):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP TRACE operation.
@@ -3069,7 +4430,40 @@ class FastAPI(Starlette):
return None
```
"""
- pass
+ return self.router.trace(
+ path,
+ response_model=response_model,
+ status_code=status_code,
+ tags=tags,
+ dependencies=dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=responses,
+ deprecated=deprecated,
+ operation_id=operation_id,
+ response_model_include=response_model_include,
+ response_model_exclude=response_model_exclude,
+ response_model_by_alias=response_model_by_alias,
+ response_model_exclude_unset=response_model_exclude_unset,
+ response_model_exclude_defaults=response_model_exclude_defaults,
+ response_model_exclude_none=response_model_exclude_none,
+ include_in_schema=include_in_schema,
+ response_class=response_class,
+ name=name,
+ callbacks=callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=generate_unique_id_function,
+ )
+
+ def websocket_route(
+ self, path: str, name: Union[str, None] = None
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.router.add_websocket_route(path, func, name=name)
+ return func
+
+ return decorator
@deprecated(
"""
@@ -3078,12 +4472,18 @@ class FastAPI(Starlette):
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(
- """
+ )
+ def on_event(
+ self,
+ event_type: Annotated[
+ str,
+ Doc(
+ """
The type of event. `startup` or `shutdown`.
"""
- )]) ->Callable[[DecoratedCallable], DecoratedCallable]:
+ ),
+ ],
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add an event handler for the application.
@@ -3092,13 +4492,19 @@ class FastAPI(Starlette):
Read more about it in the
[FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated).
"""
- pass
+ return self.router.on_event(event_type)
- def middleware(self, middleware_type: Annotated[str, Doc(
- """
+ def middleware(
+ self,
+ middleware_type: Annotated[
+ str,
+ Doc(
+ """
The type of middleware. Currently only supports `http`.
"""
- )]) ->Callable[[DecoratedCallable], DecoratedCallable]:
+ ),
+ ],
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a middleware to the application.
@@ -3124,14 +4530,24 @@ class FastAPI(Starlette):
return response
```
"""
- pass
- def exception_handler(self, exc_class_or_status_code: Annotated[Union[
- int, Type[Exception]], Doc(
- """
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_middleware(BaseHTTPMiddleware, dispatch=func)
+ return func
+
+ return decorator
+
+ def exception_handler(
+ self,
+ exc_class_or_status_code: Annotated[
+ Union[int, Type[Exception]],
+ Doc(
+ """
The Exception class this would handle, or a status code.
"""
- )]) ->Callable[[DecoratedCallable], DecoratedCallable]:
+ ),
+ ],
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add an exception handler to the app.
@@ -3161,4 +4577,9 @@ class FastAPI(Starlette):
)
```
"""
- pass
+
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_exception_handler(exc_class_or_status_code, func)
+ return func
+
+ return decorator
diff --git a/fastapi/background.py b/fastapi/background.py
index 368be9bc..203578a4 100644
--- a/fastapi/background.py
+++ b/fastapi/background.py
@@ -1,7 +1,9 @@
from typing import Any, Callable
+
from starlette.background import BackgroundTasks as StarletteBackgroundTasks
from typing_extensions import Annotated, Doc, ParamSpec
-P = ParamSpec('P')
+
+P = ParamSpec("P")
class BackgroundTasks(StarletteBackgroundTasks):
@@ -33,17 +35,25 @@ class BackgroundTasks(StarletteBackgroundTasks):
```
"""
- def add_task(self, func: Annotated[Callable[P, Any], Doc(
- """
+ def add_task(
+ self,
+ func: Annotated[
+ Callable[P, Any],
+ Doc(
+ """
The function to call after the response is sent.
It can be a regular `def` function or an `async def` function.
"""
- )], *args: P.args, **kwargs: P.kwargs) ->None:
+ ),
+ ],
+ *args: P.args,
+ **kwargs: P.kwargs,
+ ) -> None:
"""
Add a function to be called in the background after the response is sent.
Read more about it in the
[FastAPI docs for Background Tasks](https://fastapi.tiangolo.com/tutorial/background-tasks/).
"""
- pass
+ return super().add_task(func, *args, **kwargs)
diff --git a/fastapi/cli.py b/fastapi/cli.py
index 1bd91d5d..8d3301e9 100644
--- a/fastapi/cli.py
+++ b/fastapi/cli.py
@@ -1,4 +1,13 @@
try:
from fastapi_cli.cli import main as cli_main
-except ImportError:
- cli_main = None
+
+except ImportError: # pragma: no cover
+ cli_main = None # type: ignore
+
+
+def main() -> None:
+ if not cli_main: # type: ignore[truthy-function]
+ message = 'To use the fastapi command, please install "fastapi[standard]":\n\n\tpip install "fastapi[standard]"\n'
+ print(message)
+ raise RuntimeError(message) # noqa: B904
+ cli_main()
diff --git a/fastapi/concurrency.py b/fastapi/concurrency.py
index 0fabc8f3..894bd3ed 100644
--- a/fastapi/concurrency.py
+++ b/fastapi/concurrency.py
@@ -1,8 +1,39 @@
from contextlib import asynccontextmanager as asynccontextmanager
from typing import AsyncGenerator, ContextManager, TypeVar
+
import anyio
from anyio import CapacityLimiter
-from starlette.concurrency import iterate_in_threadpool as iterate_in_threadpool
-from starlette.concurrency import run_in_threadpool as run_in_threadpool
-from starlette.concurrency import run_until_first_complete as run_until_first_complete
-_T = TypeVar('_T')
+from starlette.concurrency import iterate_in_threadpool as iterate_in_threadpool # noqa
+from starlette.concurrency import run_in_threadpool as run_in_threadpool # noqa
+from starlette.concurrency import ( # noqa
+ run_until_first_complete as run_until_first_complete,
+)
+
+_T = TypeVar("_T")
+
+
+@asynccontextmanager
+async def contextmanager_in_threadpool(
+ cm: ContextManager[_T],
+) -> AsyncGenerator[_T, None]:
+ # blocking __exit__ from running waiting on a free thread
+ # can create race conditions/deadlocks if the context manager itself
+ # has its own internal pool (e.g. a database connection pool)
+ # to avoid this we let __exit__ run without a capacity limit
+ # since we're creating a new limiter for each call, any non-zero limit
+ # works (1 is arbitrary)
+ exit_limiter = CapacityLimiter(1)
+ try:
+ yield await run_in_threadpool(cm.__enter__)
+ except Exception as e:
+ ok = bool(
+ await anyio.to_thread.run_sync(
+ cm.__exit__, type(e), e, None, limiter=exit_limiter
+ )
+ )
+ if not ok:
+ raise e
+ else:
+ await anyio.to_thread.run_sync(
+ cm.__exit__, None, None, None, limiter=exit_limiter
+ )
diff --git a/fastapi/datastructures.py b/fastapi/datastructures.py
index e6043019..cf8406b0 100644
--- a/fastapi/datastructures.py
+++ b/fastapi/datastructures.py
@@ -1,11 +1,28 @@
-from typing import Any, BinaryIO, Callable, Dict, Iterable, Optional, Type, TypeVar, cast
-from fastapi._compat import PYDANTIC_V2, CoreSchema, GetJsonSchemaHandler, JsonSchemaValue, with_info_plain_validator_function
-from starlette.datastructures import URL as URL
-from starlette.datastructures import Address as Address
-from starlette.datastructures import FormData as FormData
-from starlette.datastructures import Headers as Headers
-from starlette.datastructures import QueryParams as QueryParams
-from starlette.datastructures import State as State
+from typing import (
+ Any,
+ BinaryIO,
+ Callable,
+ Dict,
+ Iterable,
+ Optional,
+ Type,
+ TypeVar,
+ cast,
+)
+
+from fastapi._compat import (
+ PYDANTIC_V2,
+ CoreSchema,
+ GetJsonSchemaHandler,
+ JsonSchemaValue,
+ with_info_plain_validator_function,
+)
+from starlette.datastructures import URL as URL # noqa: F401
+from starlette.datastructures import Address as Address # noqa: F401
+from starlette.datastructures import FormData as FormData # noqa: F401
+from starlette.datastructures import Headers as Headers # noqa: F401
+from starlette.datastructures import QueryParams as QueryParams # noqa: F401
+from starlette.datastructures import State as State # noqa: F401
from starlette.datastructures import UploadFile as StarletteUploadFile
from typing_extensions import Annotated, Doc
@@ -43,19 +60,29 @@ class UploadFile(StarletteUploadFile):
return {"filename": file.filename}
```
"""
- file: Annotated[BinaryIO, Doc(
- 'The standard Python file object (non-async).')]
- filename: Annotated[Optional[str], Doc('The original file name.')]
- size: Annotated[Optional[int], Doc('The size of the file in bytes.')]
- headers: Annotated[Headers, Doc('The headers of the request.')]
- content_type: Annotated[Optional[str], Doc(
- 'The content type of the request, from the headers.')]
-
- async def write(self, data: Annotated[bytes, Doc(
- """
+
+ file: Annotated[
+ BinaryIO,
+ Doc("The standard Python file object (non-async)."),
+ ]
+ filename: Annotated[Optional[str], Doc("The original file name.")]
+ size: Annotated[Optional[int], Doc("The size of the file in bytes.")]
+ headers: Annotated[Headers, Doc("The headers of the request.")]
+ content_type: Annotated[
+ Optional[str], Doc("The content type of the request, from the headers.")
+ ]
+
+ async def write(
+ self,
+ data: Annotated[
+ bytes,
+ Doc(
+ """
The bytes to write to the file.
"""
- )]) ->None:
+ ),
+ ],
+ ) -> None:
"""
Write some bytes to the file.
@@ -63,25 +90,37 @@ class UploadFile(StarletteUploadFile):
To be awaitable, compatible with async, this is run in threadpool.
"""
- pass
+ return await super().write(data)
- async def read(self, size: Annotated[int, Doc(
- """
+ async def read(
+ self,
+ size: Annotated[
+ int,
+ Doc(
+ """
The number of bytes to read from the file.
"""
- )]=-1) ->bytes:
+ ),
+ ] = -1,
+ ) -> bytes:
"""
Read some bytes from the file.
To be awaitable, compatible with async, this is run in threadpool.
"""
- pass
+ return await super().read(size)
- async def seek(self, offset: Annotated[int, Doc(
- """
+ async def seek(
+ self,
+ offset: Annotated[
+ int,
+ Doc(
+ """
The position in bytes to seek to in the file.
"""
- )]) ->None:
+ ),
+ ],
+ ) -> None:
"""
Move to a position in the file.
@@ -89,34 +128,48 @@ class UploadFile(StarletteUploadFile):
To be awaitable, compatible with async, this is run in threadpool.
"""
- pass
+ return await super().seek(offset)
- async def close(self) ->None:
+ async def close(self) -> None:
"""
Close the file.
To be awaitable, compatible with async, this is run in threadpool.
"""
- pass
+ return await super().close()
@classmethod
- def __get_validators__(cls: Type['UploadFile']) ->Iterable[Callable[...,
- Any]]:
+ def __get_validators__(cls: Type["UploadFile"]) -> Iterable[Callable[..., Any]]:
yield cls.validate
+
+ @classmethod
+ def validate(cls: Type["UploadFile"], v: Any) -> Any:
+ if not isinstance(v, StarletteUploadFile):
+ raise ValueError(f"Expected UploadFile, received: {type(v)}")
+ return v
+
+ @classmethod
+ def _validate(cls, __input_value: Any, _: Any) -> "UploadFile":
+ if not isinstance(__input_value, StarletteUploadFile):
+ raise ValueError(f"Expected UploadFile, received: {type(__input_value)}")
+ return cast(UploadFile, __input_value)
+
if not PYDANTIC_V2:
@classmethod
- def __modify_schema__(cls, field_schema: Dict[str, Any]) ->None:
- field_schema.update({'type': 'string', 'format': 'binary'})
+ def __modify_schema__(cls, field_schema: Dict[str, Any]) -> None:
+ field_schema.update({"type": "string", "format": "binary"})
@classmethod
- def __get_pydantic_json_schema__(cls, core_schema: CoreSchema, handler:
- GetJsonSchemaHandler) ->JsonSchemaValue:
- return {'type': 'string', 'format': 'binary'}
+ def __get_pydantic_json_schema__(
+ cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+ ) -> JsonSchemaValue:
+ return {"type": "string", "format": "binary"}
@classmethod
- def __get_pydantic_core_schema__(cls, source: Type[Any], handler:
- Callable[[Any], CoreSchema]) ->CoreSchema:
+ def __get_pydantic_core_schema__(
+ cls, source: Type[Any], handler: Callable[[Any], CoreSchema]
+ ) -> CoreSchema:
return with_info_plain_validator_function(cls._validate)
@@ -131,21 +184,21 @@ class DefaultPlaceholder:
def __init__(self, value: Any):
self.value = value
- def __bool__(self) ->bool:
+ def __bool__(self) -> bool:
return bool(self.value)
- def __eq__(self, o: object) ->bool:
+ def __eq__(self, o: object) -> bool:
return isinstance(o, DefaultPlaceholder) and o.value == self.value
-DefaultType = TypeVar('DefaultType')
+DefaultType = TypeVar("DefaultType")
-def Default(value: DefaultType) ->DefaultType:
+def Default(value: DefaultType) -> DefaultType:
"""
You shouldn't use this function directly.
It's used internally to recognize when a default value has been overwritten, even
if the overridden default value was truthy.
"""
- pass
+ return DefaultPlaceholder(value) # type: ignore
diff --git a/fastapi/dependencies/models.py b/fastapi/dependencies/models.py
index 4e5ecdae..61ef0063 100644
--- a/fastapi/dependencies/models.py
+++ b/fastapi/dependencies/models.py
@@ -1,31 +1,40 @@
from typing import Any, Callable, List, Optional, Sequence
+
from fastapi._compat import ModelField
from fastapi.security.base import SecurityBase
class SecurityRequirement:
-
- def __init__(self, security_scheme: SecurityBase, scopes: Optional[
- Sequence[str]]=None):
+ def __init__(
+ self, security_scheme: SecurityBase, scopes: Optional[Sequence[str]] = None
+ ):
self.security_scheme = security_scheme
self.scopes = scopes
class Dependant:
-
- def __init__(self, *, path_params: Optional[List[ModelField]]=None,
- query_params: Optional[List[ModelField]]=None, header_params:
- Optional[List[ModelField]]=None, cookie_params: Optional[List[
- ModelField]]=None, body_params: Optional[List[ModelField]]=None,
- dependencies: Optional[List['Dependant']]=None, security_schemes:
- Optional[List[SecurityRequirement]]=None, name: Optional[str]=None,
- call: Optional[Callable[..., Any]]=None, request_param_name:
- Optional[str]=None, websocket_param_name: Optional[str]=None,
- http_connection_param_name: Optional[str]=None, response_param_name:
- Optional[str]=None, background_tasks_param_name: Optional[str]=None,
- security_scopes_param_name: Optional[str]=None, security_scopes:
- Optional[List[str]]=None, use_cache: bool=True, path: Optional[str]
- =None) ->None:
+ def __init__(
+ self,
+ *,
+ path_params: Optional[List[ModelField]] = None,
+ query_params: Optional[List[ModelField]] = None,
+ header_params: Optional[List[ModelField]] = None,
+ cookie_params: Optional[List[ModelField]] = None,
+ body_params: Optional[List[ModelField]] = None,
+ dependencies: Optional[List["Dependant"]] = None,
+ security_schemes: Optional[List[SecurityRequirement]] = None,
+ name: Optional[str] = None,
+ call: Optional[Callable[..., Any]] = None,
+ request_param_name: Optional[str] = None,
+ websocket_param_name: Optional[str] = None,
+ http_connection_param_name: Optional[str] = None,
+ response_param_name: Optional[str] = None,
+ background_tasks_param_name: Optional[str] = None,
+ security_scopes_param_name: Optional[str] = None,
+ security_scopes: Optional[List[str]] = None,
+ use_cache: bool = True,
+ path: Optional[str] = None,
+ ) -> None:
self.path_params = path_params or []
self.query_params = query_params or []
self.header_params = header_params or []
@@ -43,6 +52,7 @@ class Dependant:
self.name = name
self.call = call
self.use_cache = use_cache
+ # Store the path to be able to re-generate a dependable from it in overrides
self.path = path
- self.cache_key = self.call, tuple(sorted(set(self.security_scopes or
- [])))
+ # Save the cache key at creation to optimize performance
+ self.cache_key = (self.call, tuple(sorted(set(self.security_scopes or []))))
diff --git a/fastapi/dependencies/utils.py b/fastapi/dependencies/utils.py
index 3c6ab88a..4f984177 100644
--- a/fastapi/dependencies/utils.py
+++ b/fastapi/dependencies/utils.py
@@ -1,12 +1,54 @@
import inspect
from contextlib import AsyncExitStack, contextmanager
from copy import copy, deepcopy
-from typing import Any, Callable, Coroutine, Dict, ForwardRef, List, Mapping, Optional, Sequence, Tuple, Type, Union, cast
+from typing import (
+ Any,
+ Callable,
+ Coroutine,
+ Dict,
+ ForwardRef,
+ List,
+ Mapping,
+ Optional,
+ Sequence,
+ Tuple,
+ Type,
+ Union,
+ cast,
+)
+
import anyio
from fastapi import params
-from fastapi._compat import PYDANTIC_V2, ErrorWrapper, ModelField, Required, Undefined, _regenerate_error_with_loc, copy_field_info, create_body_model, evaluate_forwardref, field_annotation_is_scalar, get_annotation_from_field_info, get_missing_field_error, is_bytes_field, is_bytes_sequence_field, is_scalar_field, is_scalar_sequence_field, is_sequence_field, is_uploadfile_or_nonable_uploadfile_annotation, is_uploadfile_sequence_annotation, lenient_issubclass, sequence_types, serialize_sequence_value, value_is_sequence
+from fastapi._compat import (
+ PYDANTIC_V2,
+ ErrorWrapper,
+ ModelField,
+ Required,
+ Undefined,
+ _regenerate_error_with_loc,
+ copy_field_info,
+ create_body_model,
+ evaluate_forwardref,
+ field_annotation_is_scalar,
+ get_annotation_from_field_info,
+ get_missing_field_error,
+ is_bytes_field,
+ is_bytes_sequence_field,
+ is_scalar_field,
+ is_scalar_sequence_field,
+ is_sequence_field,
+ is_uploadfile_or_nonable_uploadfile_annotation,
+ is_uploadfile_sequence_annotation,
+ lenient_issubclass,
+ sequence_types,
+ serialize_sequence_value,
+ value_is_sequence,
+)
from fastapi.background import BackgroundTasks
-from fastapi.concurrency import asynccontextmanager, contextmanager_in_threadpool
+from fastapi.concurrency import (
+ asynccontextmanager,
+ contextmanager_in_threadpool,
+)
from fastapi.dependencies.models import Dependant, SecurityRequirement
from fastapi.logger import logger
from fastapi.security.base import SecurityBase
@@ -21,18 +63,756 @@ from starlette.requests import HTTPConnection, Request
from starlette.responses import Response
from starlette.websockets import WebSocket
from typing_extensions import Annotated, get_args, get_origin
-multipart_not_installed_error = """Form data requires "python-multipart" to be installed.
-You can install "python-multipart" with:
-pip install python-multipart
-"""
-multipart_incorrect_install_error = """Form data requires "python-multipart" to be installed. It seems you installed "multipart" instead.
-You can remove "multipart" with:
+multipart_not_installed_error = (
+ 'Form data requires "python-multipart" to be installed. \n'
+ 'You can install "python-multipart" with: \n\n'
+ "pip install python-multipart\n"
+)
+multipart_incorrect_install_error = (
+ 'Form data requires "python-multipart" to be installed. '
+ 'It seems you installed "multipart" instead. \n'
+ 'You can remove "multipart" with: \n\n'
+ "pip uninstall multipart\n\n"
+ 'And then install "python-multipart" with: \n\n'
+ "pip install python-multipart\n"
+)
+
+
+def check_file_field(field: ModelField) -> None:
+ field_info = field.field_info
+ if isinstance(field_info, params.Form):
+ try:
+ # __version__ is available in both multiparts, and can be mocked
+ from multipart import __version__ # type: ignore
+
+ assert __version__
+ try:
+ # parse_options_header is only available in the right multipart
+ from multipart.multipart import parse_options_header # type: ignore
+
+ assert parse_options_header
+ except ImportError:
+ logger.error(multipart_incorrect_install_error)
+ raise RuntimeError(multipart_incorrect_install_error) from None
+ except ImportError:
+ logger.error(multipart_not_installed_error)
+ raise RuntimeError(multipart_not_installed_error) from None
+
+
+def get_param_sub_dependant(
+ *,
+ param_name: str,
+ depends: params.Depends,
+ path: str,
+ security_scopes: Optional[List[str]] = None,
+) -> Dependant:
+ assert depends.dependency
+ return get_sub_dependant(
+ depends=depends,
+ dependency=depends.dependency,
+ path=path,
+ name=param_name,
+ security_scopes=security_scopes,
+ )
+
-pip uninstall multipart
+def get_parameterless_sub_dependant(*, depends: params.Depends, path: str) -> Dependant:
+ assert callable(
+ depends.dependency
+ ), "A parameter-less dependency must have a callable dependency"
+ return get_sub_dependant(depends=depends, dependency=depends.dependency, path=path)
+
+
+def get_sub_dependant(
+ *,
+ depends: params.Depends,
+ dependency: Callable[..., Any],
+ path: str,
+ name: Optional[str] = None,
+ security_scopes: Optional[List[str]] = None,
+) -> Dependant:
+ security_requirement = None
+ security_scopes = security_scopes or []
+ if isinstance(depends, params.Security):
+ dependency_scopes = depends.scopes
+ security_scopes.extend(dependency_scopes)
+ if isinstance(dependency, SecurityBase):
+ use_scopes: List[str] = []
+ if isinstance(dependency, (OAuth2, OpenIdConnect)):
+ use_scopes = security_scopes
+ security_requirement = SecurityRequirement(
+ security_scheme=dependency, scopes=use_scopes
+ )
+ sub_dependant = get_dependant(
+ path=path,
+ call=dependency,
+ name=name,
+ security_scopes=security_scopes,
+ use_cache=depends.use_cache,
+ )
+ if security_requirement:
+ sub_dependant.security_requirements.append(security_requirement)
+ return sub_dependant
-And then install "python-multipart" with:
-pip install python-multipart
-"""
CacheKey = Tuple[Optional[Callable[..., Any]], Tuple[str, ...]]
+
+
+def get_flat_dependant(
+ dependant: Dependant,
+ *,
+ skip_repeats: bool = False,
+ visited: Optional[List[CacheKey]] = None,
+) -> Dependant:
+ if visited is None:
+ visited = []
+ visited.append(dependant.cache_key)
+
+ flat_dependant = Dependant(
+ path_params=dependant.path_params.copy(),
+ query_params=dependant.query_params.copy(),
+ header_params=dependant.header_params.copy(),
+ cookie_params=dependant.cookie_params.copy(),
+ body_params=dependant.body_params.copy(),
+ security_schemes=dependant.security_requirements.copy(),
+ use_cache=dependant.use_cache,
+ path=dependant.path,
+ )
+ for sub_dependant in dependant.dependencies:
+ if skip_repeats and sub_dependant.cache_key in visited:
+ continue
+ flat_sub = get_flat_dependant(
+ sub_dependant, skip_repeats=skip_repeats, visited=visited
+ )
+ flat_dependant.path_params.extend(flat_sub.path_params)
+ flat_dependant.query_params.extend(flat_sub.query_params)
+ flat_dependant.header_params.extend(flat_sub.header_params)
+ flat_dependant.cookie_params.extend(flat_sub.cookie_params)
+ flat_dependant.body_params.extend(flat_sub.body_params)
+ flat_dependant.security_requirements.extend(flat_sub.security_requirements)
+ return flat_dependant
+
+
+def get_flat_params(dependant: Dependant) -> List[ModelField]:
+ flat_dependant = get_flat_dependant(dependant, skip_repeats=True)
+ return (
+ flat_dependant.path_params
+ + flat_dependant.query_params
+ + flat_dependant.header_params
+ + flat_dependant.cookie_params
+ )
+
+
+def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
+ signature = inspect.signature(call)
+ globalns = getattr(call, "__globals__", {})
+ typed_params = [
+ inspect.Parameter(
+ name=param.name,
+ kind=param.kind,
+ default=param.default,
+ annotation=get_typed_annotation(param.annotation, globalns),
+ )
+ for param in signature.parameters.values()
+ ]
+ typed_signature = inspect.Signature(typed_params)
+ return typed_signature
+
+
+def get_typed_annotation(annotation: Any, globalns: Dict[str, Any]) -> Any:
+ if isinstance(annotation, str):
+ annotation = ForwardRef(annotation)
+ annotation = evaluate_forwardref(annotation, globalns, globalns)
+ return annotation
+
+
+def get_typed_return_annotation(call: Callable[..., Any]) -> Any:
+ signature = inspect.signature(call)
+ annotation = signature.return_annotation
+
+ if annotation is inspect.Signature.empty:
+ return None
+
+ globalns = getattr(call, "__globals__", {})
+ return get_typed_annotation(annotation, globalns)
+
+
+def get_dependant(
+ *,
+ path: str,
+ call: Callable[..., Any],
+ name: Optional[str] = None,
+ security_scopes: Optional[List[str]] = None,
+ use_cache: bool = True,
+) -> Dependant:
+ path_param_names = get_path_param_names(path)
+ endpoint_signature = get_typed_signature(call)
+ signature_params = endpoint_signature.parameters
+ dependant = Dependant(
+ call=call,
+ name=name,
+ path=path,
+ security_scopes=security_scopes,
+ use_cache=use_cache,
+ )
+ for param_name, param in signature_params.items():
+ is_path_param = param_name in path_param_names
+ type_annotation, depends, param_field = analyze_param(
+ param_name=param_name,
+ annotation=param.annotation,
+ value=param.default,
+ is_path_param=is_path_param,
+ )
+ if depends is not None:
+ sub_dependant = get_param_sub_dependant(
+ param_name=param_name,
+ depends=depends,
+ path=path,
+ security_scopes=security_scopes,
+ )
+ dependant.dependencies.append(sub_dependant)
+ continue
+ if add_non_field_param_to_dependency(
+ param_name=param_name,
+ type_annotation=type_annotation,
+ dependant=dependant,
+ ):
+ assert (
+ param_field is None
+ ), f"Cannot specify multiple FastAPI annotations for {param_name!r}"
+ continue
+ assert param_field is not None
+ if is_body_param(param_field=param_field, is_path_param=is_path_param):
+ dependant.body_params.append(param_field)
+ else:
+ add_param_to_fields(field=param_field, dependant=dependant)
+ return dependant
+
+
+def add_non_field_param_to_dependency(
+ *, param_name: str, type_annotation: Any, dependant: Dependant
+) -> Optional[bool]:
+ if lenient_issubclass(type_annotation, Request):
+ dependant.request_param_name = param_name
+ return True
+ elif lenient_issubclass(type_annotation, WebSocket):
+ dependant.websocket_param_name = param_name
+ return True
+ elif lenient_issubclass(type_annotation, HTTPConnection):
+ dependant.http_connection_param_name = param_name
+ return True
+ elif lenient_issubclass(type_annotation, Response):
+ dependant.response_param_name = param_name
+ return True
+ elif lenient_issubclass(type_annotation, StarletteBackgroundTasks):
+ dependant.background_tasks_param_name = param_name
+ return True
+ elif lenient_issubclass(type_annotation, SecurityScopes):
+ dependant.security_scopes_param_name = param_name
+ return True
+ return None
+
+
+def analyze_param(
+ *,
+ param_name: str,
+ annotation: Any,
+ value: Any,
+ is_path_param: bool,
+) -> Tuple[Any, Optional[params.Depends], Optional[ModelField]]:
+ field_info = None
+ depends = None
+ type_annotation: Any = Any
+ use_annotation: Any = Any
+ if annotation is not inspect.Signature.empty:
+ use_annotation = annotation
+ type_annotation = annotation
+ if get_origin(use_annotation) is Annotated:
+ annotated_args = get_args(annotation)
+ type_annotation = annotated_args[0]
+ fastapi_annotations = [
+ arg
+ for arg in annotated_args[1:]
+ if isinstance(arg, (FieldInfo, params.Depends))
+ ]
+ fastapi_specific_annotations = [
+ arg
+ for arg in fastapi_annotations
+ if isinstance(arg, (params.Param, params.Body, params.Depends))
+ ]
+ if fastapi_specific_annotations:
+ fastapi_annotation: Union[
+ FieldInfo, params.Depends, None
+ ] = fastapi_specific_annotations[-1]
+ else:
+ fastapi_annotation = None
+ if isinstance(fastapi_annotation, FieldInfo):
+ # Copy `field_info` because we mutate `field_info.default` below.
+ field_info = copy_field_info(
+ field_info=fastapi_annotation, annotation=use_annotation
+ )
+ assert field_info.default is Undefined or field_info.default is Required, (
+ f"`{field_info.__class__.__name__}` default value cannot be set in"
+ f" `Annotated` for {param_name!r}. Set the default value with `=` instead."
+ )
+ if value is not inspect.Signature.empty:
+ assert not is_path_param, "Path parameters cannot have default values"
+ field_info.default = value
+ else:
+ field_info.default = Required
+ elif isinstance(fastapi_annotation, params.Depends):
+ depends = fastapi_annotation
+
+ if isinstance(value, params.Depends):
+ assert depends is None, (
+ "Cannot specify `Depends` in `Annotated` and default value"
+ f" together for {param_name!r}"
+ )
+ assert field_info is None, (
+ "Cannot specify a FastAPI annotation in `Annotated` and `Depends` as a"
+ f" default value together for {param_name!r}"
+ )
+ depends = value
+ elif isinstance(value, FieldInfo):
+ assert field_info is None, (
+ "Cannot specify FastAPI annotations in `Annotated` and default value"
+ f" together for {param_name!r}"
+ )
+ field_info = value
+ if PYDANTIC_V2:
+ field_info.annotation = type_annotation
+
+ if depends is not None and depends.dependency is None:
+ # Copy `depends` before mutating it
+ depends = copy(depends)
+ depends.dependency = type_annotation
+
+ if lenient_issubclass(
+ type_annotation,
+ (
+ Request,
+ WebSocket,
+ HTTPConnection,
+ Response,
+ StarletteBackgroundTasks,
+ SecurityScopes,
+ ),
+ ):
+ assert depends is None, f"Cannot specify `Depends` for type {type_annotation!r}"
+ assert (
+ field_info is None
+ ), f"Cannot specify FastAPI annotation for type {type_annotation!r}"
+ elif field_info is None and depends is None:
+ default_value = value if value is not inspect.Signature.empty else Required
+ if is_path_param:
+ # We might check here that `default_value is Required`, but the fact is that the same
+ # parameter might sometimes be a path parameter and sometimes not. See
+ # `tests/test_infer_param_optionality.py` for an example.
+ field_info = params.Path(annotation=use_annotation)
+ elif is_uploadfile_or_nonable_uploadfile_annotation(
+ type_annotation
+ ) or is_uploadfile_sequence_annotation(type_annotation):
+ field_info = params.File(annotation=use_annotation, default=default_value)
+ elif not field_annotation_is_scalar(annotation=type_annotation):
+ field_info = params.Body(annotation=use_annotation, default=default_value)
+ else:
+ field_info = params.Query(annotation=use_annotation, default=default_value)
+
+ field = None
+ if field_info is not None:
+ if is_path_param:
+ assert isinstance(field_info, params.Path), (
+ f"Cannot use `{field_info.__class__.__name__}` for path param"
+ f" {param_name!r}"
+ )
+ elif (
+ isinstance(field_info, params.Param)
+ and getattr(field_info, "in_", None) is None
+ ):
+ field_info.in_ = params.ParamTypes.query
+ use_annotation_from_field_info = get_annotation_from_field_info(
+ use_annotation,
+ field_info,
+ param_name,
+ )
+ if not field_info.alias and getattr(field_info, "convert_underscores", None):
+ alias = param_name.replace("_", "-")
+ else:
+ alias = field_info.alias or param_name
+ field_info.alias = alias
+ field = create_response_field(
+ name=param_name,
+ type_=use_annotation_from_field_info,
+ default=field_info.default,
+ alias=alias,
+ required=field_info.default in (Required, Undefined),
+ field_info=field_info,
+ )
+
+ return type_annotation, depends, field
+
+
+def is_body_param(*, param_field: ModelField, is_path_param: bool) -> bool:
+ if is_path_param:
+ assert is_scalar_field(
+ field=param_field
+ ), "Path params must be of one of the supported types"
+ return False
+ elif is_scalar_field(field=param_field):
+ return False
+ elif isinstance(
+ param_field.field_info, (params.Query, params.Header)
+ ) and is_scalar_sequence_field(param_field):
+ return False
+ else:
+ assert isinstance(
+ param_field.field_info, params.Body
+ ), f"Param: {param_field.name} can only be a request body, using Body()"
+ return True
+
+
+def add_param_to_fields(*, field: ModelField, dependant: Dependant) -> None:
+ field_info = field.field_info
+ field_info_in = getattr(field_info, "in_", None)
+ if field_info_in == params.ParamTypes.path:
+ dependant.path_params.append(field)
+ elif field_info_in == params.ParamTypes.query:
+ dependant.query_params.append(field)
+ elif field_info_in == params.ParamTypes.header:
+ dependant.header_params.append(field)
+ else:
+ assert (
+ field_info_in == params.ParamTypes.cookie
+ ), f"non-body parameters must be in path, query, header or cookie: {field.name}"
+ dependant.cookie_params.append(field)
+
+
+def is_coroutine_callable(call: Callable[..., Any]) -> bool:
+ if inspect.isroutine(call):
+ return inspect.iscoroutinefunction(call)
+ if inspect.isclass(call):
+ return False
+ dunder_call = getattr(call, "__call__", None) # noqa: B004
+ return inspect.iscoroutinefunction(dunder_call)
+
+
+def is_async_gen_callable(call: Callable[..., Any]) -> bool:
+ if inspect.isasyncgenfunction(call):
+ return True
+ dunder_call = getattr(call, "__call__", None) # noqa: B004
+ return inspect.isasyncgenfunction(dunder_call)
+
+
+def is_gen_callable(call: Callable[..., Any]) -> bool:
+ if inspect.isgeneratorfunction(call):
+ return True
+ dunder_call = getattr(call, "__call__", None) # noqa: B004
+ return inspect.isgeneratorfunction(dunder_call)
+
+
+async def solve_generator(
+ *, call: Callable[..., Any], stack: AsyncExitStack, sub_values: Dict[str, Any]
+) -> Any:
+ if is_gen_callable(call):
+ cm = contextmanager_in_threadpool(contextmanager(call)(**sub_values))
+ elif is_async_gen_callable(call):
+ cm = asynccontextmanager(call)(**sub_values)
+ return await stack.enter_async_context(cm)
+
+
+async def solve_dependencies(
+ *,
+ request: Union[Request, WebSocket],
+ dependant: Dependant,
+ body: Optional[Union[Dict[str, Any], FormData]] = None,
+ background_tasks: Optional[StarletteBackgroundTasks] = None,
+ response: Optional[Response] = None,
+ dependency_overrides_provider: Optional[Any] = None,
+ dependency_cache: Optional[Dict[Tuple[Callable[..., Any], Tuple[str]], Any]] = None,
+ async_exit_stack: AsyncExitStack,
+) -> Tuple[
+ Dict[str, Any],
+ List[Any],
+ Optional[StarletteBackgroundTasks],
+ Response,
+ Dict[Tuple[Callable[..., Any], Tuple[str]], Any],
+]:
+ values: Dict[str, Any] = {}
+ errors: List[Any] = []
+ if response is None:
+ response = Response()
+ del response.headers["content-length"]
+ response.status_code = None # type: ignore
+ dependency_cache = dependency_cache or {}
+ sub_dependant: Dependant
+ for sub_dependant in dependant.dependencies:
+ sub_dependant.call = cast(Callable[..., Any], sub_dependant.call)
+ sub_dependant.cache_key = cast(
+ Tuple[Callable[..., Any], Tuple[str]], sub_dependant.cache_key
+ )
+ call = sub_dependant.call
+ use_sub_dependant = sub_dependant
+ if (
+ dependency_overrides_provider
+ and dependency_overrides_provider.dependency_overrides
+ ):
+ original_call = sub_dependant.call
+ call = getattr(
+ dependency_overrides_provider, "dependency_overrides", {}
+ ).get(original_call, original_call)
+ use_path: str = sub_dependant.path # type: ignore
+ use_sub_dependant = get_dependant(
+ path=use_path,
+ call=call,
+ name=sub_dependant.name,
+ security_scopes=sub_dependant.security_scopes,
+ )
+
+ solved_result = await solve_dependencies(
+ request=request,
+ dependant=use_sub_dependant,
+ body=body,
+ background_tasks=background_tasks,
+ response=response,
+ dependency_overrides_provider=dependency_overrides_provider,
+ dependency_cache=dependency_cache,
+ async_exit_stack=async_exit_stack,
+ )
+ (
+ sub_values,
+ sub_errors,
+ background_tasks,
+ _, # the subdependency returns the same response we have
+ sub_dependency_cache,
+ ) = solved_result
+ dependency_cache.update(sub_dependency_cache)
+ if sub_errors:
+ errors.extend(sub_errors)
+ continue
+ if sub_dependant.use_cache and sub_dependant.cache_key in dependency_cache:
+ solved = dependency_cache[sub_dependant.cache_key]
+ elif is_gen_callable(call) or is_async_gen_callable(call):
+ solved = await solve_generator(
+ call=call, stack=async_exit_stack, sub_values=sub_values
+ )
+ elif is_coroutine_callable(call):
+ solved = await call(**sub_values)
+ else:
+ solved = await run_in_threadpool(call, **sub_values)
+ if sub_dependant.name is not None:
+ values[sub_dependant.name] = solved
+ if sub_dependant.cache_key not in dependency_cache:
+ dependency_cache[sub_dependant.cache_key] = solved
+ path_values, path_errors = request_params_to_args(
+ dependant.path_params, request.path_params
+ )
+ query_values, query_errors = request_params_to_args(
+ dependant.query_params, request.query_params
+ )
+ header_values, header_errors = request_params_to_args(
+ dependant.header_params, request.headers
+ )
+ cookie_values, cookie_errors = request_params_to_args(
+ dependant.cookie_params, request.cookies
+ )
+ values.update(path_values)
+ values.update(query_values)
+ values.update(header_values)
+ values.update(cookie_values)
+ errors += path_errors + query_errors + header_errors + cookie_errors
+ if dependant.body_params:
+ (
+ body_values,
+ body_errors,
+ ) = await request_body_to_args( # body_params checked above
+ required_params=dependant.body_params, received_body=body
+ )
+ values.update(body_values)
+ errors.extend(body_errors)
+ if dependant.http_connection_param_name:
+ values[dependant.http_connection_param_name] = request
+ if dependant.request_param_name and isinstance(request, Request):
+ values[dependant.request_param_name] = request
+ elif dependant.websocket_param_name and isinstance(request, WebSocket):
+ values[dependant.websocket_param_name] = request
+ if dependant.background_tasks_param_name:
+ if background_tasks is None:
+ background_tasks = BackgroundTasks()
+ values[dependant.background_tasks_param_name] = background_tasks
+ if dependant.response_param_name:
+ values[dependant.response_param_name] = response
+ if dependant.security_scopes_param_name:
+ values[dependant.security_scopes_param_name] = SecurityScopes(
+ scopes=dependant.security_scopes
+ )
+ return values, errors, background_tasks, response, dependency_cache
+
+
+def request_params_to_args(
+ required_params: Sequence[ModelField],
+ received_params: Union[Mapping[str, Any], QueryParams, Headers],
+) -> Tuple[Dict[str, Any], List[Any]]:
+ values = {}
+ errors = []
+ for field in required_params:
+ if is_scalar_sequence_field(field) and isinstance(
+ received_params, (QueryParams, Headers)
+ ):
+ value = received_params.getlist(field.alias) or field.default
+ else:
+ value = received_params.get(field.alias)
+ field_info = field.field_info
+ assert isinstance(
+ field_info, params.Param
+ ), "Params must be subclasses of Param"
+ loc = (field_info.in_.value, field.alias)
+ if value is None:
+ if field.required:
+ errors.append(get_missing_field_error(loc=loc))
+ else:
+ values[field.name] = deepcopy(field.default)
+ continue
+ v_, errors_ = field.validate(value, values, loc=loc)
+ if isinstance(errors_, ErrorWrapper):
+ errors.append(errors_)
+ elif isinstance(errors_, list):
+ new_errors = _regenerate_error_with_loc(errors=errors_, loc_prefix=())
+ errors.extend(new_errors)
+ else:
+ values[field.name] = v_
+ return values, errors
+
+
+async def request_body_to_args(
+ required_params: List[ModelField],
+ received_body: Optional[Union[Dict[str, Any], FormData]],
+) -> Tuple[Dict[str, Any], List[Dict[str, Any]]]:
+ values = {}
+ errors: List[Dict[str, Any]] = []
+ if required_params:
+ field = required_params[0]
+ field_info = field.field_info
+ embed = getattr(field_info, "embed", None)
+ field_alias_omitted = len(required_params) == 1 and not embed
+ if field_alias_omitted:
+ received_body = {field.alias: received_body}
+
+ for field in required_params:
+ loc: Tuple[str, ...]
+ if field_alias_omitted:
+ loc = ("body",)
+ else:
+ loc = ("body", field.alias)
+
+ value: Optional[Any] = None
+ if received_body is not None:
+ if (is_sequence_field(field)) and isinstance(received_body, FormData):
+ value = received_body.getlist(field.alias)
+ else:
+ try:
+ value = received_body.get(field.alias)
+ except AttributeError:
+ errors.append(get_missing_field_error(loc))
+ continue
+ if (
+ value is None
+ or (isinstance(field_info, params.Form) and value == "")
+ or (
+ isinstance(field_info, params.Form)
+ and is_sequence_field(field)
+ and len(value) == 0
+ )
+ ):
+ if field.required:
+ errors.append(get_missing_field_error(loc))
+ else:
+ values[field.name] = deepcopy(field.default)
+ continue
+ if (
+ isinstance(field_info, params.File)
+ and is_bytes_field(field)
+ and isinstance(value, UploadFile)
+ ):
+ value = await value.read()
+ elif (
+ is_bytes_sequence_field(field)
+ and isinstance(field_info, params.File)
+ and value_is_sequence(value)
+ ):
+ # For types
+ assert isinstance(value, sequence_types) # type: ignore[arg-type]
+ results: List[Union[bytes, str]] = []
+
+ async def process_fn(
+ fn: Callable[[], Coroutine[Any, Any, Any]],
+ ) -> None:
+ result = await fn()
+ results.append(result) # noqa: B023
+
+ async with anyio.create_task_group() as tg:
+ for sub_value in value:
+ tg.start_soon(process_fn, sub_value.read)
+ value = serialize_sequence_value(field=field, value=results)
+
+ v_, errors_ = field.validate(value, values, loc=loc)
+
+ if isinstance(errors_, list):
+ errors.extend(errors_)
+ elif errors_:
+ errors.append(errors_)
+ else:
+ values[field.name] = v_
+ return values, errors
+
+
+def get_body_field(*, dependant: Dependant, name: str) -> Optional[ModelField]:
+ flat_dependant = get_flat_dependant(dependant)
+ if not flat_dependant.body_params:
+ return None
+ first_param = flat_dependant.body_params[0]
+ field_info = first_param.field_info
+ embed = getattr(field_info, "embed", None)
+ body_param_names_set = {param.name for param in flat_dependant.body_params}
+ if len(body_param_names_set) == 1 and not embed:
+ check_file_field(first_param)
+ return first_param
+ # If one field requires to embed, all have to be embedded
+ # in case a sub-dependency is evaluated with a single unique body field
+ # That is combined (embedded) with other body fields
+ for param in flat_dependant.body_params:
+ setattr(param.field_info, "embed", True) # noqa: B010
+ model_name = "Body_" + name
+ BodyModel = create_body_model(
+ fields=flat_dependant.body_params, model_name=model_name
+ )
+ required = any(True for f in flat_dependant.body_params if f.required)
+ BodyFieldInfo_kwargs: Dict[str, Any] = {
+ "annotation": BodyModel,
+ "alias": "body",
+ }
+ if not required:
+ BodyFieldInfo_kwargs["default"] = None
+ if any(isinstance(f.field_info, params.File) for f in flat_dependant.body_params):
+ BodyFieldInfo: Type[params.Body] = params.File
+ elif any(isinstance(f.field_info, params.Form) for f in flat_dependant.body_params):
+ BodyFieldInfo = params.Form
+ else:
+ BodyFieldInfo = params.Body
+
+ body_param_media_types = [
+ f.field_info.media_type
+ for f in flat_dependant.body_params
+ if isinstance(f.field_info, params.Body)
+ ]
+ if len(set(body_param_media_types)) == 1:
+ BodyFieldInfo_kwargs["media_type"] = body_param_media_types[0]
+ final_field = create_response_field(
+ name="body",
+ type_=BodyModel,
+ required=required,
+ alias="body",
+ field_info=BodyFieldInfo(**BodyFieldInfo_kwargs),
+ )
+ check_file_field(final_field)
+ return final_field
diff --git a/fastapi/encoders.py b/fastapi/encoders.py
index 66986830..451ea076 100644
--- a/fastapi/encoders.py
+++ b/fastapi/encoders.py
@@ -3,22 +3,38 @@ import datetime
from collections import defaultdict, deque
from decimal import Decimal
from enum import Enum
-from ipaddress import IPv4Address, IPv4Interface, IPv4Network, IPv6Address, IPv6Interface, IPv6Network
+from ipaddress import (
+ IPv4Address,
+ IPv4Interface,
+ IPv4Network,
+ IPv6Address,
+ IPv6Interface,
+ IPv6Network,
+)
from pathlib import Path, PurePath
from re import Pattern
from types import GeneratorType
from typing import Any, Callable, Dict, List, Optional, Tuple, Type, Union
from uuid import UUID
+
from fastapi.types import IncEx
from pydantic import BaseModel
from pydantic.color import Color
from pydantic.networks import AnyUrl, NameEmail
from pydantic.types import SecretBytes, SecretStr
from typing_extensions import Annotated, Doc
+
from ._compat import PYDANTIC_V2, UndefinedType, Url, _model_dump
-def decimal_encoder(dec_value: Decimal) ->Union[int, float]:
+# Taken from Pydantic v1 as is
+def isoformat(o: Union[datetime.date, datetime.time]) -> str:
+ return o.isoformat()
+
+
+# Taken from Pydantic v1 as is
+# TODO: pv2 should this return strings instead?
+def decimal_encoder(dec_value: Decimal) -> Union[int, float]:
"""
Encodes a Decimal as int of there's no exponent, otherwise float
@@ -33,75 +49,146 @@ def decimal_encoder(dec_value: Decimal) ->Union[int, float]:
>>> decimal_encoder(Decimal("1"))
1
"""
- pass
-
-
-ENCODERS_BY_TYPE: Dict[Type[Any], Callable[[Any], Any]] = {bytes: lambda o:
- o.decode(), Color: str, datetime.date: isoformat, datetime.datetime:
- isoformat, datetime.time: isoformat, datetime.timedelta: lambda td: td.
- total_seconds(), Decimal: decimal_encoder, Enum: lambda o: o.value,
- frozenset: list, deque: list, GeneratorType: list, IPv4Address: str,
- IPv4Interface: str, IPv4Network: str, IPv6Address: str, IPv6Interface:
- str, IPv6Network: str, NameEmail: str, Path: str, Pattern: lambda o: o.
- pattern, SecretBytes: str, SecretStr: str, set: list, UUID: str, Url:
- str, AnyUrl: str}
+ if dec_value.as_tuple().exponent >= 0: # type: ignore[operator]
+ return int(dec_value)
+ else:
+ return float(dec_value)
+
+
+ENCODERS_BY_TYPE: Dict[Type[Any], Callable[[Any], Any]] = {
+ bytes: lambda o: o.decode(),
+ Color: str,
+ datetime.date: isoformat,
+ datetime.datetime: isoformat,
+ datetime.time: isoformat,
+ datetime.timedelta: lambda td: td.total_seconds(),
+ Decimal: decimal_encoder,
+ Enum: lambda o: o.value,
+ frozenset: list,
+ deque: list,
+ GeneratorType: list,
+ IPv4Address: str,
+ IPv4Interface: str,
+ IPv4Network: str,
+ IPv6Address: str,
+ IPv6Interface: str,
+ IPv6Network: str,
+ NameEmail: str,
+ Path: str,
+ Pattern: lambda o: o.pattern,
+ SecretBytes: str,
+ SecretStr: str,
+ set: list,
+ UUID: str,
+ Url: str,
+ AnyUrl: str,
+}
+
+
+def generate_encoders_by_class_tuples(
+ type_encoder_map: Dict[Any, Callable[[Any], Any]],
+) -> Dict[Callable[[Any], Any], Tuple[Any, ...]]:
+ encoders_by_class_tuples: Dict[Callable[[Any], Any], Tuple[Any, ...]] = defaultdict(
+ tuple
+ )
+ for type_, encoder in type_encoder_map.items():
+ encoders_by_class_tuples[encoder] += (type_,)
+ return encoders_by_class_tuples
+
+
encoders_by_class_tuples = generate_encoders_by_class_tuples(ENCODERS_BY_TYPE)
-def jsonable_encoder(obj: Annotated[Any, Doc(
- """
+def jsonable_encoder(
+ obj: Annotated[
+ Any,
+ Doc(
+ """
The input object to convert to JSON.
- """)],
- include: Annotated[Optional[IncEx], Doc(
- """
+ """
+ ),
+ ],
+ include: Annotated[
+ Optional[IncEx],
+ Doc(
+ """
Pydantic's `include` parameter, passed to Pydantic models to set the
fields to include.
"""
- )]=None, exclude: Annotated[Optional[IncEx], Doc(
- """
+ ),
+ ] = None,
+ exclude: Annotated[
+ Optional[IncEx],
+ Doc(
+ """
Pydantic's `exclude` parameter, passed to Pydantic models to set the
fields to exclude.
"""
- )]=None, by_alias: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ by_alias: Annotated[
+ bool,
+ Doc(
+ """
Pydantic's `by_alias` parameter, passed to Pydantic models to define if
the output should use the alias names (when provided) or the Python
attribute names. In an API, if you set an alias, it's probably because you
want to use it in the result, so you probably want to leave this set to
`True`.
"""
- )]=True, exclude_unset: Annotated[bool, Doc(
- """
+ ),
+ ] = True,
+ exclude_unset: Annotated[
+ bool,
+ Doc(
+ """
Pydantic's `exclude_unset` parameter, passed to Pydantic models to define
if it should exclude from the output the fields that were not explicitly
set (and that only had their default values).
"""
- )]=False, exclude_defaults: Annotated[bool, Doc(
- """
+ ),
+ ] = False,
+ exclude_defaults: Annotated[
+ bool,
+ Doc(
+ """
Pydantic's `exclude_defaults` parameter, passed to Pydantic models to define
if it should exclude from the output the fields that had the same default
value, even when they were explicitly set.
"""
- )]=False, exclude_none: Annotated[bool, Doc(
- """
+ ),
+ ] = False,
+ exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Pydantic's `exclude_none` parameter, passed to Pydantic models to define
if it should exclude from the output any fields that have a `None` value.
"""
- )]=False, custom_encoder: Annotated[Optional[Dict[Any, Callable[[Any],
- Any]]], Doc(
- """
+ ),
+ ] = False,
+ custom_encoder: Annotated[
+ Optional[Dict[Any, Callable[[Any], Any]]],
+ Doc(
+ """
Pydantic's `custom_encoder` parameter, passed to Pydantic models to define
a custom encoder.
"""
- )]=None, sqlalchemy_safe: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ sqlalchemy_safe: Annotated[
+ bool,
+ Doc(
+ """
Exclude from the output any fields that start with the name `_sa`.
This is mainly a hack for compatibility with SQLAlchemy objects, they
store internal SQLAlchemy-specific state in attributes named with `_sa`,
and those objects can't (and shouldn't be) serialized to JSON.
"""
- )]=True) ->Any:
+ ),
+ ] = True,
+) -> Any:
"""
Convert any object to something that can be encoded in JSON.
@@ -114,4 +201,143 @@ def jsonable_encoder(obj: Annotated[Any, Doc(
Read more about it in the
[FastAPI docs for JSON Compatible Encoder](https://fastapi.tiangolo.com/tutorial/encoder/).
"""
- pass
+ custom_encoder = custom_encoder or {}
+ if custom_encoder:
+ if type(obj) in custom_encoder:
+ return custom_encoder[type(obj)](obj)
+ else:
+ for encoder_type, encoder_instance in custom_encoder.items():
+ if isinstance(obj, encoder_type):
+ return encoder_instance(obj)
+ if include is not None and not isinstance(include, (set, dict)):
+ include = set(include)
+ if exclude is not None and not isinstance(exclude, (set, dict)):
+ exclude = set(exclude)
+ if isinstance(obj, BaseModel):
+ # TODO: remove when deprecating Pydantic v1
+ encoders: Dict[Any, Any] = {}
+ if not PYDANTIC_V2:
+ encoders = getattr(obj.__config__, "json_encoders", {}) # type: ignore[attr-defined]
+ if custom_encoder:
+ encoders.update(custom_encoder)
+ obj_dict = _model_dump(
+ obj,
+ mode="json",
+ include=include,
+ exclude=exclude,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_none=exclude_none,
+ exclude_defaults=exclude_defaults,
+ )
+ if "__root__" in obj_dict:
+ obj_dict = obj_dict["__root__"]
+ return jsonable_encoder(
+ obj_dict,
+ exclude_none=exclude_none,
+ exclude_defaults=exclude_defaults,
+ # TODO: remove when deprecating Pydantic v1
+ custom_encoder=encoders,
+ sqlalchemy_safe=sqlalchemy_safe,
+ )
+ if dataclasses.is_dataclass(obj):
+ obj_dict = dataclasses.asdict(obj)
+ return jsonable_encoder(
+ obj_dict,
+ include=include,
+ exclude=exclude,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ custom_encoder=custom_encoder,
+ sqlalchemy_safe=sqlalchemy_safe,
+ )
+ if isinstance(obj, Enum):
+ return obj.value
+ if isinstance(obj, PurePath):
+ return str(obj)
+ if isinstance(obj, (str, int, float, type(None))):
+ return obj
+ if isinstance(obj, UndefinedType):
+ return None
+ if isinstance(obj, dict):
+ encoded_dict = {}
+ allowed_keys = set(obj.keys())
+ if include is not None:
+ allowed_keys &= set(include)
+ if exclude is not None:
+ allowed_keys -= set(exclude)
+ for key, value in obj.items():
+ if (
+ (
+ not sqlalchemy_safe
+ or (not isinstance(key, str))
+ or (not key.startswith("_sa"))
+ )
+ and (value is not None or not exclude_none)
+ and key in allowed_keys
+ ):
+ encoded_key = jsonable_encoder(
+ key,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_none=exclude_none,
+ custom_encoder=custom_encoder,
+ sqlalchemy_safe=sqlalchemy_safe,
+ )
+ encoded_value = jsonable_encoder(
+ value,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_none=exclude_none,
+ custom_encoder=custom_encoder,
+ sqlalchemy_safe=sqlalchemy_safe,
+ )
+ encoded_dict[encoded_key] = encoded_value
+ return encoded_dict
+ if isinstance(obj, (list, set, frozenset, GeneratorType, tuple, deque)):
+ encoded_list = []
+ for item in obj:
+ encoded_list.append(
+ jsonable_encoder(
+ item,
+ include=include,
+ exclude=exclude,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ custom_encoder=custom_encoder,
+ sqlalchemy_safe=sqlalchemy_safe,
+ )
+ )
+ return encoded_list
+
+ if type(obj) in ENCODERS_BY_TYPE:
+ return ENCODERS_BY_TYPE[type(obj)](obj)
+ for encoder, classes_tuple in encoders_by_class_tuples.items():
+ if isinstance(obj, classes_tuple):
+ return encoder(obj)
+
+ try:
+ data = dict(obj)
+ except Exception as e:
+ errors: List[Exception] = []
+ errors.append(e)
+ try:
+ data = vars(obj)
+ except Exception as e:
+ errors.append(e)
+ raise ValueError(errors) from e
+ return jsonable_encoder(
+ data,
+ include=include,
+ exclude=exclude,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ custom_encoder=custom_encoder,
+ sqlalchemy_safe=sqlalchemy_safe,
+ )
diff --git a/fastapi/exception_handlers.py b/fastapi/exception_handlers.py
index fab43330..6c2ba7fe 100644
--- a/fastapi/exception_handlers.py
+++ b/fastapi/exception_handlers.py
@@ -6,3 +6,29 @@ from starlette.exceptions import HTTPException
from starlette.requests import Request
from starlette.responses import JSONResponse, Response
from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY, WS_1008_POLICY_VIOLATION
+
+
+async def http_exception_handler(request: Request, exc: HTTPException) -> Response:
+ headers = getattr(exc, "headers", None)
+ if not is_body_allowed_for_status_code(exc.status_code):
+ return Response(status_code=exc.status_code, headers=headers)
+ return JSONResponse(
+ {"detail": exc.detail}, status_code=exc.status_code, headers=headers
+ )
+
+
+async def request_validation_exception_handler(
+ request: Request, exc: RequestValidationError
+) -> JSONResponse:
+ return JSONResponse(
+ status_code=HTTP_422_UNPROCESSABLE_ENTITY,
+ content={"detail": jsonable_encoder(exc.errors())},
+ )
+
+
+async def websocket_request_validation_exception_handler(
+ websocket: WebSocket, exc: WebSocketRequestValidationError
+) -> None:
+ await websocket.close(
+ code=WS_1008_POLICY_VIOLATION, reason=jsonable_encoder(exc.errors())
+ )
diff --git a/fastapi/exceptions.py b/fastapi/exceptions.py
index eaf7aec3..44d4ada8 100644
--- a/fastapi/exceptions.py
+++ b/fastapi/exceptions.py
@@ -1,4 +1,5 @@
from typing import Any, Dict, Optional, Sequence, Type, Union
+
from pydantic import BaseModel, create_model
from starlette.exceptions import HTTPException as StarletteHTTPException
from starlette.exceptions import WebSocketException as StarletteWebSocketException
@@ -33,22 +34,35 @@ class HTTPException(StarletteHTTPException):
```
"""
- def __init__(self, status_code: Annotated[int, Doc(
- """
+ def __init__(
+ self,
+ status_code: Annotated[
+ int,
+ Doc(
+ """
HTTP status code to send to the client.
"""
- )], detail: Annotated[Any, Doc(
- """
+ ),
+ ],
+ detail: Annotated[
+ Any,
+ Doc(
+ """
Any data to be sent to the client in the `detail` key of the JSON
response.
"""
- )]=None, headers: Annotated[Optional[Dict[str, str]], Doc(
- """
+ ),
+ ] = None,
+ headers: Annotated[
+ Optional[Dict[str, str]],
+ Doc(
+ """
Any headers to send to the client in the response.
"""
- )]=None) ->None:
- super().__init__(status_code=status_code, detail=detail, headers=
- headers)
+ ),
+ ] = None,
+ ) -> None:
+ super().__init__(status_code=status_code, detail=detail, headers=headers)
class WebSocketException(StarletteWebSocketException):
@@ -93,13 +107,21 @@ class WebSocketException(StarletteWebSocketException):
```
"""
- def __init__(self, code: Annotated[int, Doc(
- """
+ def __init__(
+ self,
+ code: Annotated[
+ int,
+ Doc(
+ """
A closing code from the
[valid codes defined in the specification](https://datatracker.ietf.org/doc/html/rfc6455#section-7.4.1).
"""
- )], reason: Annotated[Union[str, None], Doc(
- """
+ ),
+ ],
+ reason: Annotated[
+ Union[str, None],
+ Doc(
+ """
The reason to close the WebSocket connection.
It is UTF-8-encoded data. The interpretation of the reason is up to the
@@ -108,12 +130,14 @@ class WebSocketException(StarletteWebSocketException):
It could contain text that could be human-readable or interpretable
by the client code, etc.
"""
- )]=None) ->None:
+ ),
+ ] = None,
+ ) -> None:
super().__init__(code=code, reason=reason)
-RequestErrorModel: Type[BaseModel] = create_model('Request')
-WebSocketErrorModel: Type[BaseModel] = create_model('WebSocket')
+RequestErrorModel: Type[BaseModel] = create_model("Request")
+WebSocketErrorModel: Type[BaseModel] = create_model("WebSocket")
class FastAPIError(RuntimeError):
@@ -123,14 +147,15 @@ class FastAPIError(RuntimeError):
class ValidationException(Exception):
-
- def __init__(self, errors: Sequence[Any]) ->None:
+ def __init__(self, errors: Sequence[Any]) -> None:
self._errors = errors
+ def errors(self) -> Sequence[Any]:
+ return self._errors
-class RequestValidationError(ValidationException):
- def __init__(self, errors: Sequence[Any], *, body: Any=None) ->None:
+class RequestValidationError(ValidationException):
+ def __init__(self, errors: Sequence[Any], *, body: Any = None) -> None:
super().__init__(errors)
self.body = body
@@ -140,13 +165,12 @@ class WebSocketRequestValidationError(ValidationException):
class ResponseValidationError(ValidationException):
-
- def __init__(self, errors: Sequence[Any], *, body: Any=None) ->None:
+ def __init__(self, errors: Sequence[Any], *, body: Any = None) -> None:
super().__init__(errors)
self.body = body
- def __str__(self) ->str:
- message = f'{len(self._errors)} validation errors:\n'
+ def __str__(self) -> str:
+ message = f"{len(self._errors)} validation errors:\n"
for err in self._errors:
- message += f' {err}\n'
+ message += f" {err}\n"
return message
diff --git a/fastapi/logger.py b/fastapi/logger.py
index 3317a231..5b2c4ad5 100644
--- a/fastapi/logger.py
+++ b/fastapi/logger.py
@@ -1,2 +1,3 @@
import logging
-logger = logging.getLogger('fastapi')
+
+logger = logging.getLogger("fastapi")
diff --git a/fastapi/middleware/cors.py b/fastapi/middleware/cors.py
index 8bef8b14..8dfaad0d 100644
--- a/fastapi/middleware/cors.py
+++ b/fastapi/middleware/cors.py
@@ -1 +1 @@
-from starlette.middleware.cors import CORSMiddleware as CORSMiddleware
+from starlette.middleware.cors import CORSMiddleware as CORSMiddleware # noqa
diff --git a/fastapi/middleware/gzip.py b/fastapi/middleware/gzip.py
index 2d50d26a..bbeb2cc7 100644
--- a/fastapi/middleware/gzip.py
+++ b/fastapi/middleware/gzip.py
@@ -1 +1 @@
-from starlette.middleware.gzip import GZipMiddleware as GZipMiddleware
+from starlette.middleware.gzip import GZipMiddleware as GZipMiddleware # noqa
diff --git a/fastapi/middleware/httpsredirect.py b/fastapi/middleware/httpsredirect.py
index 41e6bde4..b7a3d8e0 100644
--- a/fastapi/middleware/httpsredirect.py
+++ b/fastapi/middleware/httpsredirect.py
@@ -1 +1,3 @@
-from starlette.middleware.httpsredirect import HTTPSRedirectMiddleware as HTTPSRedirectMiddleware
+from starlette.middleware.httpsredirect import ( # noqa
+ HTTPSRedirectMiddleware as HTTPSRedirectMiddleware,
+)
diff --git a/fastapi/middleware/trustedhost.py b/fastapi/middleware/trustedhost.py
index 00aa1fa6..08d7e035 100644
--- a/fastapi/middleware/trustedhost.py
+++ b/fastapi/middleware/trustedhost.py
@@ -1 +1,3 @@
-from starlette.middleware.trustedhost import TrustedHostMiddleware as TrustedHostMiddleware
+from starlette.middleware.trustedhost import ( # noqa
+ TrustedHostMiddleware as TrustedHostMiddleware,
+)
diff --git a/fastapi/middleware/wsgi.py b/fastapi/middleware/wsgi.py
index 5e01d0ef..c4c6a797 100644
--- a/fastapi/middleware/wsgi.py
+++ b/fastapi/middleware/wsgi.py
@@ -1 +1 @@
-from starlette.middleware.wsgi import WSGIMiddleware as WSGIMiddleware
+from starlette.middleware.wsgi import WSGIMiddleware as WSGIMiddleware # noqa
diff --git a/fastapi/openapi/constants.py b/fastapi/openapi/constants.py
index 639b3416..d724ee3c 100644
--- a/fastapi/openapi/constants.py
+++ b/fastapi/openapi/constants.py
@@ -1,3 +1,3 @@
-METHODS_WITH_BODY = {'GET', 'HEAD', 'POST', 'PUT', 'DELETE', 'PATCH'}
-REF_PREFIX = '#/components/schemas/'
-REF_TEMPLATE = '#/components/schemas/{model}'
+METHODS_WITH_BODY = {"GET", "HEAD", "POST", "PUT", "DELETE", "PATCH"}
+REF_PREFIX = "#/components/schemas/"
+REF_TEMPLATE = "#/components/schemas/{model}"
diff --git a/fastapi/openapi/docs.py b/fastapi/openapi/docs.py
index a9c03e54..c2ec358d 100644
--- a/fastapi/openapi/docs.py
+++ b/fastapi/openapi/docs.py
@@ -1,65 +1,104 @@
import json
from typing import Any, Dict, Optional
+
from fastapi.encoders import jsonable_encoder
from starlette.responses import HTMLResponse
from typing_extensions import Annotated, Doc
-swagger_ui_default_parameters: Annotated[Dict[str, Any], Doc(
- """
+
+swagger_ui_default_parameters: Annotated[
+ Dict[str, Any],
+ Doc(
+ """
Default configurations for Swagger UI.
You can use it as a template to add any other configurations needed.
"""
- )] = {'dom_id': '#swagger-ui', 'layout': 'BaseLayout', 'deepLinking':
- True, 'showExtensions': True, 'showCommonExtensions': True}
+ ),
+] = {
+ "dom_id": "#swagger-ui",
+ "layout": "BaseLayout",
+ "deepLinking": True,
+ "showExtensions": True,
+ "showCommonExtensions": True,
+}
-def get_swagger_ui_html(*, openapi_url: Annotated[str, Doc(
- """
+def get_swagger_ui_html(
+ *,
+ openapi_url: Annotated[
+ str,
+ Doc(
+ """
The OpenAPI URL that Swagger UI should load and use.
This is normally done automatically by FastAPI using the default URL
`/openapi.json`.
"""
- )], title: Annotated[str, Doc(
- """
+ ),
+ ],
+ title: Annotated[
+ str,
+ Doc(
+ """
The HTML `<title>` content, normally shown in the browser tab.
"""
- )], swagger_js_url: Annotated[str, Doc(
- """
+ ),
+ ],
+ swagger_js_url: Annotated[
+ str,
+ Doc(
+ """
The URL to use to load the Swagger UI JavaScript.
It is normally set to a CDN URL.
"""
- )]=
- 'https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js',
- swagger_css_url: Annotated[str, Doc(
- """
+ ),
+ ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js",
+ swagger_css_url: Annotated[
+ str,
+ Doc(
+ """
The URL to use to load the Swagger UI CSS.
It is normally set to a CDN URL.
"""
- )]='https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css',
- swagger_favicon_url: Annotated[str, Doc(
- """
+ ),
+ ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css",
+ swagger_favicon_url: Annotated[
+ str,
+ Doc(
+ """
The URL of the favicon to use. It is normally shown in the browser tab.
"""
- )]='https://fastapi.tiangolo.com/img/favicon.png', oauth2_redirect_url:
- Annotated[Optional[str], Doc(
- """
+ ),
+ ] = "https://fastapi.tiangolo.com/img/favicon.png",
+ oauth2_redirect_url: Annotated[
+ Optional[str],
+ Doc(
+ """
The OAuth2 redirect URL, it is normally automatically handled by FastAPI.
"""
- )]=None, init_oauth: Annotated[Optional[Dict[str, Any]], Doc(
- """
+ ),
+ ] = None,
+ init_oauth: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
A dictionary with Swagger UI OAuth2 initialization configurations.
"""
- )]=None, swagger_ui_parameters: Annotated[Optional[Dict[str, Any]], Doc
- (
- """
+ ),
+ ] = None,
+ swagger_ui_parameters: Annotated[
+ Optional[Dict[str, Any]],
+ Doc(
+ """
Configuration parameters for Swagger UI.
It defaults to [swagger_ui_default_parameters][fastapi.openapi.docs.swagger_ui_default_parameters].
"""
- )]=None) ->HTMLResponse:
+ ),
+ ] = None,
+) -> HTMLResponse:
"""
Generate and return the HTML that loads Swagger UI for the interactive
API docs (normally served at `/docs`).
@@ -71,38 +110,102 @@ def get_swagger_ui_html(*, openapi_url: Annotated[str, Doc(
[FastAPI docs for Configure Swagger UI](https://fastapi.tiangolo.com/how-to/configure-swagger-ui/)
and the [FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/).
"""
- pass
+ current_swagger_ui_parameters = swagger_ui_default_parameters.copy()
+ if swagger_ui_parameters:
+ current_swagger_ui_parameters.update(swagger_ui_parameters)
+
+ html = f"""
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <link type="text/css" rel="stylesheet" href="{swagger_css_url}">
+ <link rel="shortcut icon" href="{swagger_favicon_url}">
+ <title>{title}</title>
+ </head>
+ <body>
+ <div id="swagger-ui">
+ </div>
+ <script src="{swagger_js_url}"></script>
+ <!-- `SwaggerUIBundle` is now available on the page -->
+ <script>
+ const ui = SwaggerUIBundle({{
+ url: '{openapi_url}',
+ """
+ for key, value in current_swagger_ui_parameters.items():
+ html += f"{json.dumps(key)}: {json.dumps(jsonable_encoder(value))},\n"
-def get_redoc_html(*, openapi_url: Annotated[str, Doc(
+ if oauth2_redirect_url:
+ html += f"oauth2RedirectUrl: window.location.origin + '{oauth2_redirect_url}',"
+
+ html += """
+ presets: [
+ SwaggerUIBundle.presets.apis,
+ SwaggerUIBundle.SwaggerUIStandalonePreset
+ ],
+ })"""
+
+ if init_oauth:
+ html += f"""
+ ui.initOAuth({json.dumps(jsonable_encoder(init_oauth))})
+ """
+
+ html += """
+ </script>
+ </body>
+ </html>
"""
+ return HTMLResponse(html)
+
+
+def get_redoc_html(
+ *,
+ openapi_url: Annotated[
+ str,
+ Doc(
+ """
The OpenAPI URL that ReDoc should load and use.
This is normally done automatically by FastAPI using the default URL
`/openapi.json`.
"""
- )], title: Annotated[str, Doc(
- """
+ ),
+ ],
+ title: Annotated[
+ str,
+ Doc(
+ """
The HTML `<title>` content, normally shown in the browser tab.
"""
- )], redoc_js_url: Annotated[str, Doc(
- """
+ ),
+ ],
+ redoc_js_url: Annotated[
+ str,
+ Doc(
+ """
The URL to use to load the ReDoc JavaScript.
It is normally set to a CDN URL.
"""
- )]=
- 'https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js',
- redoc_favicon_url: Annotated[str, Doc(
- """
+ ),
+ ] = "https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js",
+ redoc_favicon_url: Annotated[
+ str,
+ Doc(
+ """
The URL of the favicon to use. It is normally shown in the browser tab.
"""
- )]='https://fastapi.tiangolo.com/img/favicon.png', with_google_fonts:
- Annotated[bool, Doc(
- """
+ ),
+ ] = "https://fastapi.tiangolo.com/img/favicon.png",
+ with_google_fonts: Annotated[
+ bool,
+ Doc(
+ """
Load and use Google Fonts.
- """)]=True
- ) ->HTMLResponse:
+ """
+ ),
+ ] = True,
+) -> HTMLResponse:
"""
Generate and return the HTML response that loads ReDoc for the alternative
API docs (normally served at `/redoc`).
@@ -113,13 +216,129 @@ def get_redoc_html(*, openapi_url: Annotated[str, Doc(
Read more about it in the
[FastAPI docs for Custom Docs UI Static Assets (Self-Hosting)](https://fastapi.tiangolo.com/how-to/custom-docs-ui-assets/).
"""
- pass
+ html = f"""
+ <!DOCTYPE html>
+ <html>
+ <head>
+ <title>{title}</title>
+ <!-- needed for adaptive design -->
+ <meta charset="utf-8"/>
+ <meta name="viewport" content="width=device-width, initial-scale=1">
+ """
+ if with_google_fonts:
+ html += """
+ <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+ """
+ html += f"""
+ <link rel="shortcut icon" href="{redoc_favicon_url}">
+ <!--
+ ReDoc doesn't change outer page styles
+ -->
+ <style>
+ body {{
+ margin: 0;
+ padding: 0;
+ }}
+ </style>
+ </head>
+ <body>
+ <noscript>
+ ReDoc requires Javascript to function. Please enable it to browse the documentation.
+ </noscript>
+ <redoc spec-url="{openapi_url}"></redoc>
+ <script src="{redoc_js_url}"> </script>
+ </body>
+ </html>
+ """
+ return HTMLResponse(html)
-def get_swagger_ui_oauth2_redirect_html() ->HTMLResponse:
+def get_swagger_ui_oauth2_redirect_html() -> HTMLResponse:
"""
Generate the HTML response with the OAuth2 redirection for Swagger UI.
You normally don't need to use or change this.
"""
- pass
+ # copied from https://github.com/swagger-api/swagger-ui/blob/v4.14.0/dist/oauth2-redirect.html
+ html = """
+ <!doctype html>
+ <html lang="en-US">
+ <head>
+ <title>Swagger UI: OAuth2 Redirect</title>
+ </head>
+ <body>
+ <script>
+ 'use strict';
+ function run () {
+ var oauth2 = window.opener.swaggerUIRedirectOauth2;
+ var sentState = oauth2.state;
+ var redirectUrl = oauth2.redirectUrl;
+ var isValid, qp, arr;
+
+ if (/code|token|error/.test(window.location.hash)) {
+ qp = window.location.hash.substring(1).replace('?', '&');
+ } else {
+ qp = location.search.substring(1);
+ }
+
+ arr = qp.split("&");
+ arr.forEach(function (v,i,_arr) { _arr[i] = '"' + v.replace('=', '":"') + '"';});
+ qp = qp ? JSON.parse('{' + arr.join() + '}',
+ function (key, value) {
+ return key === "" ? value : decodeURIComponent(value);
+ }
+ ) : {};
+
+ isValid = qp.state === sentState;
+
+ if ((
+ oauth2.auth.schema.get("flow") === "accessCode" ||
+ oauth2.auth.schema.get("flow") === "authorizationCode" ||
+ oauth2.auth.schema.get("flow") === "authorization_code"
+ ) && !oauth2.auth.code) {
+ if (!isValid) {
+ oauth2.errCb({
+ authId: oauth2.auth.name,
+ source: "auth",
+ level: "warning",
+ message: "Authorization may be unsafe, passed state was changed in server. The passed state wasn't returned from auth server."
+ });
+ }
+
+ if (qp.code) {
+ delete oauth2.state;
+ oauth2.auth.code = qp.code;
+ oauth2.callback({auth: oauth2.auth, redirectUrl: redirectUrl});
+ } else {
+ let oauthErrorMsg;
+ if (qp.error) {
+ oauthErrorMsg = "["+qp.error+"]: " +
+ (qp.error_description ? qp.error_description+ ". " : "no accessCode received from the server. ") +
+ (qp.error_uri ? "More info: "+qp.error_uri : "");
+ }
+
+ oauth2.errCb({
+ authId: oauth2.auth.name,
+ source: "auth",
+ level: "error",
+ message: oauthErrorMsg || "[Authorization failed]: no accessCode received from the server."
+ });
+ }
+ } else {
+ oauth2.callback({auth: oauth2.auth, token: qp, isValid: isValid, redirectUrl: redirectUrl});
+ }
+ window.close();
+ }
+
+ if (document.readyState !== 'loading') {
+ run();
+ } else {
+ document.addEventListener('DOMContentLoaded', function () {
+ run();
+ });
+ }
+ </script>
+ </body>
+ </html>
+ """
+ return HTMLResponse(content=html)
diff --git a/fastapi/openapi/models.py b/fastapi/openapi/models.py
index 33fbecd4..ed07b40f 100644
--- a/fastapi/openapi/models.py
+++ b/fastapi/openapi/models.py
@@ -1,42 +1,68 @@
from enum import Enum
from typing import Any, Callable, Dict, Iterable, List, Optional, Set, Type, Union
-from fastapi._compat import PYDANTIC_V2, CoreSchema, GetJsonSchemaHandler, JsonSchemaValue, _model_rebuild, with_info_plain_validator_function
+
+from fastapi._compat import (
+ PYDANTIC_V2,
+ CoreSchema,
+ GetJsonSchemaHandler,
+ JsonSchemaValue,
+ _model_rebuild,
+ with_info_plain_validator_function,
+)
from fastapi.logger import logger
from pydantic import AnyUrl, BaseModel, Field
from typing_extensions import Annotated, Literal, TypedDict
from typing_extensions import deprecated as typing_deprecated
+
try:
import email_validator
- assert email_validator
+
+ assert email_validator # make autoflake ignore the unused import
from pydantic import EmailStr
-except ImportError:
+except ImportError: # pragma: no cover
+ class EmailStr(str): # type: ignore
+ @classmethod
+ def __get_validators__(cls) -> Iterable[Callable[..., Any]]:
+ yield cls.validate
- class EmailStr(str):
+ @classmethod
+ def validate(cls, v: Any) -> str:
+ logger.warning(
+ "email-validator not installed, email fields will be treated as str.\n"
+ "To install, run: pip install email-validator"
+ )
+ return str(v)
@classmethod
- def __get_validators__(cls) ->Iterable[Callable[..., Any]]:
- yield cls.validate
+ def _validate(cls, __input_value: Any, _: Any) -> str:
+ logger.warning(
+ "email-validator not installed, email fields will be treated as str.\n"
+ "To install, run: pip install email-validator"
+ )
+ return str(__input_value)
@classmethod
- def __get_pydantic_json_schema__(cls, core_schema: CoreSchema,
- handler: GetJsonSchemaHandler) ->JsonSchemaValue:
- return {'type': 'string', 'format': 'email'}
+ def __get_pydantic_json_schema__(
+ cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler
+ ) -> JsonSchemaValue:
+ return {"type": "string", "format": "email"}
@classmethod
- def __get_pydantic_core_schema__(cls, source: Type[Any], handler:
- Callable[[Any], CoreSchema]) ->CoreSchema:
+ def __get_pydantic_core_schema__(
+ cls, source: Type[Any], handler: Callable[[Any], CoreSchema]
+ ) -> CoreSchema:
return with_info_plain_validator_function(cls._validate)
class BaseModelWithConfig(BaseModel):
if PYDANTIC_V2:
- model_config = {'extra': 'allow'}
- else:
+ model_config = {"extra": "allow"}
+ else:
class Config:
- extra = 'allow'
+ extra = "allow"
class Contact(BaseModelWithConfig):
@@ -74,7 +100,7 @@ class Server(BaseModelWithConfig):
class Reference(BaseModel):
- ref: str = Field(alias='$ref')
+ ref: str = Field(alias="$ref")
class Discriminator(BaseModel):
@@ -96,33 +122,41 @@ class ExternalDocumentation(BaseModelWithConfig):
class Schema(BaseModelWithConfig):
- schema_: Optional[str] = Field(default=None, alias='$schema')
- vocabulary: Optional[str] = Field(default=None, alias='$vocabulary')
- id: Optional[str] = Field(default=None, alias='$id')
- anchor: Optional[str] = Field(default=None, alias='$anchor')
- dynamicAnchor: Optional[str] = Field(default=None, alias='$dynamicAnchor')
- ref: Optional[str] = Field(default=None, alias='$ref')
- dynamicRef: Optional[str] = Field(default=None, alias='$dynamicRef')
- defs: Optional[Dict[str, 'SchemaOrBool']] = Field(default=None, alias=
- '$defs')
- comment: Optional[str] = Field(default=None, alias='$comment')
- allOf: Optional[List['SchemaOrBool']] = None
- anyOf: Optional[List['SchemaOrBool']] = None
- oneOf: Optional[List['SchemaOrBool']] = None
- not_: Optional['SchemaOrBool'] = Field(default=None, alias='not')
- if_: Optional['SchemaOrBool'] = Field(default=None, alias='if')
- then: Optional['SchemaOrBool'] = None
- else_: Optional['SchemaOrBool'] = Field(default=None, alias='else')
- dependentSchemas: Optional[Dict[str, 'SchemaOrBool']] = None
- prefixItems: Optional[List['SchemaOrBool']] = None
- items: Optional[Union['SchemaOrBool', List['SchemaOrBool']]] = None
- contains: Optional['SchemaOrBool'] = None
- properties: Optional[Dict[str, 'SchemaOrBool']] = None
- patternProperties: Optional[Dict[str, 'SchemaOrBool']] = None
- additionalProperties: Optional['SchemaOrBool'] = None
- propertyNames: Optional['SchemaOrBool'] = None
- unevaluatedItems: Optional['SchemaOrBool'] = None
- unevaluatedProperties: Optional['SchemaOrBool'] = None
+ # Ref: JSON Schema 2020-12: https://json-schema.org/draft/2020-12/json-schema-core.html#name-the-json-schema-core-vocabu
+ # Core Vocabulary
+ schema_: Optional[str] = Field(default=None, alias="$schema")
+ vocabulary: Optional[str] = Field(default=None, alias="$vocabulary")
+ id: Optional[str] = Field(default=None, alias="$id")
+ anchor: Optional[str] = Field(default=None, alias="$anchor")
+ dynamicAnchor: Optional[str] = Field(default=None, alias="$dynamicAnchor")
+ ref: Optional[str] = Field(default=None, alias="$ref")
+ dynamicRef: Optional[str] = Field(default=None, alias="$dynamicRef")
+ defs: Optional[Dict[str, "SchemaOrBool"]] = Field(default=None, alias="$defs")
+ comment: Optional[str] = Field(default=None, alias="$comment")
+ # Ref: JSON Schema 2020-12: https://json-schema.org/draft/2020-12/json-schema-core.html#name-a-vocabulary-for-applying-s
+ # A Vocabulary for Applying Subschemas
+ allOf: Optional[List["SchemaOrBool"]] = None
+ anyOf: Optional[List["SchemaOrBool"]] = None
+ oneOf: Optional[List["SchemaOrBool"]] = None
+ not_: Optional["SchemaOrBool"] = Field(default=None, alias="not")
+ if_: Optional["SchemaOrBool"] = Field(default=None, alias="if")
+ then: Optional["SchemaOrBool"] = None
+ else_: Optional["SchemaOrBool"] = Field(default=None, alias="else")
+ dependentSchemas: Optional[Dict[str, "SchemaOrBool"]] = None
+ prefixItems: Optional[List["SchemaOrBool"]] = None
+ # TODO: uncomment and remove below when deprecating Pydantic v1
+ # It generales a list of schemas for tuples, before prefixItems was available
+ # items: Optional["SchemaOrBool"] = None
+ items: Optional[Union["SchemaOrBool", List["SchemaOrBool"]]] = None
+ contains: Optional["SchemaOrBool"] = None
+ properties: Optional[Dict[str, "SchemaOrBool"]] = None
+ patternProperties: Optional[Dict[str, "SchemaOrBool"]] = None
+ additionalProperties: Optional["SchemaOrBool"] = None
+ propertyNames: Optional["SchemaOrBool"] = None
+ unevaluatedItems: Optional["SchemaOrBool"] = None
+ unevaluatedProperties: Optional["SchemaOrBool"] = None
+ # Ref: JSON Schema Validation 2020-12: https://json-schema.org/draft/2020-12/json-schema-validation.html#name-a-vocabulary-for-structural
+ # A Vocabulary for Structural Validation
type: Optional[str] = None
enum: Optional[List[Any]] = None
const: Optional[Any] = None
@@ -143,10 +177,16 @@ class Schema(BaseModelWithConfig):
minProperties: Optional[int] = Field(default=None, ge=0)
required: Optional[List[str]] = None
dependentRequired: Optional[Dict[str, Set[str]]] = None
+ # Ref: JSON Schema Validation 2020-12: https://json-schema.org/draft/2020-12/json-schema-validation.html#name-vocabularies-for-semantic-c
+ # Vocabularies for Semantic Content With "format"
format: Optional[str] = None
+ # Ref: JSON Schema Validation 2020-12: https://json-schema.org/draft/2020-12/json-schema-validation.html#name-a-vocabulary-for-the-conten
+ # A Vocabulary for the Contents of String-Encoded Data
contentEncoding: Optional[str] = None
contentMediaType: Optional[str] = None
- contentSchema: Optional['SchemaOrBool'] = None
+ contentSchema: Optional["SchemaOrBool"] = None
+ # Ref: JSON Schema Validation 2020-12: https://json-schema.org/draft/2020-12/json-schema-validation.html#name-a-vocabulary-for-basic-meta
+ # A Vocabulary for Basic Meta-Data Annotations
title: Optional[str] = None
description: Optional[str] = None
default: Optional[Any] = None
@@ -154,49 +194,57 @@ class Schema(BaseModelWithConfig):
readOnly: Optional[bool] = None
writeOnly: Optional[bool] = None
examples: Optional[List[Any]] = None
+ # Ref: OpenAPI 3.1.0: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#schema-object
+ # Schema Object
discriminator: Optional[Discriminator] = None
xml: Optional[XML] = None
externalDocs: Optional[ExternalDocumentation] = None
- example: Annotated[Optional[Any], typing_deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )] = None
+ example: Annotated[
+ Optional[Any],
+ typing_deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = None
+# Ref: https://json-schema.org/draft/2020-12/json-schema-core.html#name-json-schema-documents
+# A JSON Schema MUST be an object or a boolean.
SchemaOrBool = Union[Schema, bool]
-class Example(TypedDict, total=(False)):
+class Example(TypedDict, total=False):
summary: Optional[str]
description: Optional[str]
value: Optional[Any]
externalValue: Optional[AnyUrl]
- if PYDANTIC_V2:
- __pydantic_config__ = {'extra': 'allow'}
- else:
+ if PYDANTIC_V2: # type: ignore [misc]
+ __pydantic_config__ = {"extra": "allow"}
+
+ else:
class Config:
- extra = 'allow'
+ extra = "allow"
class ParameterInType(Enum):
- query = 'query'
- header = 'header'
- path = 'path'
- cookie = 'cookie'
+ query = "query"
+ header = "header"
+ path = "path"
+ cookie = "cookie"
class Encoding(BaseModelWithConfig):
contentType: Optional[str] = None
- headers: Optional[Dict[str, Union['Header', Reference]]] = None
+ headers: Optional[Dict[str, Union["Header", Reference]]] = None
style: Optional[str] = None
explode: Optional[bool] = None
allowReserved: Optional[bool] = None
class MediaType(BaseModelWithConfig):
- schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias
- ='schema')
+ schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
example: Optional[Any] = None
examples: Optional[Dict[str, Union[Example, Reference]]] = None
encoding: Optional[Dict[str, Encoding]] = None
@@ -206,19 +254,20 @@ class ParameterBase(BaseModelWithConfig):
description: Optional[str] = None
required: Optional[bool] = None
deprecated: Optional[bool] = None
+ # Serialization rules for simple scenarios
style: Optional[str] = None
explode: Optional[bool] = None
allowReserved: Optional[bool] = None
- schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias
- ='schema')
+ schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
example: Optional[Any] = None
examples: Optional[Dict[str, Union[Example, Reference]]] = None
+ # Serialization rules for more complex scenarios
content: Optional[Dict[str, MediaType]] = None
class Parameter(ParameterBase):
name: str
- in_: ParameterInType = Field(alias='in')
+ in_: ParameterInType = Field(alias="in")
class Header(ParameterBase):
@@ -255,16 +304,16 @@ class Operation(BaseModelWithConfig):
operationId: Optional[str] = None
parameters: Optional[List[Union[Parameter, Reference]]] = None
requestBody: Optional[Union[RequestBody, Reference]] = None
+ # Using Any for Specification Extensions
responses: Optional[Dict[str, Union[Response, Any]]] = None
- callbacks: Optional[Dict[str, Union[Dict[str, 'PathItem'], Reference]]
- ] = None
+ callbacks: Optional[Dict[str, Union[Dict[str, "PathItem"], Reference]]] = None
deprecated: Optional[bool] = None
security: Optional[List[Dict[str, List[str]]]] = None
servers: Optional[List[Server]] = None
class PathItem(BaseModelWithConfig):
- ref: Optional[str] = Field(default=None, alias='$ref')
+ ref: Optional[str] = Field(default=None, alias="$ref")
summary: Optional[str] = None
description: Optional[str] = None
get: Optional[Operation] = None
@@ -280,38 +329,36 @@ class PathItem(BaseModelWithConfig):
class SecuritySchemeType(Enum):
- apiKey = 'apiKey'
- http = 'http'
- oauth2 = 'oauth2'
- openIdConnect = 'openIdConnect'
+ apiKey = "apiKey"
+ http = "http"
+ oauth2 = "oauth2"
+ openIdConnect = "openIdConnect"
class SecurityBase(BaseModelWithConfig):
- type_: SecuritySchemeType = Field(alias='type')
+ type_: SecuritySchemeType = Field(alias="type")
description: Optional[str] = None
class APIKeyIn(Enum):
- query = 'query'
- header = 'header'
- cookie = 'cookie'
+ query = "query"
+ header = "header"
+ cookie = "cookie"
class APIKey(SecurityBase):
- type_: SecuritySchemeType = Field(default=SecuritySchemeType.apiKey,
- alias='type')
- in_: APIKeyIn = Field(alias='in')
+ type_: SecuritySchemeType = Field(default=SecuritySchemeType.apiKey, alias="type")
+ in_: APIKeyIn = Field(alias="in")
name: str
class HTTPBase(SecurityBase):
- type_: SecuritySchemeType = Field(default=SecuritySchemeType.http,
- alias='type')
+ type_: SecuritySchemeType = Field(default=SecuritySchemeType.http, alias="type")
scheme: str
class HTTPBearer(HTTPBase):
- scheme: Literal['bearer'] = 'bearer'
+ scheme: Literal["bearer"] = "bearer"
bearerFormat: Optional[str] = None
@@ -345,14 +392,14 @@ class OAuthFlows(BaseModelWithConfig):
class OAuth2(SecurityBase):
- type_: SecuritySchemeType = Field(default=SecuritySchemeType.oauth2,
- alias='type')
+ type_: SecuritySchemeType = Field(default=SecuritySchemeType.oauth2, alias="type")
flows: OAuthFlows
class OpenIdConnect(SecurityBase):
- type_: SecuritySchemeType = Field(default=SecuritySchemeType.
- openIdConnect, alias='type')
+ type_: SecuritySchemeType = Field(
+ default=SecuritySchemeType.openIdConnect, alias="type"
+ )
openIdConnectUrl: str
@@ -366,11 +413,10 @@ class Components(BaseModelWithConfig):
examples: Optional[Dict[str, Union[Example, Reference]]] = None
requestBodies: Optional[Dict[str, Union[RequestBody, Reference]]] = None
headers: Optional[Dict[str, Union[Header, Reference]]] = None
- securitySchemes: Optional[Dict[str, Union[SecurityScheme, Reference]]
- ] = None
+ securitySchemes: Optional[Dict[str, Union[SecurityScheme, Reference]]] = None
links: Optional[Dict[str, Union[Link, Reference]]] = None
- callbacks: Optional[Dict[str, Union[Dict[str, PathItem], Reference, Any]]
- ] = None
+ # Using Any for Specification Extensions
+ callbacks: Optional[Dict[str, Union[Dict[str, PathItem], Reference, Any]]] = None
pathItems: Optional[Dict[str, Union[PathItem, Reference]]] = None
@@ -385,6 +431,7 @@ class OpenAPI(BaseModelWithConfig):
info: Info
jsonSchemaDialect: Optional[str] = None
servers: Optional[List[Server]] = None
+ # Using Any for Specification Extensions
paths: Optional[Dict[str, Union[PathItem, Any]]] = None
webhooks: Optional[Dict[str, Union[PathItem, Reference]]] = None
components: Optional[Components] = None
diff --git a/fastapi/openapi/utils.py b/fastapi/openapi/utils.py
index 8f105dce..79ad9f83 100644
--- a/fastapi/openapi/utils.py
+++ b/fastapi/openapi/utils.py
@@ -2,8 +2,18 @@ import http.client
import inspect
import warnings
from typing import Any, Dict, List, Optional, Sequence, Set, Tuple, Type, Union, cast
+
from fastapi import routing
-from fastapi._compat import GenerateJsonSchema, JsonSchemaValue, ModelField, Undefined, get_compat_model_name_map, get_definitions, get_schema_from_model_field, lenient_issubclass
+from fastapi._compat import (
+ GenerateJsonSchema,
+ JsonSchemaValue,
+ ModelField,
+ Undefined,
+ get_compat_model_name_map,
+ get_definitions,
+ get_schema_from_model_field,
+ lenient_issubclass,
+)
from fastapi.datastructures import DefaultPlaceholder
from fastapi.dependencies.models import Dependant
from fastapi.dependencies.utils import get_flat_dependant, get_flat_params
@@ -13,19 +23,508 @@ from fastapi.openapi.models import OpenAPI
from fastapi.params import Body, Param
from fastapi.responses import Response
from fastapi.types import ModelNameMap
-from fastapi.utils import deep_dict_update, generate_operation_id_for_path, is_body_allowed_for_status_code
+from fastapi.utils import (
+ deep_dict_update,
+ generate_operation_id_for_path,
+ is_body_allowed_for_status_code,
+)
from starlette.responses import JSONResponse
from starlette.routing import BaseRoute
from starlette.status import HTTP_422_UNPROCESSABLE_ENTITY
from typing_extensions import Literal
-validation_error_definition = {'title': 'ValidationError', 'type': 'object',
- 'properties': {'loc': {'title': 'Location', 'type': 'array', 'items': {
- 'anyOf': [{'type': 'string'}, {'type': 'integer'}]}}, 'msg': {'title':
- 'Message', 'type': 'string'}, 'type': {'title': 'Error Type', 'type':
- 'string'}}, 'required': ['loc', 'msg', 'type']}
-validation_error_response_definition = {'title': 'HTTPValidationError',
- 'type': 'object', 'properties': {'detail': {'title': 'Detail', 'type':
- 'array', 'items': {'$ref': REF_PREFIX + 'ValidationError'}}}}
-status_code_ranges: Dict[str, str] = {'1XX': 'Information', '2XX':
- 'Success', '3XX': 'Redirection', '4XX': 'Client Error', '5XX':
- 'Server Error', 'DEFAULT': 'Default Response'}
+
+validation_error_definition = {
+ "title": "ValidationError",
+ "type": "object",
+ "properties": {
+ "loc": {
+ "title": "Location",
+ "type": "array",
+ "items": {"anyOf": [{"type": "string"}, {"type": "integer"}]},
+ },
+ "msg": {"title": "Message", "type": "string"},
+ "type": {"title": "Error Type", "type": "string"},
+ },
+ "required": ["loc", "msg", "type"],
+}
+
+validation_error_response_definition = {
+ "title": "HTTPValidationError",
+ "type": "object",
+ "properties": {
+ "detail": {
+ "title": "Detail",
+ "type": "array",
+ "items": {"$ref": REF_PREFIX + "ValidationError"},
+ }
+ },
+}
+
+status_code_ranges: Dict[str, str] = {
+ "1XX": "Information",
+ "2XX": "Success",
+ "3XX": "Redirection",
+ "4XX": "Client Error",
+ "5XX": "Server Error",
+ "DEFAULT": "Default Response",
+}
+
+
+def get_openapi_security_definitions(
+ flat_dependant: Dependant,
+) -> Tuple[Dict[str, Any], List[Dict[str, Any]]]:
+ security_definitions = {}
+ operation_security = []
+ for security_requirement in flat_dependant.security_requirements:
+ security_definition = jsonable_encoder(
+ security_requirement.security_scheme.model,
+ by_alias=True,
+ exclude_none=True,
+ )
+ security_name = security_requirement.security_scheme.scheme_name
+ security_definitions[security_name] = security_definition
+ operation_security.append({security_name: security_requirement.scopes})
+ return security_definitions, operation_security
+
+
+def get_openapi_operation_parameters(
+ *,
+ all_route_params: Sequence[ModelField],
+ schema_generator: GenerateJsonSchema,
+ model_name_map: ModelNameMap,
+ field_mapping: Dict[
+ Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
+ ],
+ separate_input_output_schemas: bool = True,
+) -> List[Dict[str, Any]]:
+ parameters = []
+ for param in all_route_params:
+ field_info = param.field_info
+ field_info = cast(Param, field_info)
+ if not field_info.include_in_schema:
+ continue
+ param_schema = get_schema_from_model_field(
+ field=param,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ parameter = {
+ "name": param.alias,
+ "in": field_info.in_.value,
+ "required": param.required,
+ "schema": param_schema,
+ }
+ if field_info.description:
+ parameter["description"] = field_info.description
+ if field_info.openapi_examples:
+ parameter["examples"] = jsonable_encoder(field_info.openapi_examples)
+ elif field_info.example != Undefined:
+ parameter["example"] = jsonable_encoder(field_info.example)
+ if field_info.deprecated:
+ parameter["deprecated"] = True
+ parameters.append(parameter)
+ return parameters
+
+
+def get_openapi_operation_request_body(
+ *,
+ body_field: Optional[ModelField],
+ schema_generator: GenerateJsonSchema,
+ model_name_map: ModelNameMap,
+ field_mapping: Dict[
+ Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
+ ],
+ separate_input_output_schemas: bool = True,
+) -> Optional[Dict[str, Any]]:
+ if not body_field:
+ return None
+ assert isinstance(body_field, ModelField)
+ body_schema = get_schema_from_model_field(
+ field=body_field,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ field_info = cast(Body, body_field.field_info)
+ request_media_type = field_info.media_type
+ required = body_field.required
+ request_body_oai: Dict[str, Any] = {}
+ if required:
+ request_body_oai["required"] = required
+ request_media_content: Dict[str, Any] = {"schema": body_schema}
+ if field_info.openapi_examples:
+ request_media_content["examples"] = jsonable_encoder(
+ field_info.openapi_examples
+ )
+ elif field_info.example != Undefined:
+ request_media_content["example"] = jsonable_encoder(field_info.example)
+ request_body_oai["content"] = {request_media_type: request_media_content}
+ return request_body_oai
+
+
+def generate_operation_id(
+ *, route: routing.APIRoute, method: str
+) -> str: # pragma: nocover
+ warnings.warn(
+ "fastapi.openapi.utils.generate_operation_id() was deprecated, "
+ "it is not used internally, and will be removed soon",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ if route.operation_id:
+ return route.operation_id
+ path: str = route.path_format
+ return generate_operation_id_for_path(name=route.name, path=path, method=method)
+
+
+def generate_operation_summary(*, route: routing.APIRoute, method: str) -> str:
+ if route.summary:
+ return route.summary
+ return route.name.replace("_", " ").title()
+
+
+def get_openapi_operation_metadata(
+ *, route: routing.APIRoute, method: str, operation_ids: Set[str]
+) -> Dict[str, Any]:
+ operation: Dict[str, Any] = {}
+ if route.tags:
+ operation["tags"] = route.tags
+ operation["summary"] = generate_operation_summary(route=route, method=method)
+ if route.description:
+ operation["description"] = route.description
+ operation_id = route.operation_id or route.unique_id
+ if operation_id in operation_ids:
+ message = (
+ f"Duplicate Operation ID {operation_id} for function "
+ + f"{route.endpoint.__name__}"
+ )
+ file_name = getattr(route.endpoint, "__globals__", {}).get("__file__")
+ if file_name:
+ message += f" at {file_name}"
+ warnings.warn(message, stacklevel=1)
+ operation_ids.add(operation_id)
+ operation["operationId"] = operation_id
+ if route.deprecated:
+ operation["deprecated"] = route.deprecated
+ return operation
+
+
+def get_openapi_path(
+ *,
+ route: routing.APIRoute,
+ operation_ids: Set[str],
+ schema_generator: GenerateJsonSchema,
+ model_name_map: ModelNameMap,
+ field_mapping: Dict[
+ Tuple[ModelField, Literal["validation", "serialization"]], JsonSchemaValue
+ ],
+ separate_input_output_schemas: bool = True,
+) -> Tuple[Dict[str, Any], Dict[str, Any], Dict[str, Any]]:
+ path = {}
+ security_schemes: Dict[str, Any] = {}
+ definitions: Dict[str, Any] = {}
+ assert route.methods is not None, "Methods must be a list"
+ if isinstance(route.response_class, DefaultPlaceholder):
+ current_response_class: Type[Response] = route.response_class.value
+ else:
+ current_response_class = route.response_class
+ assert current_response_class, "A response class is needed to generate OpenAPI"
+ route_response_media_type: Optional[str] = current_response_class.media_type
+ if route.include_in_schema:
+ for method in route.methods:
+ operation = get_openapi_operation_metadata(
+ route=route, method=method, operation_ids=operation_ids
+ )
+ parameters: List[Dict[str, Any]] = []
+ flat_dependant = get_flat_dependant(route.dependant, skip_repeats=True)
+ security_definitions, operation_security = get_openapi_security_definitions(
+ flat_dependant=flat_dependant
+ )
+ if operation_security:
+ operation.setdefault("security", []).extend(operation_security)
+ if security_definitions:
+ security_schemes.update(security_definitions)
+ all_route_params = get_flat_params(route.dependant)
+ operation_parameters = get_openapi_operation_parameters(
+ all_route_params=all_route_params,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ parameters.extend(operation_parameters)
+ if parameters:
+ all_parameters = {
+ (param["in"], param["name"]): param for param in parameters
+ }
+ required_parameters = {
+ (param["in"], param["name"]): param
+ for param in parameters
+ if param.get("required")
+ }
+ # Make sure required definitions of the same parameter take precedence
+ # over non-required definitions
+ all_parameters.update(required_parameters)
+ operation["parameters"] = list(all_parameters.values())
+ if method in METHODS_WITH_BODY:
+ request_body_oai = get_openapi_operation_request_body(
+ body_field=route.body_field,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ if request_body_oai:
+ operation["requestBody"] = request_body_oai
+ if route.callbacks:
+ callbacks = {}
+ for callback in route.callbacks:
+ if isinstance(callback, routing.APIRoute):
+ (
+ cb_path,
+ cb_security_schemes,
+ cb_definitions,
+ ) = get_openapi_path(
+ route=callback,
+ operation_ids=operation_ids,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ callbacks[callback.name] = {callback.path: cb_path}
+ operation["callbacks"] = callbacks
+ if route.status_code is not None:
+ status_code = str(route.status_code)
+ else:
+ # It would probably make more sense for all response classes to have an
+ # explicit default status_code, and to extract it from them, instead of
+ # doing this inspection tricks, that would probably be in the future
+ # TODO: probably make status_code a default class attribute for all
+ # responses in Starlette
+ response_signature = inspect.signature(current_response_class.__init__)
+ status_code_param = response_signature.parameters.get("status_code")
+ if status_code_param is not None:
+ if isinstance(status_code_param.default, int):
+ status_code = str(status_code_param.default)
+ operation.setdefault("responses", {}).setdefault(status_code, {})[
+ "description"
+ ] = route.response_description
+ if route_response_media_type and is_body_allowed_for_status_code(
+ route.status_code
+ ):
+ response_schema = {"type": "string"}
+ if lenient_issubclass(current_response_class, JSONResponse):
+ if route.response_field:
+ response_schema = get_schema_from_model_field(
+ field=route.response_field,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ else:
+ response_schema = {}
+ operation.setdefault("responses", {}).setdefault(
+ status_code, {}
+ ).setdefault("content", {}).setdefault(route_response_media_type, {})[
+ "schema"
+ ] = response_schema
+ if route.responses:
+ operation_responses = operation.setdefault("responses", {})
+ for (
+ additional_status_code,
+ additional_response,
+ ) in route.responses.items():
+ process_response = additional_response.copy()
+ process_response.pop("model", None)
+ status_code_key = str(additional_status_code).upper()
+ if status_code_key == "DEFAULT":
+ status_code_key = "default"
+ openapi_response = operation_responses.setdefault(
+ status_code_key, {}
+ )
+ assert isinstance(
+ process_response, dict
+ ), "An additional response must be a dict"
+ field = route.response_fields.get(additional_status_code)
+ additional_field_schema: Optional[Dict[str, Any]] = None
+ if field:
+ additional_field_schema = get_schema_from_model_field(
+ field=field,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ media_type = route_response_media_type or "application/json"
+ additional_schema = (
+ process_response.setdefault("content", {})
+ .setdefault(media_type, {})
+ .setdefault("schema", {})
+ )
+ deep_dict_update(additional_schema, additional_field_schema)
+ status_text: Optional[str] = status_code_ranges.get(
+ str(additional_status_code).upper()
+ ) or http.client.responses.get(int(additional_status_code))
+ description = (
+ process_response.get("description")
+ or openapi_response.get("description")
+ or status_text
+ or "Additional Response"
+ )
+ deep_dict_update(openapi_response, process_response)
+ openapi_response["description"] = description
+ http422 = str(HTTP_422_UNPROCESSABLE_ENTITY)
+ if (all_route_params or route.body_field) and not any(
+ status in operation["responses"]
+ for status in [http422, "4XX", "default"]
+ ):
+ operation["responses"][http422] = {
+ "description": "Validation Error",
+ "content": {
+ "application/json": {
+ "schema": {"$ref": REF_PREFIX + "HTTPValidationError"}
+ }
+ },
+ }
+ if "ValidationError" not in definitions:
+ definitions.update(
+ {
+ "ValidationError": validation_error_definition,
+ "HTTPValidationError": validation_error_response_definition,
+ }
+ )
+ if route.openapi_extra:
+ deep_dict_update(operation, route.openapi_extra)
+ path[method.lower()] = operation
+ return path, security_schemes, definitions
+
+
+def get_fields_from_routes(
+ routes: Sequence[BaseRoute],
+) -> List[ModelField]:
+ body_fields_from_routes: List[ModelField] = []
+ responses_from_routes: List[ModelField] = []
+ request_fields_from_routes: List[ModelField] = []
+ callback_flat_models: List[ModelField] = []
+ for route in routes:
+ if getattr(route, "include_in_schema", None) and isinstance(
+ route, routing.APIRoute
+ ):
+ if route.body_field:
+ assert isinstance(
+ route.body_field, ModelField
+ ), "A request body must be a Pydantic Field"
+ body_fields_from_routes.append(route.body_field)
+ if route.response_field:
+ responses_from_routes.append(route.response_field)
+ if route.response_fields:
+ responses_from_routes.extend(route.response_fields.values())
+ if route.callbacks:
+ callback_flat_models.extend(get_fields_from_routes(route.callbacks))
+ params = get_flat_params(route.dependant)
+ request_fields_from_routes.extend(params)
+
+ flat_models = callback_flat_models + list(
+ body_fields_from_routes + responses_from_routes + request_fields_from_routes
+ )
+ return flat_models
+
+
+def get_openapi(
+ *,
+ title: str,
+ version: str,
+ openapi_version: str = "3.1.0",
+ summary: Optional[str] = None,
+ description: Optional[str] = None,
+ routes: Sequence[BaseRoute],
+ webhooks: Optional[Sequence[BaseRoute]] = None,
+ tags: Optional[List[Dict[str, Any]]] = None,
+ servers: Optional[List[Dict[str, Union[str, Any]]]] = None,
+ terms_of_service: Optional[str] = None,
+ contact: Optional[Dict[str, Union[str, Any]]] = None,
+ license_info: Optional[Dict[str, Union[str, Any]]] = None,
+ separate_input_output_schemas: bool = True,
+) -> Dict[str, Any]:
+ info: Dict[str, Any] = {"title": title, "version": version}
+ if summary:
+ info["summary"] = summary
+ if description:
+ info["description"] = description
+ if terms_of_service:
+ info["termsOfService"] = terms_of_service
+ if contact:
+ info["contact"] = contact
+ if license_info:
+ info["license"] = license_info
+ output: Dict[str, Any] = {"openapi": openapi_version, "info": info}
+ if servers:
+ output["servers"] = servers
+ components: Dict[str, Dict[str, Any]] = {}
+ paths: Dict[str, Dict[str, Any]] = {}
+ webhook_paths: Dict[str, Dict[str, Any]] = {}
+ operation_ids: Set[str] = set()
+ all_fields = get_fields_from_routes(list(routes or []) + list(webhooks or []))
+ model_name_map = get_compat_model_name_map(all_fields)
+ schema_generator = GenerateJsonSchema(ref_template=REF_TEMPLATE)
+ field_mapping, definitions = get_definitions(
+ fields=all_fields,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ for route in routes or []:
+ if isinstance(route, routing.APIRoute):
+ result = get_openapi_path(
+ route=route,
+ operation_ids=operation_ids,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ if result:
+ path, security_schemes, path_definitions = result
+ if path:
+ paths.setdefault(route.path_format, {}).update(path)
+ if security_schemes:
+ components.setdefault("securitySchemes", {}).update(
+ security_schemes
+ )
+ if path_definitions:
+ definitions.update(path_definitions)
+ for webhook in webhooks or []:
+ if isinstance(webhook, routing.APIRoute):
+ result = get_openapi_path(
+ route=webhook,
+ operation_ids=operation_ids,
+ schema_generator=schema_generator,
+ model_name_map=model_name_map,
+ field_mapping=field_mapping,
+ separate_input_output_schemas=separate_input_output_schemas,
+ )
+ if result:
+ path, security_schemes, path_definitions = result
+ if path:
+ webhook_paths.setdefault(webhook.path_format, {}).update(path)
+ if security_schemes:
+ components.setdefault("securitySchemes", {}).update(
+ security_schemes
+ )
+ if path_definitions:
+ definitions.update(path_definitions)
+ if definitions:
+ components["schemas"] = {k: definitions[k] for k in sorted(definitions)}
+ if components:
+ output["components"] = components
+ output["paths"] = paths
+ if webhook_paths:
+ output["webhooks"] = webhook_paths
+ if tags:
+ output["tags"] = tags
+ return jsonable_encoder(OpenAPI(**output), by_alias=True, exclude_none=True) # type: ignore
diff --git a/fastapi/param_functions.py b/fastapi/param_functions.py
index 298d63fa..3b25d774 100644
--- a/fastapi/param_functions.py
+++ b/fastapi/param_functions.py
@@ -1,127 +1,1818 @@
from typing import Any, Callable, Dict, List, Optional, Sequence, Union
+
from fastapi import params
from fastapi._compat import Undefined
from fastapi.openapi.models import Example
from typing_extensions import Annotated, Doc, deprecated
+
_Unset: Any = Undefined
-def Path(default: Annotated[Any, Doc(
- """
- Default value if the parameter field is not set.
+def Path( # noqa: N802
+ default: Annotated[
+ Any,
+ Doc(
+ """
+ Default value if the parameter field is not set.
+
+ This doesn't affect `Path` parameters as the value is always required.
+ The parameter is available only for compatibility.
+ """
+ ),
+ ] = ...,
+ *,
+ default_factory: Annotated[
+ Union[Callable[[], Any], None],
+ Doc(
+ """
+ A callable to generate the default value.
+
+ This doesn't affect `Path` parameters as the value is always required.
+ The parameter is available only for compatibility.
+ """
+ ),
+ ] = _Unset,
+ alias: Annotated[
+ Optional[str],
+ Doc(
+ """
+ An alternative name for the parameter field.
+
+ This will be used to extract the data and for the generated OpenAPI.
+ It is particularly useful when you can't use the name you want because it
+ is a Python reserved keyword or similar.
+ """
+ ),
+ ] = None,
+ alias_priority: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Priority of the alias. This affects whether an alias generator is used.
+ """
+ ),
+ ] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Whitelist' validation step. The parameter field will be the single one
+ allowed by the alias or set of aliases defined.
+ """
+ ),
+ ] = None,
+ serialization_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Blacklist' validation step. The vanilla parameter field will be the
+ single one of the alias' or set of aliases' fields and all the other
+ fields will be ignored at serialization time.
+ """
+ ),
+ ] = None,
+ title: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable title.
+ """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable description.
+ """
+ ),
+ ] = None,
+ gt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than. If set, value must be greater than this. Only applicable to
+ numbers.
+ """
+ ),
+ ] = None,
+ ge: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than or equal. If set, value must be greater than or equal to
+ this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ lt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than. If set, value must be less than this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ le: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than or equal. If set, value must be less than or equal to this.
+ Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ min_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Minimum length for strings.
+ """
+ ),
+ ] = None,
+ max_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Maximum length for strings.
+ """
+ ),
+ ] = None,
+ pattern: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ ] = None,
+ regex: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ Parameter field name for discriminating the type in a tagged union.
+ """
+ ),
+ ] = None,
+ strict: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ If `True`, strict validation is applied to the field.
+ """
+ ),
+ ] = _Unset,
+ multiple_of: Annotated[
+ Union[float, None],
+ Doc(
+ """
+ Value must be a multiple of this. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ allow_inf_nan: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ max_digits: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of allow digits for strings.
+ """
+ ),
+ ] = _Unset,
+ decimal_places: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of decimal places allowed for numbers.
+ """
+ ),
+ ] = _Unset,
+ examples: Annotated[
+ Optional[List[Any]],
+ Doc(
+ """
+ Example values for this field.
+ """
+ ),
+ ] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Annotated[
+ Optional[Dict[str, Example]],
+ Doc(
+ """
+ OpenAPI-specific examples.
+
+ It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+ Swagger UI (that provides the `/docs` interface) has better support for the
+ OpenAPI-specific examples than the JSON Schema `examples`, that's the main
+ use case for this.
+
+ Read more about it in the
+ [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
+ """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Union[deprecated, str, bool, None],
+ Doc(
+ """
+ Mark this parameter field as deprecated.
+
+ It will affect the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
+ To include (or not) this parameter field in the generated OpenAPI.
+ You probably don't need it, but it's available.
+
+ This affects the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = True,
+ json_schema_extra: Annotated[
+ Union[Dict[str, Any], None],
+ Doc(
+ """
+ Any additional JSON schema data.
+ """
+ ),
+ ] = None,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
+ Include extra fields used by the JSON Schema.
+ """
+ ),
+ deprecated(
+ """
+ The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
+ """
+ ),
+ ],
+) -> Any:
+ """
+ Declare a path parameter for a *path operation*.
+
+ Read more about it in the
+ [FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/).
+
+ ```python
+ from typing import Annotated
+
+ from fastapi import FastAPI, Path
+
+ app = FastAPI()
+
+
+ @app.get("/items/{item_id}")
+ async def read_items(
+ item_id: Annotated[int, Path(title="The ID of the item to get")],
+ ):
+ return {"item_id": item_id}
+ ```
+ """
+ return params.Path(
+ default=default,
+ default_factory=default_factory,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
+
+
+def Query( # noqa: N802
+ default: Annotated[
+ Any,
+ Doc(
+ """
+ Default value if the parameter field is not set.
+ """
+ ),
+ ] = Undefined,
+ *,
+ default_factory: Annotated[
+ Union[Callable[[], Any], None],
+ Doc(
+ """
+ A callable to generate the default value.
+
+ This doesn't affect `Path` parameters as the value is always required.
+ The parameter is available only for compatibility.
+ """
+ ),
+ ] = _Unset,
+ alias: Annotated[
+ Optional[str],
+ Doc(
+ """
+ An alternative name for the parameter field.
+
+ This will be used to extract the data and for the generated OpenAPI.
+ It is particularly useful when you can't use the name you want because it
+ is a Python reserved keyword or similar.
+ """
+ ),
+ ] = None,
+ alias_priority: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Priority of the alias. This affects whether an alias generator is used.
+ """
+ ),
+ ] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Whitelist' validation step. The parameter field will be the single one
+ allowed by the alias or set of aliases defined.
+ """
+ ),
+ ] = None,
+ serialization_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Blacklist' validation step. The vanilla parameter field will be the
+ single one of the alias' or set of aliases' fields and all the other
+ fields will be ignored at serialization time.
+ """
+ ),
+ ] = None,
+ title: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable title.
+ """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable description.
+ """
+ ),
+ ] = None,
+ gt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than. If set, value must be greater than this. Only applicable to
+ numbers.
+ """
+ ),
+ ] = None,
+ ge: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than or equal. If set, value must be greater than or equal to
+ this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ lt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than. If set, value must be less than this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ le: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than or equal. If set, value must be less than or equal to this.
+ Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ min_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Minimum length for strings.
+ """
+ ),
+ ] = None,
+ max_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Maximum length for strings.
+ """
+ ),
+ ] = None,
+ pattern: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ ] = None,
+ regex: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ Parameter field name for discriminating the type in a tagged union.
+ """
+ ),
+ ] = None,
+ strict: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ If `True`, strict validation is applied to the field.
+ """
+ ),
+ ] = _Unset,
+ multiple_of: Annotated[
+ Union[float, None],
+ Doc(
+ """
+ Value must be a multiple of this. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ allow_inf_nan: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ max_digits: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of allow digits for strings.
+ """
+ ),
+ ] = _Unset,
+ decimal_places: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of decimal places allowed for numbers.
+ """
+ ),
+ ] = _Unset,
+ examples: Annotated[
+ Optional[List[Any]],
+ Doc(
+ """
+ Example values for this field.
+ """
+ ),
+ ] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Annotated[
+ Optional[Dict[str, Example]],
+ Doc(
+ """
+ OpenAPI-specific examples.
+
+ It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+ Swagger UI (that provides the `/docs` interface) has better support for the
+ OpenAPI-specific examples than the JSON Schema `examples`, that's the main
+ use case for this.
+
+ Read more about it in the
+ [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
+ """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Union[deprecated, str, bool, None],
+ Doc(
+ """
+ Mark this parameter field as deprecated.
+
+ It will affect the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
+ To include (or not) this parameter field in the generated OpenAPI.
+ You probably don't need it, but it's available.
+
+ This affects the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = True,
+ json_schema_extra: Annotated[
+ Union[Dict[str, Any], None],
+ Doc(
+ """
+ Any additional JSON schema data.
+ """
+ ),
+ ] = None,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
+ Include extra fields used by the JSON Schema.
+ """
+ ),
+ deprecated(
+ """
+ The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
+ """
+ ),
+ ],
+) -> Any:
+ return params.Query(
+ default=default,
+ default_factory=default_factory,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
+
+
+def Header( # noqa: N802
+ default: Annotated[
+ Any,
+ Doc(
+ """
+ Default value if the parameter field is not set.
+ """
+ ),
+ ] = Undefined,
+ *,
+ default_factory: Annotated[
+ Union[Callable[[], Any], None],
+ Doc(
+ """
+ A callable to generate the default value.
+
+ This doesn't affect `Path` parameters as the value is always required.
+ The parameter is available only for compatibility.
+ """
+ ),
+ ] = _Unset,
+ alias: Annotated[
+ Optional[str],
+ Doc(
+ """
+ An alternative name for the parameter field.
+
+ This will be used to extract the data and for the generated OpenAPI.
+ It is particularly useful when you can't use the name you want because it
+ is a Python reserved keyword or similar.
+ """
+ ),
+ ] = None,
+ alias_priority: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Priority of the alias. This affects whether an alias generator is used.
+ """
+ ),
+ ] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Whitelist' validation step. The parameter field will be the single one
+ allowed by the alias or set of aliases defined.
+ """
+ ),
+ ] = None,
+ serialization_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Blacklist' validation step. The vanilla parameter field will be the
+ single one of the alias' or set of aliases' fields and all the other
+ fields will be ignored at serialization time.
+ """
+ ),
+ ] = None,
+ convert_underscores: Annotated[
+ bool,
+ Doc(
+ """
+ Automatically convert underscores to hyphens in the parameter field name.
+
+ Read more about it in the
+ [FastAPI docs for Header Parameters](https://fastapi.tiangolo.com/tutorial/header-params/#automatic-conversion)
+ """
+ ),
+ ] = True,
+ title: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable title.
+ """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable description.
+ """
+ ),
+ ] = None,
+ gt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than. If set, value must be greater than this. Only applicable to
+ numbers.
+ """
+ ),
+ ] = None,
+ ge: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than or equal. If set, value must be greater than or equal to
+ this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ lt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than. If set, value must be less than this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ le: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than or equal. If set, value must be less than or equal to this.
+ Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ min_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Minimum length for strings.
+ """
+ ),
+ ] = None,
+ max_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Maximum length for strings.
+ """
+ ),
+ ] = None,
+ pattern: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ ] = None,
+ regex: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ Parameter field name for discriminating the type in a tagged union.
+ """
+ ),
+ ] = None,
+ strict: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ If `True`, strict validation is applied to the field.
+ """
+ ),
+ ] = _Unset,
+ multiple_of: Annotated[
+ Union[float, None],
+ Doc(
+ """
+ Value must be a multiple of this. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ allow_inf_nan: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ max_digits: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of allow digits for strings.
+ """
+ ),
+ ] = _Unset,
+ decimal_places: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of decimal places allowed for numbers.
+ """
+ ),
+ ] = _Unset,
+ examples: Annotated[
+ Optional[List[Any]],
+ Doc(
+ """
+ Example values for this field.
+ """
+ ),
+ ] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Annotated[
+ Optional[Dict[str, Example]],
+ Doc(
+ """
+ OpenAPI-specific examples.
+
+ It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+ Swagger UI (that provides the `/docs` interface) has better support for the
+ OpenAPI-specific examples than the JSON Schema `examples`, that's the main
+ use case for this.
+
+ Read more about it in the
+ [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
+ """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Union[deprecated, str, bool, None],
+ Doc(
+ """
+ Mark this parameter field as deprecated.
+
+ It will affect the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
+ To include (or not) this parameter field in the generated OpenAPI.
+ You probably don't need it, but it's available.
+
+ This affects the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = True,
+ json_schema_extra: Annotated[
+ Union[Dict[str, Any], None],
+ Doc(
+ """
+ Any additional JSON schema data.
+ """
+ ),
+ ] = None,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
+ Include extra fields used by the JSON Schema.
+ """
+ ),
+ deprecated(
+ """
+ The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
+ """
+ ),
+ ],
+) -> Any:
+ return params.Header(
+ default=default,
+ default_factory=default_factory,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ convert_underscores=convert_underscores,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
+
+
+def Cookie( # noqa: N802
+ default: Annotated[
+ Any,
+ Doc(
+ """
+ Default value if the parameter field is not set.
+ """
+ ),
+ ] = Undefined,
+ *,
+ default_factory: Annotated[
+ Union[Callable[[], Any], None],
+ Doc(
+ """
+ A callable to generate the default value.
+
+ This doesn't affect `Path` parameters as the value is always required.
+ The parameter is available only for compatibility.
+ """
+ ),
+ ] = _Unset,
+ alias: Annotated[
+ Optional[str],
+ Doc(
+ """
+ An alternative name for the parameter field.
+
+ This will be used to extract the data and for the generated OpenAPI.
+ It is particularly useful when you can't use the name you want because it
+ is a Python reserved keyword or similar.
+ """
+ ),
+ ] = None,
+ alias_priority: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Priority of the alias. This affects whether an alias generator is used.
+ """
+ ),
+ ] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Whitelist' validation step. The parameter field will be the single one
+ allowed by the alias or set of aliases defined.
+ """
+ ),
+ ] = None,
+ serialization_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Blacklist' validation step. The vanilla parameter field will be the
+ single one of the alias' or set of aliases' fields and all the other
+ fields will be ignored at serialization time.
+ """
+ ),
+ ] = None,
+ title: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable title.
+ """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable description.
+ """
+ ),
+ ] = None,
+ gt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than. If set, value must be greater than this. Only applicable to
+ numbers.
+ """
+ ),
+ ] = None,
+ ge: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than or equal. If set, value must be greater than or equal to
+ this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ lt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than. If set, value must be less than this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ le: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than or equal. If set, value must be less than or equal to this.
+ Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ min_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Minimum length for strings.
+ """
+ ),
+ ] = None,
+ max_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Maximum length for strings.
+ """
+ ),
+ ] = None,
+ pattern: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ ] = None,
+ regex: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ Parameter field name for discriminating the type in a tagged union.
+ """
+ ),
+ ] = None,
+ strict: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ If `True`, strict validation is applied to the field.
+ """
+ ),
+ ] = _Unset,
+ multiple_of: Annotated[
+ Union[float, None],
+ Doc(
+ """
+ Value must be a multiple of this. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ allow_inf_nan: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ max_digits: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of allow digits for strings.
+ """
+ ),
+ ] = _Unset,
+ decimal_places: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of decimal places allowed for numbers.
+ """
+ ),
+ ] = _Unset,
+ examples: Annotated[
+ Optional[List[Any]],
+ Doc(
+ """
+ Example values for this field.
+ """
+ ),
+ ] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Annotated[
+ Optional[Dict[str, Example]],
+ Doc(
+ """
+ OpenAPI-specific examples.
+
+ It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+ Swagger UI (that provides the `/docs` interface) has better support for the
+ OpenAPI-specific examples than the JSON Schema `examples`, that's the main
+ use case for this.
+
+ Read more about it in the
+ [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
+ """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Union[deprecated, str, bool, None],
+ Doc(
+ """
+ Mark this parameter field as deprecated.
+
+ It will affect the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
+ To include (or not) this parameter field in the generated OpenAPI.
+ You probably don't need it, but it's available.
+
+ This affects the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = True,
+ json_schema_extra: Annotated[
+ Union[Dict[str, Any], None],
+ Doc(
+ """
+ Any additional JSON schema data.
+ """
+ ),
+ ] = None,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
+ Include extra fields used by the JSON Schema.
+ """
+ ),
+ deprecated(
+ """
+ The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
+ """
+ ),
+ ],
+) -> Any:
+ return params.Cookie(
+ default=default,
+ default_factory=default_factory,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
+
+
+def Body( # noqa: N802
+ default: Annotated[
+ Any,
+ Doc(
+ """
+ Default value if the parameter field is not set.
+ """
+ ),
+ ] = Undefined,
+ *,
+ default_factory: Annotated[
+ Union[Callable[[], Any], None],
+ Doc(
+ """
+ A callable to generate the default value.
+
+ This doesn't affect `Path` parameters as the value is always required.
+ The parameter is available only for compatibility.
+ """
+ ),
+ ] = _Unset,
+ embed: Annotated[
+ bool,
+ Doc(
+ """
+ When `embed` is `True`, the parameter will be expected in a JSON body as a
+ key instead of being the JSON body itself.
+
+ This happens automatically when more than one `Body` parameter is declared.
+
+ Read more about it in the
+ [FastAPI docs for Body - Multiple Parameters](https://fastapi.tiangolo.com/tutorial/body-multiple-params/#embed-a-single-body-parameter).
+ """
+ ),
+ ] = False,
+ media_type: Annotated[
+ str,
+ Doc(
+ """
+ The media type of this parameter field. Changing it would affect the
+ generated OpenAPI, but currently it doesn't affect the parsing of the data.
+ """
+ ),
+ ] = "application/json",
+ alias: Annotated[
+ Optional[str],
+ Doc(
+ """
+ An alternative name for the parameter field.
+
+ This will be used to extract the data and for the generated OpenAPI.
+ It is particularly useful when you can't use the name you want because it
+ is a Python reserved keyword or similar.
+ """
+ ),
+ ] = None,
+ alias_priority: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Priority of the alias. This affects whether an alias generator is used.
+ """
+ ),
+ ] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Whitelist' validation step. The parameter field will be the single one
+ allowed by the alias or set of aliases defined.
+ """
+ ),
+ ] = None,
+ serialization_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Blacklist' validation step. The vanilla parameter field will be the
+ single one of the alias' or set of aliases' fields and all the other
+ fields will be ignored at serialization time.
+ """
+ ),
+ ] = None,
+ title: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable title.
+ """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable description.
+ """
+ ),
+ ] = None,
+ gt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than. If set, value must be greater than this. Only applicable to
+ numbers.
+ """
+ ),
+ ] = None,
+ ge: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than or equal. If set, value must be greater than or equal to
+ this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ lt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than. If set, value must be less than this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ le: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than or equal. If set, value must be less than or equal to this.
+ Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ min_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Minimum length for strings.
+ """
+ ),
+ ] = None,
+ max_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Maximum length for strings.
+ """
+ ),
+ ] = None,
+ pattern: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ ] = None,
+ regex: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ Parameter field name for discriminating the type in a tagged union.
+ """
+ ),
+ ] = None,
+ strict: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ If `True`, strict validation is applied to the field.
+ """
+ ),
+ ] = _Unset,
+ multiple_of: Annotated[
+ Union[float, None],
+ Doc(
+ """
+ Value must be a multiple of this. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ allow_inf_nan: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ max_digits: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of allow digits for strings.
+ """
+ ),
+ ] = _Unset,
+ decimal_places: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of decimal places allowed for numbers.
+ """
+ ),
+ ] = _Unset,
+ examples: Annotated[
+ Optional[List[Any]],
+ Doc(
+ """
+ Example values for this field.
+ """
+ ),
+ ] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Annotated[
+ Optional[Dict[str, Example]],
+ Doc(
+ """
+ OpenAPI-specific examples.
+
+ It will be added to the generated OpenAPI (e.g. visible at `/docs`).
+
+ Swagger UI (that provides the `/docs` interface) has better support for the
+ OpenAPI-specific examples than the JSON Schema `examples`, that's the main
+ use case for this.
- This doesn't affect `Path` parameters as the value is always required.
- The parameter is available only for compatibility.
+ Read more about it in the
+ [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
+ """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Union[deprecated, str, bool, None],
+ Doc(
+ """
+ Mark this parameter field as deprecated.
+
+ It will affect the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
+ To include (or not) this parameter field in the generated OpenAPI.
+ You probably don't need it, but it's available.
+
+ This affects the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = True,
+ json_schema_extra: Annotated[
+ Union[Dict[str, Any], None],
+ Doc(
+ """
+ Any additional JSON schema data.
+ """
+ ),
+ ] = None,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
+ Include extra fields used by the JSON Schema.
+ """
+ ),
+ deprecated(
+ """
+ The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
+ """
+ ),
+ ],
+) -> Any:
+ return params.Body(
+ default=default,
+ default_factory=default_factory,
+ embed=embed,
+ media_type=media_type,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
+
+
+def Form( # noqa: N802
+ default: Annotated[
+ Any,
+ Doc(
+ """
+ Default value if the parameter field is not set.
+ """
+ ),
+ ] = Undefined,
+ *,
+ default_factory: Annotated[
+ Union[Callable[[], Any], None],
+ Doc(
"""
- )]=..., *, default_factory: Annotated[Union[Callable[[], Any], None],
- Doc(
- """
A callable to generate the default value.
This doesn't affect `Path` parameters as the value is always required.
The parameter is available only for compatibility.
"""
- )]=_Unset, alias: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = _Unset,
+ media_type: Annotated[
+ str,
+ Doc(
+ """
+ The media type of this parameter field. Changing it would affect the
+ generated OpenAPI, but currently it doesn't affect the parsing of the data.
+ """
+ ),
+ ] = "application/x-www-form-urlencoded",
+ alias: Annotated[
+ Optional[str],
+ Doc(
+ """
An alternative name for the parameter field.
This will be used to extract the data and for the generated OpenAPI.
It is particularly useful when you can't use the name you want because it
is a Python reserved keyword or similar.
"""
- )]=None, alias_priority: Annotated[Union[int, None], Doc(
- """
+ ),
+ ] = None,
+ alias_priority: Annotated[
+ Union[int, None],
+ Doc(
+ """
Priority of the alias. This affects whether an alias generator is used.
"""
- )]=_Unset, validation_alias: Annotated[Union[str, None], Doc(
- """
+ ),
+ ] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
'Whitelist' validation step. The parameter field will be the single one
allowed by the alias or set of aliases defined.
"""
- )]=None, serialization_alias: Annotated[Union[str, None], Doc(
- """
+ ),
+ ] = None,
+ serialization_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
'Blacklist' validation step. The vanilla parameter field will be the
single one of the alias' or set of aliases' fields and all the other
fields will be ignored at serialization time.
"""
- )]=None, title: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ title: Annotated[
+ Optional[str],
+ Doc(
+ """
Human-readable title.
- """)]=None,
- description: Annotated[Optional[str], Doc(
- """
+ """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Human-readable description.
- """)]=None, gt:
- Annotated[Optional[float], Doc(
- """
+ """
+ ),
+ ] = None,
+ gt: Annotated[
+ Optional[float],
+ Doc(
+ """
Greater than. If set, value must be greater than this. Only applicable to
numbers.
"""
- )]=None, ge: Annotated[Optional[float], Doc(
- """
+ ),
+ ] = None,
+ ge: Annotated[
+ Optional[float],
+ Doc(
+ """
Greater than or equal. If set, value must be greater than or equal to
this. Only applicable to numbers.
"""
- )]=None, lt: Annotated[Optional[float], Doc(
- """
+ ),
+ ] = None,
+ lt: Annotated[
+ Optional[float],
+ Doc(
+ """
Less than. If set, value must be less than this. Only applicable to numbers.
"""
- )]=None, le: Annotated[Optional[float], Doc(
- """
+ ),
+ ] = None,
+ le: Annotated[
+ Optional[float],
+ Doc(
+ """
Less than or equal. If set, value must be less than or equal to this.
Only applicable to numbers.
"""
- )]=None, min_length: Annotated[Optional[int], Doc(
- """
+ ),
+ ] = None,
+ min_length: Annotated[
+ Optional[int],
+ Doc(
+ """
Minimum length for strings.
- """)]=None,
- max_length: Annotated[Optional[int], Doc(
- """
+ """
+ ),
+ ] = None,
+ max_length: Annotated[
+ Optional[int],
+ Doc(
+ """
Maximum length for strings.
- """)]=None,
- pattern: Annotated[Optional[str], Doc(
- """
+ """
+ ),
+ ] = None,
+ pattern: Annotated[
+ Optional[str],
+ Doc(
+ """
RegEx pattern for strings.
- """)]=None,
- regex: Annotated[Optional[str], Doc(
- """
+ """
+ ),
+ ] = None,
+ regex: Annotated[
+ Optional[str],
+ Doc(
+ """
RegEx pattern for strings.
- """), deprecated
- (
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Annotated[Union[str, None], Doc(
- """
+ """
+ ),
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Annotated[
+ Union[str, None],
+ Doc(
+ """
Parameter field name for discriminating the type in a tagged union.
"""
- )]=None, strict: Annotated[Union[bool, None], Doc(
- """
+ ),
+ ] = None,
+ strict: Annotated[
+ Union[bool, None],
+ Doc(
+ """
If `True`, strict validation is applied to the field.
"""
- )]=_Unset, multiple_of: Annotated[Union[float, None], Doc(
- """
+ ),
+ ] = _Unset,
+ multiple_of: Annotated[
+ Union[float, None],
+ Doc(
+ """
Value must be a multiple of this. Only applicable to numbers.
"""
- )]=_Unset, allow_inf_nan: Annotated[Union[bool, None], Doc(
- """
+ ),
+ ] = _Unset,
+ allow_inf_nan: Annotated[
+ Union[bool, None],
+ Doc(
+ """
Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
"""
- )]=_Unset, max_digits: Annotated[Union[int, None], Doc(
- """
+ ),
+ ] = _Unset,
+ max_digits: Annotated[
+ Union[int, None],
+ Doc(
+ """
Maximum number of allow digits for strings.
"""
- )]=_Unset, decimal_places: Annotated[Union[int, None], Doc(
- """
+ ),
+ ] = _Unset,
+ decimal_places: Annotated[
+ Union[int, None],
+ Doc(
+ """
Maximum number of decimal places allowed for numbers.
"""
- )]=_Unset, examples: Annotated[Optional[List[Any]], Doc(
- """
+ ),
+ ] = _Unset,
+ examples: Annotated[
+ Optional[List[Any]],
+ Doc(
+ """
Example values for this field.
- """)]=None,
- example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Annotated[Optional[Dict[str, Example]],
- Doc(
- """
+ """
+ ),
+ ] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Annotated[
+ Optional[Dict[str, Example]],
+ Doc(
+ """
OpenAPI-specific examples.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -133,65 +1824,416 @@ def Path(default: Annotated[Any, Doc(
Read more about it in the
[FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
"""
- )]=None, deprecated: Annotated[Union[deprecated, str, bool, None], Doc(
- """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Union[deprecated, str, bool, None],
+ Doc(
+ """
Mark this parameter field as deprecated.
It will affect the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, include_in_schema: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
To include (or not) this parameter field in the generated OpenAPI.
You probably don't need it, but it's available.
This affects the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=True, json_schema_extra: Annotated[Union[Dict[str, Any], None], Doc(
- """
+ ),
+ ] = True,
+ json_schema_extra: Annotated[
+ Union[Dict[str, Any], None],
+ Doc(
+ """
Any additional JSON schema data.
- """)]=None,
- **extra: Annotated[Any, Doc(
- """
+ """
+ ),
+ ] = None,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
Include extra fields used by the JSON Schema.
"""
- ), deprecated(
- """
+ ),
+ deprecated(
+ """
The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
"""
- )]) ->Any:
- """
- Declare a path parameter for a *path operation*.
+ ),
+ ],
+) -> Any:
+ return params.Form(
+ default=default,
+ default_factory=default_factory,
+ media_type=media_type,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
- Read more about it in the
- [FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/).
- ```python
- from typing import Annotated
+def File( # noqa: N802
+ default: Annotated[
+ Any,
+ Doc(
+ """
+ Default value if the parameter field is not set.
+ """
+ ),
+ ] = Undefined,
+ *,
+ default_factory: Annotated[
+ Union[Callable[[], Any], None],
+ Doc(
+ """
+ A callable to generate the default value.
- from fastapi import FastAPI, Path
+ This doesn't affect `Path` parameters as the value is always required.
+ The parameter is available only for compatibility.
+ """
+ ),
+ ] = _Unset,
+ media_type: Annotated[
+ str,
+ Doc(
+ """
+ The media type of this parameter field. Changing it would affect the
+ generated OpenAPI, but currently it doesn't affect the parsing of the data.
+ """
+ ),
+ ] = "multipart/form-data",
+ alias: Annotated[
+ Optional[str],
+ Doc(
+ """
+ An alternative name for the parameter field.
- app = FastAPI()
+ This will be used to extract the data and for the generated OpenAPI.
+ It is particularly useful when you can't use the name you want because it
+ is a Python reserved keyword or similar.
+ """
+ ),
+ ] = None,
+ alias_priority: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Priority of the alias. This affects whether an alias generator is used.
+ """
+ ),
+ ] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Whitelist' validation step. The parameter field will be the single one
+ allowed by the alias or set of aliases defined.
+ """
+ ),
+ ] = None,
+ serialization_alias: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ 'Blacklist' validation step. The vanilla parameter field will be the
+ single one of the alias' or set of aliases' fields and all the other
+ fields will be ignored at serialization time.
+ """
+ ),
+ ] = None,
+ title: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable title.
+ """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
+ Human-readable description.
+ """
+ ),
+ ] = None,
+ gt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than. If set, value must be greater than this. Only applicable to
+ numbers.
+ """
+ ),
+ ] = None,
+ ge: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Greater than or equal. If set, value must be greater than or equal to
+ this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ lt: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than. If set, value must be less than this. Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ le: Annotated[
+ Optional[float],
+ Doc(
+ """
+ Less than or equal. If set, value must be less than or equal to this.
+ Only applicable to numbers.
+ """
+ ),
+ ] = None,
+ min_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Minimum length for strings.
+ """
+ ),
+ ] = None,
+ max_length: Annotated[
+ Optional[int],
+ Doc(
+ """
+ Maximum length for strings.
+ """
+ ),
+ ] = None,
+ pattern: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ ] = None,
+ regex: Annotated[
+ Optional[str],
+ Doc(
+ """
+ RegEx pattern for strings.
+ """
+ ),
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Annotated[
+ Union[str, None],
+ Doc(
+ """
+ Parameter field name for discriminating the type in a tagged union.
+ """
+ ),
+ ] = None,
+ strict: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ If `True`, strict validation is applied to the field.
+ """
+ ),
+ ] = _Unset,
+ multiple_of: Annotated[
+ Union[float, None],
+ Doc(
+ """
+ Value must be a multiple of this. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ allow_inf_nan: Annotated[
+ Union[bool, None],
+ Doc(
+ """
+ Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
+ """
+ ),
+ ] = _Unset,
+ max_digits: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of allow digits for strings.
+ """
+ ),
+ ] = _Unset,
+ decimal_places: Annotated[
+ Union[int, None],
+ Doc(
+ """
+ Maximum number of decimal places allowed for numbers.
+ """
+ ),
+ ] = _Unset,
+ examples: Annotated[
+ Optional[List[Any]],
+ Doc(
+ """
+ Example values for this field.
+ """
+ ),
+ ] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Annotated[
+ Optional[Dict[str, Example]],
+ Doc(
+ """
+ OpenAPI-specific examples.
+ It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- @app.get("/items/{item_id}")
- async def read_items(
- item_id: Annotated[int, Path(title="The ID of the item to get")],
- ):
- return {"item_id": item_id}
- ```
- """
- pass
+ Swagger UI (that provides the `/docs` interface) has better support for the
+ OpenAPI-specific examples than the JSON Schema `examples`, that's the main
+ use case for this.
+
+ Read more about it in the
+ [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
+ """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Union[deprecated, str, bool, None],
+ Doc(
+ """
+ Mark this parameter field as deprecated.
+ It will affect the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
+ To include (or not) this parameter field in the generated OpenAPI.
+ You probably don't need it, but it's available.
-def Depends(dependency: Annotated[Optional[Callable[..., Any]], Doc(
- """
+ This affects the generated OpenAPI (e.g. visible at `/docs`).
+ """
+ ),
+ ] = True,
+ json_schema_extra: Annotated[
+ Union[Dict[str, Any], None],
+ Doc(
+ """
+ Any additional JSON schema data.
+ """
+ ),
+ ] = None,
+ **extra: Annotated[
+ Any,
+ Doc(
+ """
+ Include extra fields used by the JSON Schema.
+ """
+ ),
+ deprecated(
+ """
+ The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
+ """
+ ),
+ ],
+) -> Any:
+ return params.File(
+ default=default,
+ default_factory=default_factory,
+ media_type=media_type,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ deprecated=deprecated,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
+
+
+def Depends( # noqa: N802
+ dependency: Annotated[
+ Optional[Callable[..., Any]],
+ Doc(
+ """
A "dependable" callable (like a function).
Don't call it directly, FastAPI will call it for you, just pass the object
directly.
"""
- )]=None, *, use_cache: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ *,
+ use_cache: Annotated[
+ bool,
+ Doc(
+ """
By default, after a dependency is called the first time in a request, if
the dependency is declared again for the rest of the request (for example
if the dependency is needed by several dependencies), the value will be
@@ -200,7 +2242,9 @@ def Depends(dependency: Annotated[Optional[Callable[..., Any]], Doc(
Set `use_cache` to `False` to disable this behavior and ensure the
dependency is called again (if declared more than once) in the same request.
"""
- )]=True) ->Any:
+ ),
+ ] = True,
+) -> Any:
"""
Declare a FastAPI dependency.
@@ -230,18 +2274,26 @@ def Depends(dependency: Annotated[Optional[Callable[..., Any]], Doc(
return commons
```
"""
- pass
+ return params.Depends(dependency=dependency, use_cache=use_cache)
-def Security(dependency: Annotated[Optional[Callable[..., Any]], Doc(
- """
+def Security( # noqa: N802
+ dependency: Annotated[
+ Optional[Callable[..., Any]],
+ Doc(
+ """
A "dependable" callable (like a function).
Don't call it directly, FastAPI will call it for you, just pass the object
directly.
"""
- )]=None, *, scopes: Annotated[Optional[Sequence[str]], Doc(
- """
+ ),
+ ] = None,
+ *,
+ scopes: Annotated[
+ Optional[Sequence[str]],
+ Doc(
+ """
OAuth2 scopes required for the *path operation* that uses this Security
dependency.
@@ -253,8 +2305,12 @@ def Security(dependency: Annotated[Optional[Callable[..., Any]], Doc(
So they are visible in the OpenAPI specification.
)
"""
- )]=None, use_cache: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ use_cache: Annotated[
+ bool,
+ Doc(
+ """
By default, after a dependency is called the first time in a request, if
the dependency is declared again for the rest of the request (for example
if the dependency is needed by several dependencies), the value will be
@@ -263,7 +2319,9 @@ def Security(dependency: Annotated[Optional[Callable[..., Any]], Doc(
Set `use_cache` to `False` to disable this behavior and ensure the
dependency is called again (if declared more than once) in the same request.
"""
- )]=True) ->Any:
+ ),
+ ] = True,
+) -> Any:
"""
Declare a FastAPI Security dependency.
@@ -299,4 +2357,4 @@ def Security(dependency: Annotated[Optional[Callable[..., Any]], Doc(
return [{"item_id": "Foo", "owner": current_user.username}]
```
"""
- pass
+ return params.Security(dependency=dependency, scopes=scopes, use_cache=use_cache)
diff --git a/fastapi/params.py b/fastapi/params.py
index cebc920a..86014653 100644
--- a/fastapi/params.py
+++ b/fastapi/params.py
@@ -1,391 +1,783 @@
import warnings
from enum import Enum
from typing import Any, Callable, Dict, List, Optional, Sequence, Union
+
from fastapi.openapi.models import Example
from pydantic.fields import FieldInfo
from typing_extensions import Annotated, deprecated
+
from ._compat import PYDANTIC_V2, PYDANTIC_VERSION, Undefined
+
_Unset: Any = Undefined
class ParamTypes(Enum):
- query = 'query'
- header = 'header'
- path = 'path'
- cookie = 'cookie'
+ query = "query"
+ header = "header"
+ path = "path"
+ cookie = "cookie"
class Param(FieldInfo):
in_: ParamTypes
- def __init__(self, default: Any=Undefined, *, default_factory: Union[
- Callable[[], Any], None]=_Unset, annotation: Optional[Any]=None,
- alias: Optional[str]=None, alias_priority: Union[int, None]=_Unset,
- validation_alias: Union[str, None]=None, serialization_alias: Union
- [str, None]=None, title: Optional[str]=None, description: Optional[
- str]=None, gt: Optional[float]=None, ge: Optional[float]=None, lt:
- Optional[float]=None, le: Optional[float]=None, min_length:
- Optional[int]=None, max_length: Optional[int]=None, pattern:
- Optional[str]=None, regex: Annotated[Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
+ def __init__(
+ self,
+ default: Any = Undefined,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
if example is not _Unset:
warnings.warn(
- '`example` has been deprecated, please use `examples` instead',
- category=DeprecationWarning, stacklevel=4)
+ "`example` has been deprecated, please use `examples` instead",
+ category=DeprecationWarning,
+ stacklevel=4,
+ )
self.example = example
self.include_in_schema = include_in_schema
self.openapi_examples = openapi_examples
- kwargs = dict(default=default, default_factory=default_factory,
- alias=alias, title=title, description=description, gt=gt, ge=ge,
- lt=lt, le=le, min_length=min_length, max_length=max_length,
- discriminator=discriminator, multiple_of=multiple_of, allow_nan
- =allow_inf_nan, max_digits=max_digits, decimal_places=
- decimal_places, **extra)
+ kwargs = dict(
+ default=default,
+ default_factory=default_factory,
+ alias=alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ discriminator=discriminator,
+ multiple_of=multiple_of,
+ allow_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ **extra,
+ )
if examples is not None:
- kwargs['examples'] = examples
+ kwargs["examples"] = examples
if regex is not None:
warnings.warn(
- '`regex` has been deprecated, please use `pattern` instead',
- category=DeprecationWarning, stacklevel=4)
+ "`regex` has been deprecated, please use `pattern` instead",
+ category=DeprecationWarning,
+ stacklevel=4,
+ )
current_json_schema_extra = json_schema_extra or extra
- if PYDANTIC_VERSION < '2.7.0':
+ if PYDANTIC_VERSION < "2.7.0":
self.deprecated = deprecated
else:
- kwargs['deprecated'] = deprecated
+ kwargs["deprecated"] = deprecated
if PYDANTIC_V2:
- kwargs.update({'annotation': annotation, 'alias_priority':
- alias_priority, 'validation_alias': validation_alias,
- 'serialization_alias': serialization_alias, 'strict':
- strict, 'json_schema_extra': current_json_schema_extra})
- kwargs['pattern'] = pattern or regex
+ kwargs.update(
+ {
+ "annotation": annotation,
+ "alias_priority": alias_priority,
+ "validation_alias": validation_alias,
+ "serialization_alias": serialization_alias,
+ "strict": strict,
+ "json_schema_extra": current_json_schema_extra,
+ }
+ )
+ kwargs["pattern"] = pattern or regex
else:
- kwargs['regex'] = pattern or regex
+ kwargs["regex"] = pattern or regex
kwargs.update(**current_json_schema_extra)
use_kwargs = {k: v for k, v in kwargs.items() if v is not _Unset}
+
super().__init__(**use_kwargs)
- def __repr__(self) ->str:
- return f'{self.__class__.__name__}({self.default})'
+ def __repr__(self) -> str:
+ return f"{self.__class__.__name__}({self.default})"
class Path(Param):
in_ = ParamTypes.path
- def __init__(self, default: Any=..., *, default_factory: Union[Callable
- [[], Any], None]=_Unset, annotation: Optional[Any]=None, alias:
- Optional[str]=None, alias_priority: Union[int, None]=_Unset,
- validation_alias: Union[str, None]=None, serialization_alias: Union
- [str, None]=None, title: Optional[str]=None, description: Optional[
- str]=None, gt: Optional[float]=None, ge: Optional[float]=None, lt:
- Optional[float]=None, le: Optional[float]=None, min_length:
- Optional[int]=None, max_length: Optional[int]=None, pattern:
- Optional[str]=None, regex: Annotated[Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
- assert default is ..., 'Path parameters cannot have a default value'
+ def __init__(
+ self,
+ default: Any = ...,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
+ assert default is ..., "Path parameters cannot have a default value"
self.in_ = self.in_
- super().__init__(default=default, default_factory=default_factory,
- annotation=annotation, alias=alias, alias_priority=
- alias_priority, validation_alias=validation_alias,
- serialization_alias=serialization_alias, title=title,
- description=description, gt=gt, ge=ge, lt=lt, le=le, min_length
- =min_length, max_length=max_length, pattern=pattern, regex=
- regex, discriminator=discriminator, strict=strict, multiple_of=
- multiple_of, allow_inf_nan=allow_inf_nan, max_digits=max_digits,
- decimal_places=decimal_places, deprecated=deprecated, example=
- example, examples=examples, openapi_examples=openapi_examples,
- include_in_schema=include_in_schema, json_schema_extra=
- json_schema_extra, **extra)
+ super().__init__(
+ default=default,
+ default_factory=default_factory,
+ annotation=annotation,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ deprecated=deprecated,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
class Query(Param):
in_ = ParamTypes.query
- def __init__(self, default: Any=Undefined, *, default_factory: Union[
- Callable[[], Any], None]=_Unset, annotation: Optional[Any]=None,
- alias: Optional[str]=None, alias_priority: Union[int, None]=_Unset,
- validation_alias: Union[str, None]=None, serialization_alias: Union
- [str, None]=None, title: Optional[str]=None, description: Optional[
- str]=None, gt: Optional[float]=None, ge: Optional[float]=None, lt:
- Optional[float]=None, le: Optional[float]=None, min_length:
- Optional[int]=None, max_length: Optional[int]=None, pattern:
- Optional[str]=None, regex: Annotated[Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
- super().__init__(default=default, default_factory=default_factory,
- annotation=annotation, alias=alias, alias_priority=
- alias_priority, validation_alias=validation_alias,
- serialization_alias=serialization_alias, title=title,
- description=description, gt=gt, ge=ge, lt=lt, le=le, min_length
- =min_length, max_length=max_length, pattern=pattern, regex=
- regex, discriminator=discriminator, strict=strict, multiple_of=
- multiple_of, allow_inf_nan=allow_inf_nan, max_digits=max_digits,
- decimal_places=decimal_places, deprecated=deprecated, example=
- example, examples=examples, openapi_examples=openapi_examples,
- include_in_schema=include_in_schema, json_schema_extra=
- json_schema_extra, **extra)
+ def __init__(
+ self,
+ default: Any = Undefined,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
+ super().__init__(
+ default=default,
+ default_factory=default_factory,
+ annotation=annotation,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ deprecated=deprecated,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
class Header(Param):
in_ = ParamTypes.header
- def __init__(self, default: Any=Undefined, *, default_factory: Union[
- Callable[[], Any], None]=_Unset, annotation: Optional[Any]=None,
- alias: Optional[str]=None, alias_priority: Union[int, None]=_Unset,
- validation_alias: Union[str, None]=None, serialization_alias: Union
- [str, None]=None, convert_underscores: bool=True, title: Optional[
- str]=None, description: Optional[str]=None, gt: Optional[float]=
- None, ge: Optional[float]=None, lt: Optional[float]=None, le:
- Optional[float]=None, min_length: Optional[int]=None, max_length:
- Optional[int]=None, pattern: Optional[str]=None, regex: Annotated[
- Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
+ def __init__(
+ self,
+ default: Any = Undefined,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ convert_underscores: bool = True,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
self.convert_underscores = convert_underscores
- super().__init__(default=default, default_factory=default_factory,
- annotation=annotation, alias=alias, alias_priority=
- alias_priority, validation_alias=validation_alias,
- serialization_alias=serialization_alias, title=title,
- description=description, gt=gt, ge=ge, lt=lt, le=le, min_length
- =min_length, max_length=max_length, pattern=pattern, regex=
- regex, discriminator=discriminator, strict=strict, multiple_of=
- multiple_of, allow_inf_nan=allow_inf_nan, max_digits=max_digits,
- decimal_places=decimal_places, deprecated=deprecated, example=
- example, examples=examples, openapi_examples=openapi_examples,
- include_in_schema=include_in_schema, json_schema_extra=
- json_schema_extra, **extra)
+ super().__init__(
+ default=default,
+ default_factory=default_factory,
+ annotation=annotation,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ deprecated=deprecated,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
class Cookie(Param):
in_ = ParamTypes.cookie
- def __init__(self, default: Any=Undefined, *, default_factory: Union[
- Callable[[], Any], None]=_Unset, annotation: Optional[Any]=None,
- alias: Optional[str]=None, alias_priority: Union[int, None]=_Unset,
- validation_alias: Union[str, None]=None, serialization_alias: Union
- [str, None]=None, title: Optional[str]=None, description: Optional[
- str]=None, gt: Optional[float]=None, ge: Optional[float]=None, lt:
- Optional[float]=None, le: Optional[float]=None, min_length:
- Optional[int]=None, max_length: Optional[int]=None, pattern:
- Optional[str]=None, regex: Annotated[Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
- super().__init__(default=default, default_factory=default_factory,
- annotation=annotation, alias=alias, alias_priority=
- alias_priority, validation_alias=validation_alias,
- serialization_alias=serialization_alias, title=title,
- description=description, gt=gt, ge=ge, lt=lt, le=le, min_length
- =min_length, max_length=max_length, pattern=pattern, regex=
- regex, discriminator=discriminator, strict=strict, multiple_of=
- multiple_of, allow_inf_nan=allow_inf_nan, max_digits=max_digits,
- decimal_places=decimal_places, deprecated=deprecated, example=
- example, examples=examples, openapi_examples=openapi_examples,
- include_in_schema=include_in_schema, json_schema_extra=
- json_schema_extra, **extra)
+ def __init__(
+ self,
+ default: Any = Undefined,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
+ super().__init__(
+ default=default,
+ default_factory=default_factory,
+ annotation=annotation,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ deprecated=deprecated,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
class Body(FieldInfo):
-
- def __init__(self, default: Any=Undefined, *, default_factory: Union[
- Callable[[], Any], None]=_Unset, annotation: Optional[Any]=None,
- embed: bool=False, media_type: str='application/json', alias:
- Optional[str]=None, alias_priority: Union[int, None]=_Unset,
- validation_alias: Union[str, None]=None, serialization_alias: Union
- [str, None]=None, title: Optional[str]=None, description: Optional[
- str]=None, gt: Optional[float]=None, ge: Optional[float]=None, lt:
- Optional[float]=None, le: Optional[float]=None, min_length:
- Optional[int]=None, max_length: Optional[int]=None, pattern:
- Optional[str]=None, regex: Annotated[Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
+ def __init__(
+ self,
+ default: Any = Undefined,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ embed: bool = False,
+ media_type: str = "application/json",
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
self.embed = embed
self.media_type = media_type
if example is not _Unset:
warnings.warn(
- '`example` has been deprecated, please use `examples` instead',
- category=DeprecationWarning, stacklevel=4)
+ "`example` has been deprecated, please use `examples` instead",
+ category=DeprecationWarning,
+ stacklevel=4,
+ )
self.example = example
self.include_in_schema = include_in_schema
self.openapi_examples = openapi_examples
- kwargs = dict(default=default, default_factory=default_factory,
- alias=alias, title=title, description=description, gt=gt, ge=ge,
- lt=lt, le=le, min_length=min_length, max_length=max_length,
- discriminator=discriminator, multiple_of=multiple_of, allow_nan
- =allow_inf_nan, max_digits=max_digits, decimal_places=
- decimal_places, **extra)
+ kwargs = dict(
+ default=default,
+ default_factory=default_factory,
+ alias=alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ discriminator=discriminator,
+ multiple_of=multiple_of,
+ allow_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ **extra,
+ )
if examples is not None:
- kwargs['examples'] = examples
+ kwargs["examples"] = examples
if regex is not None:
warnings.warn(
- '`regex` has been depreacated, please use `pattern` instead',
- category=DeprecationWarning, stacklevel=4)
+ "`regex` has been depreacated, please use `pattern` instead",
+ category=DeprecationWarning,
+ stacklevel=4,
+ )
current_json_schema_extra = json_schema_extra or extra
- if PYDANTIC_VERSION < '2.7.0':
+ if PYDANTIC_VERSION < "2.7.0":
self.deprecated = deprecated
else:
- kwargs['deprecated'] = deprecated
+ kwargs["deprecated"] = deprecated
if PYDANTIC_V2:
- kwargs.update({'annotation': annotation, 'alias_priority':
- alias_priority, 'validation_alias': validation_alias,
- 'serialization_alias': serialization_alias, 'strict':
- strict, 'json_schema_extra': current_json_schema_extra})
- kwargs['pattern'] = pattern or regex
+ kwargs.update(
+ {
+ "annotation": annotation,
+ "alias_priority": alias_priority,
+ "validation_alias": validation_alias,
+ "serialization_alias": serialization_alias,
+ "strict": strict,
+ "json_schema_extra": current_json_schema_extra,
+ }
+ )
+ kwargs["pattern"] = pattern or regex
else:
- kwargs['regex'] = pattern or regex
+ kwargs["regex"] = pattern or regex
kwargs.update(**current_json_schema_extra)
+
use_kwargs = {k: v for k, v in kwargs.items() if v is not _Unset}
+
super().__init__(**use_kwargs)
- def __repr__(self) ->str:
- return f'{self.__class__.__name__}({self.default})'
+ def __repr__(self) -> str:
+ return f"{self.__class__.__name__}({self.default})"
class Form(Body):
-
- def __init__(self, default: Any=Undefined, *, default_factory: Union[
- Callable[[], Any], None]=_Unset, annotation: Optional[Any]=None,
- media_type: str='application/x-www-form-urlencoded', alias:
- Optional[str]=None, alias_priority: Union[int, None]=_Unset,
- validation_alias: Union[str, None]=None, serialization_alias: Union
- [str, None]=None, title: Optional[str]=None, description: Optional[
- str]=None, gt: Optional[float]=None, ge: Optional[float]=None, lt:
- Optional[float]=None, le: Optional[float]=None, min_length:
- Optional[int]=None, max_length: Optional[int]=None, pattern:
- Optional[str]=None, regex: Annotated[Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
- super().__init__(default=default, default_factory=default_factory,
- annotation=annotation, embed=True, media_type=media_type, alias
- =alias, alias_priority=alias_priority, validation_alias=
- validation_alias, serialization_alias=serialization_alias,
- title=title, description=description, gt=gt, ge=ge, lt=lt, le=
- le, min_length=min_length, max_length=max_length, pattern=
- pattern, regex=regex, discriminator=discriminator, strict=
- strict, multiple_of=multiple_of, allow_inf_nan=allow_inf_nan,
- max_digits=max_digits, decimal_places=decimal_places,
- deprecated=deprecated, example=example, examples=examples,
- openapi_examples=openapi_examples, include_in_schema=
- include_in_schema, json_schema_extra=json_schema_extra, **extra)
+ def __init__(
+ self,
+ default: Any = Undefined,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ media_type: str = "application/x-www-form-urlencoded",
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
+ super().__init__(
+ default=default,
+ default_factory=default_factory,
+ annotation=annotation,
+ embed=True,
+ media_type=media_type,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ deprecated=deprecated,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
class File(Form):
-
- def __init__(self, default: Any=Undefined, *, default_factory: Union[
- Callable[[], Any], None]=_Unset, annotation: Optional[Any]=None,
- media_type: str='multipart/form-data', alias: Optional[str]=None,
- alias_priority: Union[int, None]=_Unset, validation_alias: Union[
- str, None]=None, serialization_alias: Union[str, None]=None, title:
- Optional[str]=None, description: Optional[str]=None, gt: Optional[
- float]=None, ge: Optional[float]=None, lt: Optional[float]=None, le:
- Optional[float]=None, min_length: Optional[int]=None, max_length:
- Optional[int]=None, pattern: Optional[str]=None, regex: Annotated[
- Optional[str], deprecated(
- 'Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead.'
- )]=None, discriminator: Union[str, None]=None, strict: Union[bool,
- None]=_Unset, multiple_of: Union[float, None]=_Unset, allow_inf_nan:
- Union[bool, None]=_Unset, max_digits: Union[int, None]=_Unset,
- decimal_places: Union[int, None]=_Unset, examples: Optional[List[
- Any]]=None, example: Annotated[Optional[Any], deprecated(
- 'Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, although still supported. Use examples instead.'
- )]=_Unset, openapi_examples: Optional[Dict[str, Example]]=None,
- deprecated: Union[deprecated, str, bool, None]=None,
- include_in_schema: bool=True, json_schema_extra: Union[Dict[str,
- Any], None]=None, **extra: Any):
- super().__init__(default=default, default_factory=default_factory,
- annotation=annotation, media_type=media_type, alias=alias,
- alias_priority=alias_priority, validation_alias=
- validation_alias, serialization_alias=serialization_alias,
- title=title, description=description, gt=gt, ge=ge, lt=lt, le=
- le, min_length=min_length, max_length=max_length, pattern=
- pattern, regex=regex, discriminator=discriminator, strict=
- strict, multiple_of=multiple_of, allow_inf_nan=allow_inf_nan,
- max_digits=max_digits, decimal_places=decimal_places,
- deprecated=deprecated, example=example, examples=examples,
- openapi_examples=openapi_examples, include_in_schema=
- include_in_schema, json_schema_extra=json_schema_extra, **extra)
+ def __init__(
+ self,
+ default: Any = Undefined,
+ *,
+ default_factory: Union[Callable[[], Any], None] = _Unset,
+ annotation: Optional[Any] = None,
+ media_type: str = "multipart/form-data",
+ alias: Optional[str] = None,
+ alias_priority: Union[int, None] = _Unset,
+ # TODO: update when deprecating Pydantic v1, import these types
+ # validation_alias: str | AliasPath | AliasChoices | None
+ validation_alias: Union[str, None] = None,
+ serialization_alias: Union[str, None] = None,
+ title: Optional[str] = None,
+ description: Optional[str] = None,
+ gt: Optional[float] = None,
+ ge: Optional[float] = None,
+ lt: Optional[float] = None,
+ le: Optional[float] = None,
+ min_length: Optional[int] = None,
+ max_length: Optional[int] = None,
+ pattern: Optional[str] = None,
+ regex: Annotated[
+ Optional[str],
+ deprecated(
+ "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
+ ),
+ ] = None,
+ discriminator: Union[str, None] = None,
+ strict: Union[bool, None] = _Unset,
+ multiple_of: Union[float, None] = _Unset,
+ allow_inf_nan: Union[bool, None] = _Unset,
+ max_digits: Union[int, None] = _Unset,
+ decimal_places: Union[int, None] = _Unset,
+ examples: Optional[List[Any]] = None,
+ example: Annotated[
+ Optional[Any],
+ deprecated(
+ "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
+ "although still supported. Use examples instead."
+ ),
+ ] = _Unset,
+ openapi_examples: Optional[Dict[str, Example]] = None,
+ deprecated: Union[deprecated, str, bool, None] = None,
+ include_in_schema: bool = True,
+ json_schema_extra: Union[Dict[str, Any], None] = None,
+ **extra: Any,
+ ):
+ super().__init__(
+ default=default,
+ default_factory=default_factory,
+ annotation=annotation,
+ media_type=media_type,
+ alias=alias,
+ alias_priority=alias_priority,
+ validation_alias=validation_alias,
+ serialization_alias=serialization_alias,
+ title=title,
+ description=description,
+ gt=gt,
+ ge=ge,
+ lt=lt,
+ le=le,
+ min_length=min_length,
+ max_length=max_length,
+ pattern=pattern,
+ regex=regex,
+ discriminator=discriminator,
+ strict=strict,
+ multiple_of=multiple_of,
+ allow_inf_nan=allow_inf_nan,
+ max_digits=max_digits,
+ decimal_places=decimal_places,
+ deprecated=deprecated,
+ example=example,
+ examples=examples,
+ openapi_examples=openapi_examples,
+ include_in_schema=include_in_schema,
+ json_schema_extra=json_schema_extra,
+ **extra,
+ )
class Depends:
-
- def __init__(self, dependency: Optional[Callable[..., Any]]=None, *,
- use_cache: bool=True):
+ def __init__(
+ self, dependency: Optional[Callable[..., Any]] = None, *, use_cache: bool = True
+ ):
self.dependency = dependency
self.use_cache = use_cache
- def __repr__(self) ->str:
- attr = getattr(self.dependency, '__name__', type(self.dependency).
- __name__)
- cache = '' if self.use_cache else ', use_cache=False'
- return f'{self.__class__.__name__}({attr}{cache})'
+ def __repr__(self) -> str:
+ attr = getattr(self.dependency, "__name__", type(self.dependency).__name__)
+ cache = "" if self.use_cache else ", use_cache=False"
+ return f"{self.__class__.__name__}({attr}{cache})"
class Security(Depends):
-
- def __init__(self, dependency: Optional[Callable[..., Any]]=None, *,
- scopes: Optional[Sequence[str]]=None, use_cache: bool=True):
+ def __init__(
+ self,
+ dependency: Optional[Callable[..., Any]] = None,
+ *,
+ scopes: Optional[Sequence[str]] = None,
+ use_cache: bool = True,
+ ):
super().__init__(dependency=dependency, use_cache=use_cache)
self.scopes = scopes or []
diff --git a/fastapi/requests.py b/fastapi/requests.py
index 931a2bfc..d16552c0 100644
--- a/fastapi/requests.py
+++ b/fastapi/requests.py
@@ -1,2 +1,2 @@
-from starlette.requests import HTTPConnection as HTTPConnection
-from starlette.requests import Request as Request
+from starlette.requests import HTTPConnection as HTTPConnection # noqa: F401
+from starlette.requests import Request as Request # noqa: F401
diff --git a/fastapi/responses.py b/fastapi/responses.py
index ae75b5a3..6c8db6f3 100644
--- a/fastapi/responses.py
+++ b/fastapi/responses.py
@@ -1,19 +1,23 @@
from typing import Any
-from starlette.responses import FileResponse as FileResponse
-from starlette.responses import HTMLResponse as HTMLResponse
-from starlette.responses import JSONResponse as JSONResponse
-from starlette.responses import PlainTextResponse as PlainTextResponse
-from starlette.responses import RedirectResponse as RedirectResponse
-from starlette.responses import Response as Response
-from starlette.responses import StreamingResponse as StreamingResponse
+
+from starlette.responses import FileResponse as FileResponse # noqa
+from starlette.responses import HTMLResponse as HTMLResponse # noqa
+from starlette.responses import JSONResponse as JSONResponse # noqa
+from starlette.responses import PlainTextResponse as PlainTextResponse # noqa
+from starlette.responses import RedirectResponse as RedirectResponse # noqa
+from starlette.responses import Response as Response # noqa
+from starlette.responses import StreamingResponse as StreamingResponse # noqa
+
try:
import ujson
-except ImportError:
- ujson = None
+except ImportError: # pragma: nocover
+ ujson = None # type: ignore
+
+
try:
import orjson
-except ImportError:
- orjson = None
+except ImportError: # pragma: nocover
+ orjson = None # type: ignore
class UJSONResponse(JSONResponse):
@@ -24,6 +28,10 @@ class UJSONResponse(JSONResponse):
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/).
"""
+ def render(self, content: Any) -> bytes:
+ assert ujson is not None, "ujson must be installed to use UJSONResponse"
+ return ujson.dumps(content, ensure_ascii=False).encode("utf-8")
+
class ORJSONResponse(JSONResponse):
"""
@@ -32,3 +40,9 @@ class ORJSONResponse(JSONResponse):
Read more about it in the
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/).
"""
+
+ def render(self, content: Any) -> bytes:
+ assert orjson is not None, "orjson must be installed to use ORJSONResponse"
+ return orjson.dumps(
+ content, option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SERIALIZE_NUMPY
+ )
diff --git a/fastapi/routing.py b/fastapi/routing.py
index b0e631f4..fa135185 100644
--- a/fastapi/routing.py
+++ b/fastapi/routing.py
@@ -5,72 +5,422 @@ import inspect
import json
from contextlib import AsyncExitStack
from enum import Enum, IntEnum
-from typing import Any, Callable, Coroutine, Dict, List, Optional, Sequence, Set, Tuple, Type, Union
+from typing import (
+ Any,
+ Callable,
+ Coroutine,
+ Dict,
+ List,
+ Optional,
+ Sequence,
+ Set,
+ Tuple,
+ Type,
+ Union,
+)
+
from fastapi import params
-from fastapi._compat import ModelField, Undefined, _get_model_config, _model_dump, _normalize_errors, lenient_issubclass
+from fastapi._compat import (
+ ModelField,
+ Undefined,
+ _get_model_config,
+ _model_dump,
+ _normalize_errors,
+ lenient_issubclass,
+)
from fastapi.datastructures import Default, DefaultPlaceholder
from fastapi.dependencies.models import Dependant
-from fastapi.dependencies.utils import get_body_field, get_dependant, get_parameterless_sub_dependant, get_typed_return_annotation, solve_dependencies
+from fastapi.dependencies.utils import (
+ get_body_field,
+ get_dependant,
+ get_parameterless_sub_dependant,
+ get_typed_return_annotation,
+ solve_dependencies,
+)
from fastapi.encoders import jsonable_encoder
-from fastapi.exceptions import FastAPIError, RequestValidationError, ResponseValidationError, WebSocketRequestValidationError
+from fastapi.exceptions import (
+ FastAPIError,
+ RequestValidationError,
+ ResponseValidationError,
+ WebSocketRequestValidationError,
+)
from fastapi.types import DecoratedCallable, IncEx
-from fastapi.utils import create_cloned_field, create_response_field, generate_unique_id, get_value_or_default, is_body_allowed_for_status_code
+from fastapi.utils import (
+ create_cloned_field,
+ create_response_field,
+ generate_unique_id,
+ get_value_or_default,
+ is_body_allowed_for_status_code,
+)
from pydantic import BaseModel
from starlette import routing
from starlette.concurrency import run_in_threadpool
from starlette.exceptions import HTTPException
from starlette.requests import Request
from starlette.responses import JSONResponse, Response
-from starlette.routing import BaseRoute, Match, compile_path, get_name, request_response, websocket_session
-from starlette.routing import Mount as Mount
+from starlette.routing import (
+ BaseRoute,
+ Match,
+ compile_path,
+ get_name,
+ request_response,
+ websocket_session,
+)
+from starlette.routing import Mount as Mount # noqa
from starlette.types import ASGIApp, Lifespan, Scope
from starlette.websockets import WebSocket
from typing_extensions import Annotated, Doc, deprecated
-class APIWebSocketRoute(routing.WebSocketRoute):
+def _prepare_response_content(
+ res: Any,
+ *,
+ exclude_unset: bool,
+ exclude_defaults: bool = False,
+ exclude_none: bool = False,
+) -> Any:
+ if isinstance(res, BaseModel):
+ read_with_orm_mode = getattr(_get_model_config(res), "read_with_orm_mode", None)
+ if read_with_orm_mode:
+ # Let from_orm extract the data from this model instead of converting
+ # it now to a dict.
+ # Otherwise, there's no way to extract lazy data that requires attribute
+ # access instead of dict iteration, e.g. lazy relationships.
+ return res
+ return _model_dump(
+ res,
+ by_alias=True,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ )
+ elif isinstance(res, list):
+ return [
+ _prepare_response_content(
+ item,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ )
+ for item in res
+ ]
+ elif isinstance(res, dict):
+ return {
+ k: _prepare_response_content(
+ v,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ )
+ for k, v in res.items()
+ }
+ elif dataclasses.is_dataclass(res):
+ return dataclasses.asdict(res)
+ return res
+
+
+async def serialize_response(
+ *,
+ field: Optional[ModelField] = None,
+ response_content: Any,
+ include: Optional[IncEx] = None,
+ exclude: Optional[IncEx] = None,
+ by_alias: bool = True,
+ exclude_unset: bool = False,
+ exclude_defaults: bool = False,
+ exclude_none: bool = False,
+ is_coroutine: bool = True,
+) -> Any:
+ if field:
+ errors = []
+ if not hasattr(field, "serialize"):
+ # pydantic v1
+ response_content = _prepare_response_content(
+ response_content,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ )
+ if is_coroutine:
+ value, errors_ = field.validate(response_content, {}, loc=("response",))
+ else:
+ value, errors_ = await run_in_threadpool(
+ field.validate, response_content, {}, loc=("response",)
+ )
+ if isinstance(errors_, list):
+ errors.extend(errors_)
+ elif errors_:
+ errors.append(errors_)
+ if errors:
+ raise ResponseValidationError(
+ errors=_normalize_errors(errors), body=response_content
+ )
+
+ if hasattr(field, "serialize"):
+ return field.serialize(
+ value,
+ include=include,
+ exclude=exclude,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ )
+
+ return jsonable_encoder(
+ value,
+ include=include,
+ exclude=exclude,
+ by_alias=by_alias,
+ exclude_unset=exclude_unset,
+ exclude_defaults=exclude_defaults,
+ exclude_none=exclude_none,
+ )
+ else:
+ return jsonable_encoder(response_content)
+
+
+async def run_endpoint_function(
+ *, dependant: Dependant, values: Dict[str, Any], is_coroutine: bool
+) -> Any:
+ # Only called by get_request_handler. Has been split into its own function to
+ # facilitate profiling endpoints, since inner functions are harder to profile.
+ assert dependant.call is not None, "dependant.call must be a function"
+
+ if is_coroutine:
+ return await dependant.call(**values)
+ else:
+ return await run_in_threadpool(dependant.call, **values)
+
+
+def get_request_handler(
+ dependant: Dependant,
+ body_field: Optional[ModelField] = None,
+ status_code: Optional[int] = None,
+ response_class: Union[Type[Response], DefaultPlaceholder] = Default(JSONResponse),
+ response_field: Optional[ModelField] = None,
+ response_model_include: Optional[IncEx] = None,
+ response_model_exclude: Optional[IncEx] = 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,
+ dependency_overrides_provider: Optional[Any] = None,
+) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+ assert dependant.call is not None, "dependant.call must be a function"
+ is_coroutine = asyncio.iscoroutinefunction(dependant.call)
+ is_body_form = body_field and isinstance(body_field.field_info, params.Form)
+ if isinstance(response_class, DefaultPlaceholder):
+ actual_response_class: Type[Response] = response_class.value
+ else:
+ actual_response_class = response_class
+
+ async def app(request: Request) -> Response:
+ response: Union[Response, None] = None
+ async with AsyncExitStack() as file_stack:
+ try:
+ body: Any = None
+ if body_field:
+ if is_body_form:
+ body = await request.form()
+ file_stack.push_async_callback(body.close)
+ else:
+ body_bytes = await request.body()
+ if body_bytes:
+ json_body: Any = Undefined
+ content_type_value = request.headers.get("content-type")
+ if not content_type_value:
+ json_body = await request.json()
+ else:
+ message = email.message.Message()
+ message["content-type"] = content_type_value
+ if message.get_content_maintype() == "application":
+ subtype = message.get_content_subtype()
+ if subtype == "json" or subtype.endswith("+json"):
+ json_body = await request.json()
+ if json_body != Undefined:
+ body = json_body
+ else:
+ body = body_bytes
+ except json.JSONDecodeError as e:
+ validation_error = RequestValidationError(
+ [
+ {
+ "type": "json_invalid",
+ "loc": ("body", e.pos),
+ "msg": "JSON decode error",
+ "input": {},
+ "ctx": {"error": e.msg},
+ }
+ ],
+ body=e.doc,
+ )
+ raise validation_error from e
+ except HTTPException:
+ # If a middleware raises an HTTPException, it should be raised again
+ raise
+ except Exception as e:
+ http_error = HTTPException(
+ status_code=400, detail="There was an error parsing the body"
+ )
+ raise http_error from e
+ errors: List[Any] = []
+ async with AsyncExitStack() as async_exit_stack:
+ solved_result = await solve_dependencies(
+ request=request,
+ dependant=dependant,
+ body=body,
+ dependency_overrides_provider=dependency_overrides_provider,
+ async_exit_stack=async_exit_stack,
+ )
+ values, errors, background_tasks, sub_response, _ = solved_result
+ if not errors:
+ raw_response = await run_endpoint_function(
+ dependant=dependant, values=values, is_coroutine=is_coroutine
+ )
+ if isinstance(raw_response, Response):
+ if raw_response.background is None:
+ raw_response.background = background_tasks
+ response = raw_response
+ else:
+ response_args: Dict[str, Any] = {"background": background_tasks}
+ # If status_code was set, use it, otherwise use the default from the
+ # response class, in the case of redirect it's 307
+ current_status_code = (
+ status_code if status_code else sub_response.status_code
+ )
+ if current_status_code is not None:
+ response_args["status_code"] = current_status_code
+ if sub_response.status_code:
+ response_args["status_code"] = sub_response.status_code
+ content = await serialize_response(
+ field=response_field,
+ response_content=raw_response,
+ include=response_model_include,
+ exclude=response_model_exclude,
+ by_alias=response_model_by_alias,
+ exclude_unset=response_model_exclude_unset,
+ exclude_defaults=response_model_exclude_defaults,
+ exclude_none=response_model_exclude_none,
+ is_coroutine=is_coroutine,
+ )
+ response = actual_response_class(content, **response_args)
+ if not is_body_allowed_for_status_code(response.status_code):
+ response.body = b""
+ response.headers.raw.extend(sub_response.headers.raw)
+ if errors:
+ validation_error = RequestValidationError(
+ _normalize_errors(errors), body=body
+ )
+ raise validation_error
+ if response is None:
+ raise FastAPIError(
+ "No response object was returned. There's a high chance that the "
+ "application code is raising an exception and a dependency with yield "
+ "has a block with a bare except, or a block with except Exception, "
+ "and is not raising the exception again. Read more about it in the "
+ "docs: https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#dependencies-with-yield-and-except"
+ )
+ return response
+
+ return app
+
+
+def get_websocket_app(
+ dependant: Dependant, dependency_overrides_provider: Optional[Any] = None
+) -> Callable[[WebSocket], Coroutine[Any, Any, Any]]:
+ async def app(websocket: WebSocket) -> None:
+ async with AsyncExitStack() as async_exit_stack:
+ # TODO: remove this scope later, after a few releases
+ # This scope fastapi_astack is no longer used by FastAPI, kept for
+ # compatibility, just in case
+ websocket.scope["fastapi_astack"] = async_exit_stack
+ solved_result = await solve_dependencies(
+ request=websocket,
+ dependant=dependant,
+ dependency_overrides_provider=dependency_overrides_provider,
+ async_exit_stack=async_exit_stack,
+ )
+ values, errors, _, _2, _3 = solved_result
+ if errors:
+ raise WebSocketRequestValidationError(_normalize_errors(errors))
+ assert dependant.call is not None, "dependant.call must be a function"
+ await dependant.call(**values)
+
+ return app
+
- def __init__(self, path: str, endpoint: Callable[..., Any], *, name:
- Optional[str]=None, dependencies: Optional[Sequence[params.Depends]
- ]=None, dependency_overrides_provider: Optional[Any]=None) ->None:
+class APIWebSocketRoute(routing.WebSocketRoute):
+ def __init__(
+ self,
+ path: str,
+ endpoint: Callable[..., Any],
+ *,
+ name: Optional[str] = None,
+ dependencies: Optional[Sequence[params.Depends]] = None,
+ dependency_overrides_provider: Optional[Any] = None,
+ ) -> None:
self.path = path
self.endpoint = endpoint
self.name = get_name(endpoint) if name is None else name
self.dependencies = list(dependencies or [])
- self.path_regex, self.path_format, self.param_convertors = (
- compile_path(path))
- self.dependant = get_dependant(path=self.path_format, call=self.
- endpoint)
+ self.path_regex, self.path_format, self.param_convertors = compile_path(path)
+ self.dependant = get_dependant(path=self.path_format, call=self.endpoint)
for depends in self.dependencies[::-1]:
- self.dependant.dependencies.insert(0,
- get_parameterless_sub_dependant(depends=depends, path=self.
- path_format))
- self.app = websocket_session(get_websocket_app(dependant=self.
- dependant, dependency_overrides_provider=
- dependency_overrides_provider))
+ self.dependant.dependencies.insert(
+ 0,
+ get_parameterless_sub_dependant(depends=depends, path=self.path_format),
+ )
+
+ self.app = websocket_session(
+ get_websocket_app(
+ dependant=self.dependant,
+ dependency_overrides_provider=dependency_overrides_provider,
+ )
+ )
+ def matches(self, scope: Scope) -> Tuple[Match, Scope]:
+ match, child_scope = super().matches(scope)
+ if match != Match.NONE:
+ child_scope["route"] = self
+ return match, child_scope
-class APIRoute(routing.Route):
- def __init__(self, path: str, endpoint: Callable[..., Any], *,
- response_model: Any=Default(None), status_code: Optional[int]=None,
- tags: Optional[List[Union[str, Enum]]]=None, dependencies: Optional
- [Sequence[params.Depends]]=None, summary: Optional[str]=None,
- description: Optional[str]=None, response_description: str=
- 'Successful Response', responses: Optional[Dict[Union[int, str],
- Dict[str, Any]]]=None, deprecated: Optional[bool]=None, name:
- Optional[str]=None, methods: Optional[Union[Set[str], List[str]]]=
- None, operation_id: Optional[str]=None, response_model_include:
- Optional[IncEx]=None, response_model_exclude: Optional[IncEx]=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, include_in_schema: bool=
- True, response_class: Union[Type[Response], DefaultPlaceholder]=
- Default(JSONResponse), dependency_overrides_provider: Optional[Any]
- =None, callbacks: Optional[List[BaseRoute]]=None, openapi_extra:
- Optional[Dict[str, Any]]=None, generate_unique_id_function: Union[
- Callable[['APIRoute'], str], DefaultPlaceholder]=Default(
- generate_unique_id)) ->None:
+class APIRoute(routing.Route):
+ def __init__(
+ self,
+ path: str,
+ endpoint: Callable[..., Any],
+ *,
+ response_model: Any = Default(None),
+ status_code: Optional[int] = None,
+ tags: Optional[List[Union[str, Enum]]] = None,
+ dependencies: Optional[Sequence[params.Depends]] = None,
+ summary: Optional[str] = None,
+ description: Optional[str] = None,
+ response_description: str = "Successful Response",
+ responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
+ deprecated: Optional[bool] = None,
+ name: Optional[str] = None,
+ methods: Optional[Union[Set[str], List[str]]] = None,
+ operation_id: Optional[str] = None,
+ response_model_include: Optional[IncEx] = None,
+ response_model_exclude: Optional[IncEx] = 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,
+ include_in_schema: bool = True,
+ response_class: Union[Type[Response], DefaultPlaceholder] = Default(
+ JSONResponse
+ ),
+ dependency_overrides_provider: Optional[Any] = None,
+ callbacks: Optional[List[BaseRoute]] = None,
+ openapi_extra: Optional[Dict[str, Any]] = None,
+ generate_unique_id_function: Union[
+ Callable[["APIRoute"], str], DefaultPlaceholder
+ ] = Default(generate_unique_id),
+ ) -> None:
self.path = path
self.endpoint = endpoint
if isinstance(response_model, DefaultPlaceholder):
@@ -99,64 +449,98 @@ class APIRoute(routing.Route):
self.tags = tags or []
self.responses = responses or {}
self.name = get_name(endpoint) if name is None else name
- self.path_regex, self.path_format, self.param_convertors = (
- compile_path(path))
+ self.path_regex, self.path_format, self.param_convertors = compile_path(path)
if methods is None:
- methods = ['GET']
+ methods = ["GET"]
self.methods: Set[str] = {method.upper() for method in methods}
if isinstance(generate_unique_id_function, DefaultPlaceholder):
- current_generate_unique_id: Callable[['APIRoute'], str
- ] = generate_unique_id_function.value
+ current_generate_unique_id: Callable[
+ ["APIRoute"], str
+ ] = generate_unique_id_function.value
else:
current_generate_unique_id = generate_unique_id_function
self.unique_id = self.operation_id or current_generate_unique_id(self)
+ # normalize enums e.g. http.HTTPStatus
if isinstance(status_code, IntEnum):
status_code = int(status_code)
self.status_code = status_code
if self.response_model:
- assert is_body_allowed_for_status_code(status_code
- ), f'Status code {status_code} must not have a response body'
- response_name = 'Response_' + self.unique_id
- self.response_field = create_response_field(name=response_name,
- type_=self.response_model, mode='serialization')
- self.secure_cloned_response_field: Optional[ModelField
- ] = create_cloned_field(self.response_field)
+ assert is_body_allowed_for_status_code(
+ status_code
+ ), f"Status code {status_code} must not have a response body"
+ response_name = "Response_" + self.unique_id
+ self.response_field = create_response_field(
+ name=response_name,
+ type_=self.response_model,
+ mode="serialization",
+ )
+ # Create a clone of the field, so that a Pydantic submodel is not returned
+ # as is just because it's an instance of a subclass of a more limited class
+ # e.g. UserInDB (containing hashed_password) could be a subclass of User
+ # that doesn't have the hashed_password. But because it's a subclass, it
+ # would pass the validation and be returned as is.
+ # By being a new field, no inheritance will be passed as is. A new model
+ # will always be created.
+ # TODO: remove when deprecating Pydantic v1
+ self.secure_cloned_response_field: Optional[
+ ModelField
+ ] = create_cloned_field(self.response_field)
else:
- self.response_field = None
+ self.response_field = None # type: ignore
self.secure_cloned_response_field = None
self.dependencies = list(dependencies or [])
- self.description = description or inspect.cleandoc(self.endpoint.
- __doc__ or '')
- self.description = self.description.split('\x0c')[0].strip()
+ self.description = description or inspect.cleandoc(self.endpoint.__doc__ or "")
+ # if a "form feed" character (page break) is found in the description text,
+ # truncate description text to the content preceding the first "form feed"
+ self.description = self.description.split("\f")[0].strip()
response_fields = {}
for additional_status_code, response in self.responses.items():
- assert isinstance(response, dict
- ), 'An additional response must be a dict'
- model = response.get('model')
+ assert isinstance(response, dict), "An additional response must be a dict"
+ model = response.get("model")
if model:
- assert is_body_allowed_for_status_code(additional_status_code
- ), f'Status code {additional_status_code} must not have a response body'
- response_name = (
- f'Response_{additional_status_code}_{self.unique_id}')
- response_field = create_response_field(name=response_name,
- type_=model)
+ assert is_body_allowed_for_status_code(
+ additional_status_code
+ ), f"Status code {additional_status_code} must not have a response body"
+ response_name = f"Response_{additional_status_code}_{self.unique_id}"
+ response_field = create_response_field(name=response_name, type_=model)
response_fields[additional_status_code] = response_field
if response_fields:
- self.response_fields: Dict[Union[int, str], ModelField
- ] = response_fields
+ self.response_fields: Dict[Union[int, str], ModelField] = response_fields
else:
self.response_fields = {}
- assert callable(endpoint), 'An endpoint must be a callable'
- self.dependant = get_dependant(path=self.path_format, call=self.
- endpoint)
+
+ assert callable(endpoint), "An endpoint must be a callable"
+ self.dependant = get_dependant(path=self.path_format, call=self.endpoint)
for depends in self.dependencies[::-1]:
- self.dependant.dependencies.insert(0,
- get_parameterless_sub_dependant(depends=depends, path=self.
- path_format))
- self.body_field = get_body_field(dependant=self.dependant, name=
- self.unique_id)
+ self.dependant.dependencies.insert(
+ 0,
+ get_parameterless_sub_dependant(depends=depends, path=self.path_format),
+ )
+ self.body_field = get_body_field(dependant=self.dependant, name=self.unique_id)
self.app = request_response(self.get_route_handler())
+ def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
+ return get_request_handler(
+ dependant=self.dependant,
+ body_field=self.body_field,
+ status_code=self.status_code,
+ response_class=self.response_class,
+ response_field=self.secure_cloned_response_field,
+ response_model_include=self.response_model_include,
+ response_model_exclude=self.response_model_exclude,
+ response_model_by_alias=self.response_model_by_alias,
+ response_model_exclude_unset=self.response_model_exclude_unset,
+ response_model_exclude_defaults=self.response_model_exclude_defaults,
+ response_model_exclude_none=self.response_model_exclude_none,
+ dependency_overrides_provider=self.dependency_overrides_provider,
+ )
+
+ def matches(self, scope: Scope) -> Tuple[Match, Scope]:
+ match, child_scope = super().matches(scope)
+ if match != Match.NONE:
+ child_scope["route"] = self
+ return match, child_scope
+
class APIRouter(routing.Router):
"""
@@ -185,10 +569,14 @@ class APIRouter(routing.Router):
```
"""
- def __init__(self, *, prefix: Annotated[str, Doc(
- 'An optional path prefix for the router.')]='', tags: Annotated[
- Optional[List[Union[str, Enum]]], Doc(
- """
+ def __init__(
+ self,
+ *,
+ prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "",
+ tags: Annotated[
+ Optional[List[Union[str, Enum]]],
+ Doc(
+ """
A list of tags to be applied to all the *path operations* in this
router.
@@ -197,25 +585,35 @@ class APIRouter(routing.Router):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[params.Depends]],
- Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[params.Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to all the
*path operations* in this router.
Read more about it in the
[FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
"""
- )]=None, default_response_class: Annotated[Type[Response], Doc(
- """
+ ),
+ ] = None,
+ default_response_class: Annotated[
+ Type[Response],
+ Doc(
+ """
The default response class to be used.
Read more in the
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).
"""
- )]=Default(JSONResponse), responses: Annotated[Optional[Dict[Union[
- int, str], Dict[str, Any]]], Doc(
- """
+ ),
+ ] = Default(JSONResponse),
+ responses: Annotated[
+ Optional[Dict[Union[int, str], Dict[str, Any]]],
+ Doc(
+ """
Additional responses to be shown in OpenAPI.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -226,8 +624,12 @@ class APIRouter(routing.Router):
And in the
[FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = None,
+ callbacks: Annotated[
+ Optional[List[BaseRoute]],
+ Doc(
+ """
OpenAPI callbacks that should apply to all *path operations* in this
router.
@@ -236,8 +638,12 @@ class APIRouter(routing.Router):
Read more about it in the
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
"""
- )]=None, routes: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = None,
+ routes: Annotated[
+ Optional[List[BaseRoute]],
+ Doc(
+ """
**Note**: you probably shouldn't use this parameter, it is inherited
from Starlette and supported for compatibility.
@@ -245,51 +651,73 @@ class APIRouter(routing.Router):
A list of routes to serve incoming HTTP and WebSocket requests.
"""
- ), deprecated(
- """
+ ),
+ deprecated(
+ """
You normally wouldn't use this parameter with FastAPI, it is inherited
from Starlette and supported for compatibility.
In FastAPI, you normally would use the *path operation methods*,
like `router.get()`, `router.post()`, etc.
"""
- )]=None, redirect_slashes: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ redirect_slashes: Annotated[
+ bool,
+ Doc(
+ """
Whether to detect and redirect slashes in URLs when the client doesn't
use the same format.
"""
- )]=True, default: Annotated[Optional[ASGIApp], Doc(
- """
+ ),
+ ] = True,
+ default: Annotated[
+ Optional[ASGIApp],
+ Doc(
+ """
Default function handler for this router. Used to handle
404 Not Found errors.
"""
- )]=None, dependency_overrides_provider: Annotated[Optional[Any],
- Doc(
- """
+ ),
+ ] = None,
+ dependency_overrides_provider: Annotated[
+ Optional[Any],
+ Doc(
+ """
Only used internally by FastAPI to handle dependency overrides.
You shouldn't need to use it. It normally points to the `FastAPI` app
object.
"""
- )]=None, route_class: Annotated[Type[APIRoute], Doc(
- """
+ ),
+ ] = None,
+ route_class: Annotated[
+ Type[APIRoute],
+ Doc(
+ """
Custom route (*path operation*) class to be used by this router.
Read more about it in the
[FastAPI docs for Custom Request and APIRoute class](https://fastapi.tiangolo.com/how-to/custom-request-and-route/#custom-apiroute-class-in-a-router).
"""
- )]=APIRoute, on_startup: Annotated[Optional[Sequence[Callable[[],
- Any]]], Doc(
- """
+ ),
+ ] = APIRoute,
+ on_startup: Annotated[
+ Optional[Sequence[Callable[[], Any]]],
+ Doc(
+ """
A list of startup event handler functions.
You should instead use the `lifespan` handlers.
Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
"""
- )]=None, on_shutdown: Annotated[Optional[Sequence[Callable[[], Any]
- ]], Doc(
- """
+ ),
+ ] = None,
+ on_shutdown: Annotated[
+ Optional[Sequence[Callable[[], Any]]],
+ Doc(
+ """
A list of shutdown event handler functions.
You should instead use the `lifespan` handlers.
@@ -297,16 +725,26 @@ class APIRouter(routing.Router):
Read more in the
[FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
"""
- )]=None, lifespan: Annotated[Optional[Lifespan[Any]], Doc(
- """
+ ),
+ ] = None,
+ # the generic to Lifespan[AppType] is the type of the top level application
+ # which the router cannot know statically, so we use typing.Any
+ lifespan: Annotated[
+ Optional[Lifespan[Any]],
+ Doc(
+ """
A `Lifespan` context manager handler. This replaces `startup` and
`shutdown` functions with a single context manager.
Read more in the
[FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
"""
- )]=None, deprecated: Annotated[Optional[bool], Doc(
- """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Optional[bool],
+ Doc(
+ """
Mark all *path operations* in this router as deprecated.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -314,8 +752,12 @@ class APIRouter(routing.Router):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
"""
- )]=None, include_in_schema: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
To include (or not) all the *path operations* in this router in the
generated OpenAPI.
@@ -324,9 +766,12 @@ class APIRouter(routing.Router):
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, generate_unique_id_function: Annotated[Callable[[APIRoute],
- str], Doc(
- """
+ ),
+ ] = True,
+ 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.
@@ -336,14 +781,22 @@ class APIRouter(routing.Router):
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)) ->None:
- super().__init__(routes=routes, redirect_slashes=redirect_slashes,
- default=default, on_startup=on_startup, on_shutdown=on_shutdown,
- lifespan=lifespan)
+ ),
+ ] = Default(generate_unique_id),
+ ) -> None:
+ super().__init__(
+ routes=routes,
+ redirect_slashes=redirect_slashes,
+ default=default,
+ on_startup=on_startup,
+ on_shutdown=on_shutdown,
+ lifespan=lifespan,
+ )
if prefix:
- assert prefix.startswith('/'), "A path prefix must start with '/'"
- assert not prefix.endswith('/'
- ), "A path prefix must not end with '/', as the routes will start with '/'"
+ assert prefix.startswith("/"), "A path prefix must start with '/'"
+ assert not prefix.endswith(
+ "/"
+ ), "A path prefix must not end with '/', as the routes will start with '/'"
self.prefix = prefix
self.tags: List[Union[str, Enum]] = tags or []
self.dependencies = list(dependencies or [])
@@ -356,24 +809,222 @@ class APIRouter(routing.Router):
self.default_response_class = default_response_class
self.generate_unique_id_function = generate_unique_id_function
- def websocket(self, path: Annotated[str, Doc(
- """
+ def route(
+ self,
+ path: str,
+ methods: Optional[List[str]] = None,
+ name: Optional[str] = None,
+ include_in_schema: bool = True,
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_route(
+ path,
+ func,
+ methods=methods,
+ name=name,
+ include_in_schema=include_in_schema,
+ )
+ return func
+
+ return decorator
+
+ def add_api_route(
+ self,
+ path: str,
+ endpoint: Callable[..., Any],
+ *,
+ response_model: Any = Default(None),
+ status_code: Optional[int] = None,
+ tags: Optional[List[Union[str, Enum]]] = None,
+ dependencies: Optional[Sequence[params.Depends]] = None,
+ summary: Optional[str] = None,
+ description: Optional[str] = None,
+ response_description: str = "Successful Response",
+ responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
+ deprecated: Optional[bool] = None,
+ methods: Optional[Union[Set[str], List[str]]] = None,
+ operation_id: Optional[str] = None,
+ response_model_include: Optional[IncEx] = None,
+ response_model_exclude: Optional[IncEx] = 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,
+ include_in_schema: bool = True,
+ response_class: Union[Type[Response], DefaultPlaceholder] = Default(
+ JSONResponse
+ ),
+ name: Optional[str] = None,
+ route_class_override: Optional[Type[APIRoute]] = None,
+ callbacks: Optional[List[BaseRoute]] = None,
+ openapi_extra: Optional[Dict[str, Any]] = None,
+ generate_unique_id_function: Union[
+ Callable[[APIRoute], str], DefaultPlaceholder
+ ] = Default(generate_unique_id),
+ ) -> None:
+ route_class = route_class_override or self.route_class
+ responses = responses or {}
+ combined_responses = {**self.responses, **responses}
+ current_response_class = get_value_or_default(
+ response_class, self.default_response_class
+ )
+ current_tags = self.tags.copy()
+ if tags:
+ current_tags.extend(tags)
+ current_dependencies = self.dependencies.copy()
+ if dependencies:
+ current_dependencies.extend(dependencies)
+ current_callbacks = self.callbacks.copy()
+ if callbacks:
+ current_callbacks.extend(callbacks)
+ current_generate_unique_id = get_value_or_default(
+ generate_unique_id_function, self.generate_unique_id_function
+ )
+ route = route_class(
+ self.prefix + path,
+ endpoint=endpoint,
+ response_model=response_model,
+ status_code=status_code,
+ tags=current_tags,
+ dependencies=current_dependencies,
+ summary=summary,
+ description=description,
+ response_description=response_description,
+ responses=combined_responses,
+ deprecated=deprecated or self.deprecated,
+ methods=methods,
+ 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 and self.include_in_schema,
+ response_class=current_response_class,
+ name=name,
+ dependency_overrides_provider=self.dependency_overrides_provider,
+ callbacks=current_callbacks,
+ openapi_extra=openapi_extra,
+ generate_unique_id_function=current_generate_unique_id,
+ )
+ self.routes.append(route)
+
+ def api_route(
+ self,
+ path: str,
+ *,
+ response_model: Any = Default(None),
+ status_code: Optional[int] = None,
+ tags: Optional[List[Union[str, Enum]]] = None,
+ dependencies: Optional[Sequence[params.Depends]] = None,
+ summary: Optional[str] = None,
+ description: Optional[str] = None,
+ response_description: str = "Successful Response",
+ responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None,
+ deprecated: Optional[bool] = None,
+ methods: Optional[List[str]] = None,
+ operation_id: Optional[str] = None,
+ response_model_include: Optional[IncEx] = None,
+ response_model_exclude: Optional[IncEx] = 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,
+ include_in_schema: bool = True,
+ response_class: Type[Response] = Default(JSONResponse),
+ name: Optional[str] = None,
+ callbacks: Optional[List[BaseRoute]] = None,
+ openapi_extra: Optional[Dict[str, Any]] = None,
+ generate_unique_id_function: Callable[[APIRoute], str] = Default(
+ generate_unique_id
+ ),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_api_route(
+ path,
+ func,
+ 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=methods,
+ 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,
+ )
+ return func
+
+ return decorator
+
+ def add_api_websocket_route(
+ self,
+ path: str,
+ endpoint: Callable[..., Any],
+ name: Optional[str] = None,
+ *,
+ dependencies: Optional[Sequence[params.Depends]] = None,
+ ) -> None:
+ current_dependencies = self.dependencies.copy()
+ if dependencies:
+ current_dependencies.extend(dependencies)
+
+ route = APIWebSocketRoute(
+ self.prefix + path,
+ endpoint=endpoint,
+ name=name,
+ dependencies=current_dependencies,
+ dependency_overrides_provider=self.dependency_overrides_provider,
+ )
+ self.routes.append(route)
+
+ def websocket(
+ self,
+ path: Annotated[
+ str,
+ Doc(
+ """
WebSocket path.
- """)], name:
- Annotated[Optional[str], Doc(
- """
+ """
+ ),
+ ],
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
A name for the WebSocket. Only used internally.
"""
- )]=None, *, dependencies: Annotated[Optional[Sequence[params.
- Depends]], Doc(
- """
+ ),
+ ] = 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]:
+ ),
+ ] = None,
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Decorate a WebSocket function.
@@ -400,13 +1051,33 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
- def include_router(self, router: Annotated['APIRouter', Doc(
- 'The `APIRouter` to include.')], *, prefix: Annotated[str, Doc(
- 'An optional path prefix for the router.')]='', tags: Annotated[
- Optional[List[Union[str, Enum]]], Doc(
- """
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_api_websocket_route(
+ path, func, name=name, dependencies=dependencies
+ )
+ return func
+
+ return decorator
+
+ def websocket_route(
+ self, path: str, name: Union[str, None] = None
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_websocket_route(path, func, name=name)
+ return func
+
+ return decorator
+
+ def include_router(
+ self,
+ router: Annotated["APIRouter", Doc("The `APIRouter` to include.")],
+ *,
+ prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "",
+ tags: Annotated[
+ Optional[List[Union[str, Enum]]],
+ Doc(
+ """
A list of tags to be applied to all the *path operations* in this
router.
@@ -415,25 +1086,35 @@ class APIRouter(routing.Router):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
"""
- )]=None, dependencies: Annotated[Optional[Sequence[params.Depends]],
- Doc(
- """
+ ),
+ ] = None,
+ dependencies: Annotated[
+ Optional[Sequence[params.Depends]],
+ Doc(
+ """
A list of dependencies (using `Depends()`) to be applied to all the
*path operations* in this router.
Read more about it in the
[FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
"""
- )]=None, default_response_class: Annotated[Type[Response], Doc(
- """
+ ),
+ ] = None,
+ default_response_class: Annotated[
+ Type[Response],
+ Doc(
+ """
The default response class to be used.
Read more in the
[FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).
"""
- )]=Default(JSONResponse), responses: Annotated[Optional[Dict[Union[
- int, str], Dict[str, Any]]], Doc(
- """
+ ),
+ ] = Default(JSONResponse),
+ responses: Annotated[
+ Optional[Dict[Union[int, str], Dict[str, Any]]],
+ Doc(
+ """
Additional responses to be shown in OpenAPI.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -444,8 +1125,12 @@ class APIRouter(routing.Router):
And in the
[FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = None,
+ callbacks: Annotated[
+ Optional[List[BaseRoute]],
+ Doc(
+ """
OpenAPI callbacks that should apply to all *path operations* in this
router.
@@ -454,8 +1139,12 @@ class APIRouter(routing.Router):
Read more about it in the
[FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
"""
- )]=None, deprecated: Annotated[Optional[bool], Doc(
- """
+ ),
+ ] = None,
+ deprecated: Annotated[
+ Optional[bool],
+ Doc(
+ """
Mark all *path operations* in this router as deprecated.
It will be added to the generated OpenAPI (e.g. visible at `/docs`).
@@ -463,16 +1152,23 @@ class APIRouter(routing.Router):
Read more about it in the
[FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
"""
- )]=None, include_in_schema: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ include_in_schema: Annotated[
+ bool,
+ Doc(
+ """
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`).
"""
- )]=True, generate_unique_id_function: Annotated[Callable[[APIRoute],
- str], Doc(
- """
+ ),
+ ] = True,
+ 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.
@@ -482,7 +1178,9 @@ class APIRouter(routing.Router):
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)) ->None:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> None:
"""
Include another `APIRouter` in the same current `APIRouter`.
@@ -506,16 +1204,128 @@ class APIRouter(routing.Router):
app.include_router(internal_router)
```
"""
- pass
-
- def get(self, path: Annotated[str, Doc(
- """
+ if prefix:
+ assert prefix.startswith("/"), "A path prefix must start with '/'"
+ assert not prefix.endswith(
+ "/"
+ ), "A path prefix must not end with '/', as the routes will start with '/'"
+ else:
+ for r in router.routes:
+ path = getattr(r, "path") # noqa: B009
+ name = getattr(r, "name", "unknown")
+ if path is not None and not path:
+ raise FastAPIError(
+ f"Prefix and path cannot be both empty (path operation: {name})"
+ )
+ if responses is None:
+ responses = {}
+ for route in router.routes:
+ if isinstance(route, APIRoute):
+ combined_responses = {**responses, **route.responses}
+ use_response_class = get_value_or_default(
+ route.response_class,
+ router.default_response_class,
+ default_response_class,
+ self.default_response_class,
+ )
+ current_tags = []
+ if tags:
+ current_tags.extend(tags)
+ if route.tags:
+ current_tags.extend(route.tags)
+ current_dependencies: List[params.Depends] = []
+ if dependencies:
+ current_dependencies.extend(dependencies)
+ if route.dependencies:
+ current_dependencies.extend(route.dependencies)
+ current_callbacks = []
+ if callbacks:
+ current_callbacks.extend(callbacks)
+ if route.callbacks:
+ current_callbacks.extend(route.callbacks)
+ current_generate_unique_id = get_value_or_default(
+ route.generate_unique_id_function,
+ router.generate_unique_id_function,
+ generate_unique_id_function,
+ self.generate_unique_id_function,
+ )
+ self.add_api_route(
+ prefix + route.path,
+ route.endpoint,
+ response_model=route.response_model,
+ status_code=route.status_code,
+ tags=current_tags,
+ dependencies=current_dependencies,
+ summary=route.summary,
+ description=route.description,
+ response_description=route.response_description,
+ responses=combined_responses,
+ deprecated=route.deprecated or deprecated or self.deprecated,
+ methods=route.methods,
+ operation_id=route.operation_id,
+ response_model_include=route.response_model_include,
+ response_model_exclude=route.response_model_exclude,
+ response_model_by_alias=route.response_model_by_alias,
+ response_model_exclude_unset=route.response_model_exclude_unset,
+ response_model_exclude_defaults=route.response_model_exclude_defaults,
+ response_model_exclude_none=route.response_model_exclude_none,
+ include_in_schema=route.include_in_schema
+ and self.include_in_schema
+ and include_in_schema,
+ response_class=use_response_class,
+ name=route.name,
+ route_class_override=type(route),
+ callbacks=current_callbacks,
+ openapi_extra=route.openapi_extra,
+ generate_unique_id_function=current_generate_unique_id,
+ )
+ elif isinstance(route, routing.Route):
+ methods = list(route.methods or [])
+ self.add_route(
+ prefix + route.path,
+ route.endpoint,
+ methods=methods,
+ include_in_schema=route.include_in_schema,
+ name=route.name,
+ )
+ elif isinstance(route, APIWebSocketRoute):
+ current_dependencies = []
+ if dependencies:
+ current_dependencies.extend(dependencies)
+ if route.dependencies:
+ current_dependencies.extend(route.dependencies)
+ self.add_api_websocket_route(
+ prefix + route.path,
+ route.endpoint,
+ dependencies=current_dependencies,
+ name=route.name,
+ )
+ elif isinstance(route, routing.WebSocketRoute):
+ self.add_websocket_route(
+ prefix + route.path, route.endpoint, name=route.name
+ )
+ for handler in router.on_startup:
+ self.add_event_handler("startup", handler)
+ for handler in router.on_shutdown:
+ self.add_event_handler("shutdown", handler)
+
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -544,8 +1354,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -553,8 +1367,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -562,17 +1380,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -580,8 +1405,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -594,27 +1423,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -629,32 +1473,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -667,8 +1527,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -680,8 +1544,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -693,8 +1561,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -702,8 +1574,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -711,12 +1587,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -727,17 +1611,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -747,8 +1638,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP GET operation.
@@ -767,16 +1659,50 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
- def put(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -805,8 +1731,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -814,8 +1744,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -823,17 +1757,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -841,8 +1782,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -855,27 +1800,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -890,32 +1850,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -928,8 +1904,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -941,8 +1921,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -954,8 +1938,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -963,8 +1951,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -972,12 +1964,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -988,17 +1988,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -1008,8 +2015,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP PUT operation.
@@ -1033,16 +2041,50 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
- def post(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1071,8 +2113,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -1080,8 +2126,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -1089,17 +2139,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -1107,8 +2164,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1121,27 +2182,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1156,32 +2232,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1194,8 +2286,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -1207,8 +2303,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -1220,8 +2320,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -1229,8 +2333,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -1238,12 +2346,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -1254,17 +2370,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -1274,8 +2397,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP POST operation.
@@ -1299,16 +2423,50 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
- def delete(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1337,8 +2495,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -1346,8 +2508,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -1355,17 +2521,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -1373,8 +2546,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1387,27 +2564,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1422,32 +2614,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1460,8 +2668,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -1473,8 +2685,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -1486,8 +2702,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -1495,8 +2715,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -1504,12 +2728,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -1520,17 +2752,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -1540,8 +2779,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP DELETE operation.
@@ -1560,16 +2800,50 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
- def options(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1598,8 +2872,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -1607,8 +2885,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -1616,17 +2898,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -1634,8 +2923,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1648,27 +2941,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1683,32 +2991,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1721,8 +3045,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -1734,8 +3062,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -1747,8 +3079,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -1756,8 +3092,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -1765,12 +3105,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -1781,17 +3129,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -1801,8 +3156,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP OPTIONS operation.
@@ -1821,16 +3177,50 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
- def head(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -1859,8 +3249,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -1868,8 +3262,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -1877,17 +3275,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -1895,8 +3300,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -1909,27 +3318,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -1944,32 +3368,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -1982,8 +3422,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -1995,8 +3439,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -2008,8 +3456,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -2017,8 +3469,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -2026,12 +3482,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -2042,17 +3506,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -2062,8 +3533,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP HEAD operation.
@@ -2087,16 +3559,50 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
- def patch(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -2125,8 +3631,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -2134,8 +3644,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -2143,17 +3657,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -2161,8 +3682,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -2175,27 +3700,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -2210,32 +3750,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -2248,8 +3804,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -2261,8 +3821,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -2274,8 +3838,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -2283,8 +3851,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -2292,12 +3864,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -2308,17 +3888,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -2328,8 +3915,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP PATCH operation.
@@ -2353,16 +3941,50 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
- def trace(self, path: Annotated[str, Doc(
- """
+ 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(
- """
+ ),
+ ],
+ *,
+ 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
@@ -2391,8 +4013,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -2400,8 +4026,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -2409,17 +4039,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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`).
@@ -2427,8 +4064,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
A description for the *path operation*.
If not provided, it will be extracted automatically from the docstring
@@ -2441,27 +4082,42 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = "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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = None,
+ operation_id: Annotated[
+ Optional[str],
+ Doc(
+ """
Custom operation ID to be used by this *path operation*.
By default, it is generated automatically.
@@ -2476,32 +4132,48 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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
@@ -2514,8 +4186,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`
@@ -2527,8 +4203,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = False,
+ response_model_exclude_none: Annotated[
+ bool,
+ Doc(
+ """
Configuration passed to Pydantic to define if the response data should
exclude fields set to `None`.
@@ -2540,8 +4220,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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`).
@@ -2549,8 +4233,12 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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.
@@ -2558,12 +4246,20 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = Default(JSONResponse),
+ name: Annotated[
+ Optional[str],
+ Doc(
+ """
Name for this *path operation*. Only used internally.
"""
- )]=None, callbacks: Annotated[Optional[List[BaseRoute]], Doc(
- """
+ ),
+ ] = 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
@@ -2574,17 +4270,24 @@ class APIRouter(routing.Router):
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(
- """
+ ),
+ ] = 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(
- """
+ ),
+ ] = 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.
@@ -2594,8 +4297,9 @@ class APIRouter(routing.Router):
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]:
+ ),
+ ] = Default(generate_unique_id),
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add a *path operation* using an HTTP TRACE operation.
@@ -2619,7 +4323,32 @@ class APIRouter(routing.Router):
app.include_router(router)
```
"""
- pass
+ 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,
+ )
@deprecated(
"""
@@ -2628,12 +4357,18 @@ class APIRouter(routing.Router):
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(
- """
+ )
+ def on_event(
+ self,
+ event_type: Annotated[
+ str,
+ Doc(
+ """
The type of event. `startup` or `shutdown`.
"""
- )]) ->Callable[[DecoratedCallable], DecoratedCallable]:
+ ),
+ ],
+ ) -> Callable[[DecoratedCallable], DecoratedCallable]:
"""
Add an event handler for the router.
@@ -2642,4 +4377,9 @@ class APIRouter(routing.Router):
Read more about it in the
[FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated).
"""
- pass
+
+ def decorator(func: DecoratedCallable) -> DecoratedCallable:
+ self.add_event_handler(event_type, func)
+ return func
+
+ return decorator
diff --git a/fastapi/security/api_key.py b/fastapi/security/api_key.py
index 215e9cb9..d68bdb03 100644
--- a/fastapi/security/api_key.py
+++ b/fastapi/security/api_key.py
@@ -1,4 +1,5 @@
from typing import Optional
+
from fastapi.openapi.models import APIKey, APIKeyIn
from fastapi.security.base import SecurityBase
from starlette.exceptions import HTTPException
@@ -43,21 +44,37 @@ class APIKeyQuery(APIKeyBase):
```
"""
- def __init__(self, *, name: Annotated[str, Doc('Query parameter name.')
- ], scheme_name: Annotated[Optional[str], Doc(
- """
+ def __init__(
+ self,
+ *,
+ name: Annotated[
+ str,
+ Doc("Query parameter name."),
+ ],
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if the query parameter is not provided, `APIKeyQuery` will
automatically cancel the request and send the client an error.
@@ -71,18 +88,24 @@ class APIKeyQuery(APIKeyBase):
provided in one of multiple optional ways (for example, in a query
parameter or in an HTTP Bearer token).
"""
- )]=True):
- self.model: APIKey = APIKey(**{'in': APIKeyIn.query}, name=name,
- description=description)
+ ),
+ ] = True,
+ ):
+ self.model: APIKey = APIKey(
+ **{"in": APIKeyIn.query}, # type: ignore[arg-type]
+ name=name,
+ description=description,
+ )
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[str]:
+ async def __call__(self, request: Request) -> Optional[str]:
api_key = request.query_params.get(self.model.name)
if not api_key:
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
return api_key
@@ -120,21 +143,34 @@ class APIKeyHeader(APIKeyBase):
```
"""
- def __init__(self, *, name: Annotated[str, Doc('Header name.')],
- scheme_name: Annotated[Optional[str], Doc(
- """
+ def __init__(
+ self,
+ *,
+ name: Annotated[str, Doc("Header name.")],
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if the header is not provided, `APIKeyHeader` will
automatically cancel the request and send the client an error.
@@ -147,18 +183,24 @@ class APIKeyHeader(APIKeyBase):
provided in one of multiple optional ways (for example, in a header or
in an HTTP Bearer token).
"""
- )]=True):
- self.model: APIKey = APIKey(**{'in': APIKeyIn.header}, name=name,
- description=description)
+ ),
+ ] = True,
+ ):
+ self.model: APIKey = APIKey(
+ **{"in": APIKeyIn.header}, # type: ignore[arg-type]
+ name=name,
+ description=description,
+ )
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[str]:
+ async def __call__(self, request: Request) -> Optional[str]:
api_key = request.headers.get(self.model.name)
if not api_key:
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
return api_key
@@ -196,21 +238,34 @@ class APIKeyCookie(APIKeyBase):
```
"""
- def __init__(self, *, name: Annotated[str, Doc('Cookie name.')],
- scheme_name: Annotated[Optional[str], Doc(
- """
+ def __init__(
+ self,
+ *,
+ name: Annotated[str, Doc("Cookie name.")],
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if the cookie is not provided, `APIKeyCookie` will
automatically cancel the request and send the client an error.
@@ -223,18 +278,24 @@ class APIKeyCookie(APIKeyBase):
provided in one of multiple optional ways (for example, in a cookie or
in an HTTP Bearer token).
"""
- )]=True):
- self.model: APIKey = APIKey(**{'in': APIKeyIn.cookie}, name=name,
- description=description)
+ ),
+ ] = True,
+ ):
+ self.model: APIKey = APIKey(
+ **{"in": APIKeyIn.cookie}, # type: ignore[arg-type]
+ name=name,
+ description=description,
+ )
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[str]:
+ async def __call__(self, request: Request) -> Optional[str]:
api_key = request.cookies.get(self.model.name)
if not api_key:
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
return api_key
diff --git a/fastapi/security/http.py b/fastapi/security/http.py
index a202bb48..a142b135 100644
--- a/fastapi/security/http.py
+++ b/fastapi/security/http.py
@@ -1,6 +1,7 @@
import binascii
from base64 import b64decode
from typing import Optional
+
from fastapi.exceptions import HTTPException
from fastapi.openapi.models import HTTPBase as HTTPBaseModel
from fastapi.openapi.models import HTTPBearer as HTTPBearerModel
@@ -20,8 +21,9 @@ class HTTPBasicCredentials(BaseModel):
Read more about it in the
[FastAPI docs for HTTP Basic Auth](https://fastapi.tiangolo.com/advanced/security/http-basic-auth/).
"""
- username: Annotated[str, Doc('The HTTP Basic username.')]
- password: Annotated[str, Doc('The HTTP Basic password.')]
+
+ username: Annotated[str, Doc("The HTTP Basic username.")]
+ password: Annotated[str, Doc("The HTTP Basic password.")]
class HTTPAuthorizationCredentials(BaseModel):
@@ -45,38 +47,51 @@ class HTTPAuthorizationCredentials(BaseModel):
* `scheme` will have the value `"Bearer"`
* `credentials` will have the value `"deadbeef12346"`
"""
- scheme: Annotated[str, Doc(
- """
+
+ scheme: Annotated[
+ str,
+ Doc(
+ """
The HTTP authorization scheme extracted from the header value.
"""
- )]
- credentials: Annotated[str, Doc(
- """
+ ),
+ ]
+ credentials: Annotated[
+ str,
+ Doc(
+ """
The HTTP authorization credentials extracted from the header value.
"""
- )]
+ ),
+ ]
class HTTPBase(SecurityBase):
-
- def __init__(self, *, scheme: str, scheme_name: Optional[str]=None,
- description: Optional[str]=None, auto_error: bool=True):
+ def __init__(
+ self,
+ *,
+ scheme: str,
+ scheme_name: Optional[str] = None,
+ description: Optional[str] = None,
+ auto_error: bool = True,
+ ):
self.model = HTTPBaseModel(scheme=scheme, description=description)
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[
- HTTPAuthorizationCredentials]:
- authorization = request.headers.get('Authorization')
+ async def __call__(
+ self, request: Request
+ ) -> Optional[HTTPAuthorizationCredentials]:
+ authorization = request.headers.get("Authorization")
scheme, credentials = get_authorization_scheme_param(authorization)
if not (authorization and scheme and credentials):
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
- return HTTPAuthorizationCredentials(scheme=scheme, credentials=
- credentials)
+ return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
class HTTPBasic(HTTPBase):
@@ -112,24 +127,41 @@ class HTTPBasic(HTTPBase):
```
"""
- def __init__(self, *, scheme_name: Annotated[Optional[str], Doc(
- """
+ def __init__(
+ self,
+ *,
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, realm: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ realm: Annotated[
+ Optional[str],
+ Doc(
+ """
HTTP Basic authentication realm.
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if the HTTP Basic authentication is not provided (a
header), `HTTPBasic` will automatically cancel the request and send the
client an error.
@@ -144,35 +176,42 @@ class HTTPBasic(HTTPBase):
provided in one of multiple optional ways (for example, in HTTP Basic
authentication or in an HTTP Bearer token).
"""
- )]=True):
- self.model = HTTPBaseModel(scheme='basic', description=description)
+ ),
+ ] = True,
+ ):
+ self.model = HTTPBaseModel(scheme="basic", description=description)
self.scheme_name = scheme_name or self.__class__.__name__
self.realm = realm
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[HTTPBasicCredentials
- ]:
- authorization = request.headers.get('Authorization')
+ async def __call__( # type: ignore
+ self, request: Request
+ ) -> Optional[HTTPBasicCredentials]:
+ authorization = request.headers.get("Authorization")
scheme, param = get_authorization_scheme_param(authorization)
if self.realm:
- unauthorized_headers = {'WWW-Authenticate':
- f'Basic realm="{self.realm}"'}
+ unauthorized_headers = {"WWW-Authenticate": f'Basic realm="{self.realm}"'}
else:
- unauthorized_headers = {'WWW-Authenticate': 'Basic'}
- if not authorization or scheme.lower() != 'basic':
+ unauthorized_headers = {"WWW-Authenticate": "Basic"}
+ if not authorization or scheme.lower() != "basic":
if self.auto_error:
- raise HTTPException(status_code=HTTP_401_UNAUTHORIZED,
- detail='Not authenticated', headers=unauthorized_headers)
+ raise HTTPException(
+ status_code=HTTP_401_UNAUTHORIZED,
+ detail="Not authenticated",
+ headers=unauthorized_headers,
+ )
else:
return None
- invalid_user_credentials_exc = HTTPException(status_code=
- HTTP_401_UNAUTHORIZED, detail=
- 'Invalid authentication credentials', headers=unauthorized_headers)
+ invalid_user_credentials_exc = HTTPException(
+ status_code=HTTP_401_UNAUTHORIZED,
+ detail="Invalid authentication credentials",
+ headers=unauthorized_headers,
+ )
try:
- data = b64decode(param).decode('ascii')
+ data = b64decode(param).decode("ascii")
except (ValueError, UnicodeDecodeError, binascii.Error):
- raise invalid_user_credentials_exc
- username, separator, password = data.partition(':')
+ raise invalid_user_credentials_exc # noqa: B904
+ username, separator, password = data.partition(":")
if not separator:
raise invalid_user_credentials_exc
return HTTPBasicCredentials(username=username, password=password)
@@ -210,22 +249,34 @@ class HTTPBearer(HTTPBase):
```
"""
- def __init__(self, *, bearerFormat: Annotated[Optional[str], Doc(
- 'Bearer token format.')]=None, scheme_name: Annotated[Optional[str],
- Doc(
- """
+ def __init__(
+ self,
+ *,
+ bearerFormat: Annotated[Optional[str], Doc("Bearer token format.")] = None,
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if the HTTP Bearer token not provided (in an
`Authorization` header), `HTTPBearer` will automatically cancel the
request and send the client an error.
@@ -240,30 +291,34 @@ class HTTPBearer(HTTPBase):
provided in one of multiple optional ways (for example, in an HTTP
Bearer token or in a cookie).
"""
- )]=True):
- self.model = HTTPBearerModel(bearerFormat=bearerFormat, description
- =description)
+ ),
+ ] = True,
+ ):
+ self.model = HTTPBearerModel(bearerFormat=bearerFormat, description=description)
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[
- HTTPAuthorizationCredentials]:
- authorization = request.headers.get('Authorization')
+ async def __call__(
+ self, request: Request
+ ) -> Optional[HTTPAuthorizationCredentials]:
+ authorization = request.headers.get("Authorization")
scheme, credentials = get_authorization_scheme_param(authorization)
if not (authorization and scheme and credentials):
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
- if scheme.lower() != 'bearer':
+ if scheme.lower() != "bearer":
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Invalid authentication credentials')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN,
+ detail="Invalid authentication credentials",
+ )
else:
return None
- return HTTPAuthorizationCredentials(scheme=scheme, credentials=
- credentials)
+ return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
class HTTPDigest(HTTPBase):
@@ -298,20 +353,33 @@ class HTTPDigest(HTTPBase):
```
"""
- def __init__(self, *, scheme_name: Annotated[Optional[str], Doc(
- """
+ def __init__(
+ self,
+ *,
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if the HTTP Digest not provided, `HTTPDigest` will
automatically cancel the request and send the client an error.
@@ -325,23 +393,28 @@ class HTTPDigest(HTTPBase):
provided in one of multiple optional ways (for example, in HTTP
Digest or in a cookie).
"""
- )]=True):
- self.model = HTTPBaseModel(scheme='digest', description=description)
+ ),
+ ] = True,
+ ):
+ self.model = HTTPBaseModel(scheme="digest", description=description)
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[
- HTTPAuthorizationCredentials]:
- authorization = request.headers.get('Authorization')
+ async def __call__(
+ self, request: Request
+ ) -> Optional[HTTPAuthorizationCredentials]:
+ authorization = request.headers.get("Authorization")
scheme, credentials = get_authorization_scheme_param(authorization)
if not (authorization and scheme and credentials):
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
- if scheme.lower() != 'digest':
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Invalid authentication credentials')
- return HTTPAuthorizationCredentials(scheme=scheme, credentials=
- credentials)
+ if scheme.lower() != "digest":
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN,
+ detail="Invalid authentication credentials",
+ )
+ return HTTPAuthorizationCredentials(scheme=scheme, credentials=credentials)
diff --git a/fastapi/security/oauth2.py b/fastapi/security/oauth2.py
index cf99c823..9720cace 100644
--- a/fastapi/security/oauth2.py
+++ b/fastapi/security/oauth2.py
@@ -1,4 +1,5 @@
from typing import Any, Dict, List, Optional, Union, cast
+
from fastapi.exceptions import HTTPException
from fastapi.openapi.models import OAuth2 as OAuth2Model
from fastapi.openapi.models import OAuthFlows as OAuthFlowsModel
@@ -7,6 +8,8 @@ from fastapi.security.base import SecurityBase
from fastapi.security.utils import get_authorization_scheme_param
from starlette.requests import Request
from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
+
+# TODO: import from typing when deprecating Python 3.9
from typing_extensions import Annotated, Doc
@@ -55,26 +58,46 @@ class OAuth2PasswordRequestForm:
know that that it is application specific, it's not part of the specification.
"""
- def __init__(self, *, grant_type: Annotated[Union[str, None], Form(
- pattern='password'), Doc(
- """
+ def __init__(
+ self,
+ *,
+ grant_type: Annotated[
+ Union[str, None],
+ Form(pattern="password"),
+ Doc(
+ """
The OAuth2 spec says it is required and MUST be the fixed string
"password". Nevertheless, this dependency class is permissive and
allows not passing it. If you want to enforce it, use instead the
`OAuth2PasswordRequestFormStrict` dependency.
"""
- )]=None, username: Annotated[str, Form(), Doc(
- """
+ ),
+ ] = None,
+ username: Annotated[
+ str,
+ Form(),
+ Doc(
+ """
`username` string. The OAuth2 spec requires the exact field name
`username`.
"""
- )], password: Annotated[str, Form(), Doc(
- """
+ ),
+ ],
+ password: Annotated[
+ str,
+ Form(),
+ Doc(
+ """
`password` string. The OAuth2 spec requires the exact field name
`password".
"""
- )], scope: Annotated[str, Form(), Doc(
- """
+ ),
+ ],
+ scope: Annotated[
+ str,
+ Form(),
+ Doc(
+ """
A single string with actually several scopes separated by spaces. Each
scope is also a string.
@@ -92,20 +115,32 @@ class OAuth2PasswordRequestForm:
* `profile`
* `openid`
"""
- )]='', client_id: Annotated[Union[str, None], Form(), Doc(
- """
+ ),
+ ] = "",
+ client_id: Annotated[
+ Union[str, None],
+ Form(),
+ Doc(
+ """
If there's a `client_id`, it can be sent as part of the form fields.
But the OAuth2 specification recommends sending the `client_id` and
`client_secret` (if any) using HTTP Basic auth.
"""
- )]=None, client_secret: Annotated[Union[str, None], Form(), Doc(
- """
+ ),
+ ] = None,
+ client_secret: Annotated[
+ Union[str, None],
+ Form(),
+ Doc(
+ """
If there's a `client_password` (and a `client_id`), they can be sent
as part of the form fields. But the OAuth2 specification recommends
sending the `client_id` and `client_secret` (if any) using HTTP Basic
auth.
"""
- )]=None):
+ ),
+ ] = None,
+ ):
self.grant_type = grant_type
self.username = username
self.password = password
@@ -178,26 +213,45 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
using HTTP Basic auth, as: client_id:client_secret
"""
- def __init__(self, grant_type: Annotated[str, Form(pattern='password'),
- Doc(
- """
+ def __init__(
+ self,
+ grant_type: Annotated[
+ str,
+ Form(pattern="password"),
+ Doc(
+ """
The OAuth2 spec says it is required and MUST be the fixed string
"password". This dependency is strict about it. If you want to be
permissive, use instead the `OAuth2PasswordRequestForm` dependency
class.
"""
- )], username: Annotated[str, Form(), Doc(
- """
+ ),
+ ],
+ username: Annotated[
+ str,
+ Form(),
+ Doc(
+ """
`username` string. The OAuth2 spec requires the exact field name
`username`.
"""
- )], password: Annotated[str, Form(), Doc(
- """
+ ),
+ ],
+ password: Annotated[
+ str,
+ Form(),
+ Doc(
+ """
`password` string. The OAuth2 spec requires the exact field name
`password".
"""
- )], scope: Annotated[str, Form(), Doc(
- """
+ ),
+ ],
+ scope: Annotated[
+ str,
+ Form(),
+ Doc(
+ """
A single string with actually several scopes separated by spaces. Each
scope is also a string.
@@ -215,23 +269,40 @@ class OAuth2PasswordRequestFormStrict(OAuth2PasswordRequestForm):
* `profile`
* `openid`
"""
- )]='', client_id: Annotated[Union[str, None], Form(), Doc(
- """
+ ),
+ ] = "",
+ client_id: Annotated[
+ Union[str, None],
+ Form(),
+ Doc(
+ """
If there's a `client_id`, it can be sent as part of the form fields.
But the OAuth2 specification recommends sending the `client_id` and
`client_secret` (if any) using HTTP Basic auth.
"""
- )]=None, client_secret: Annotated[Union[str, None], Form(), Doc(
- """
+ ),
+ ] = None,
+ client_secret: Annotated[
+ Union[str, None],
+ Form(),
+ Doc(
+ """
If there's a `client_password` (and a `client_id`), they can be sent
as part of the form fields. But the OAuth2 specification recommends
sending the `client_id` and `client_secret` (if any) using HTTP Basic
auth.
"""
- )]=None):
- super().__init__(grant_type=grant_type, username=username, password
- =password, scope=scope, client_id=client_id, client_secret=
- client_secret)
+ ),
+ ] = None,
+ ):
+ super().__init__(
+ grant_type=grant_type,
+ username=username,
+ password=password,
+ scope=scope,
+ client_id=client_id,
+ client_secret=client_secret,
+ )
class OAuth2(SecurityBase):
@@ -247,25 +318,41 @@ class OAuth2(SecurityBase):
[FastAPI docs for Security](https://fastapi.tiangolo.com/tutorial/security/).
"""
- def __init__(self, *, flows: Annotated[Union[OAuthFlowsModel, Dict[str,
- Dict[str, Any]]], Doc(
- """
+ def __init__(
+ self,
+ *,
+ flows: Annotated[
+ Union[OAuthFlowsModel, Dict[str, Dict[str, Any]]],
+ Doc(
+ """
The dictionary of OAuth2 flows.
"""
- )]=OAuthFlowsModel(), scheme_name: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = OAuthFlowsModel(),
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if no HTTP Authorization header is provided, required for
OAuth2 authentication, it will automatically cancel the request and
send the client an error.
@@ -280,18 +367,22 @@ class OAuth2(SecurityBase):
provided in one of multiple optional ways (for example, with OAuth2
or in a cookie).
"""
- )]=True):
- self.model = OAuth2Model(flows=cast(OAuthFlowsModel, flows),
- description=description)
+ ),
+ ] = True,
+ ):
+ self.model = OAuth2Model(
+ flows=cast(OAuthFlowsModel, flows), description=description
+ )
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[str]:
- authorization = request.headers.get('Authorization')
+ async def __call__(self, request: Request) -> Optional[str]:
+ authorization = request.headers.get("Authorization")
if not authorization:
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
return authorization
@@ -306,30 +397,50 @@ class OAuth2PasswordBearer(OAuth2):
[FastAPI docs for Simple OAuth2 with Password and Bearer](https://fastapi.tiangolo.com/tutorial/security/simple-oauth2/).
"""
- def __init__(self, tokenUrl: Annotated[str, Doc(
- """
+ def __init__(
+ self,
+ tokenUrl: Annotated[
+ str,
+ Doc(
+ """
The URL to obtain the OAuth2 token. This would be the *path operation*
that has `OAuth2PasswordRequestForm` as a dependency.
"""
- )], scheme_name: Annotated[Optional[str], Doc(
- """
+ ),
+ ],
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, scopes: Annotated[Optional[Dict[str, str]], Doc(
- """
+ ),
+ ] = None,
+ scopes: Annotated[
+ Optional[Dict[str, str]],
+ Doc(
+ """
The OAuth2 scopes that would be required by the *path operations* that
use this dependency.
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if no HTTP Authorization header is provided, required for
OAuth2 authentication, it will automatically cancel the request and
send the client an error.
@@ -344,22 +455,31 @@ class OAuth2PasswordBearer(OAuth2):
provided in one of multiple optional ways (for example, with OAuth2
or in a cookie).
"""
- )]=True):
+ ),
+ ] = True,
+ ):
if not scopes:
scopes = {}
- flows = OAuthFlowsModel(password=cast(Any, {'tokenUrl': tokenUrl,
- 'scopes': scopes}))
- super().__init__(flows=flows, scheme_name=scheme_name, description=
- description, auto_error=auto_error)
-
- async def __call__(self, request: Request) ->Optional[str]:
- authorization = request.headers.get('Authorization')
+ flows = OAuthFlowsModel(
+ password=cast(Any, {"tokenUrl": tokenUrl, "scopes": scopes})
+ )
+ super().__init__(
+ flows=flows,
+ scheme_name=scheme_name,
+ description=description,
+ auto_error=auto_error,
+ )
+
+ async def __call__(self, request: Request) -> Optional[str]:
+ authorization = request.headers.get("Authorization")
scheme, param = get_authorization_scheme_param(authorization)
- if not authorization or scheme.lower() != 'bearer':
+ if not authorization or scheme.lower() != "bearer":
if self.auto_error:
- raise HTTPException(status_code=HTTP_401_UNAUTHORIZED,
- detail='Not authenticated', headers={'WWW-Authenticate':
- 'Bearer'})
+ raise HTTPException(
+ status_code=HTTP_401_UNAUTHORIZED,
+ detail="Not authenticated",
+ headers={"WWW-Authenticate": "Bearer"},
+ )
else:
return None
return param
@@ -371,33 +491,58 @@ class OAuth2AuthorizationCodeBearer(OAuth2):
flow. An instance of it would be used as a dependency.
"""
- def __init__(self, authorizationUrl: str, tokenUrl: Annotated[str, Doc(
- """
+ def __init__(
+ self,
+ authorizationUrl: str,
+ tokenUrl: Annotated[
+ str,
+ Doc(
+ """
The URL to obtain the OAuth2 token.
"""
- )], refreshUrl: Annotated[Optional[str], Doc(
- """
+ ),
+ ],
+ refreshUrl: Annotated[
+ Optional[str],
+ Doc(
+ """
The URL to refresh the token and obtain a new one.
"""
- )]=None, scheme_name: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, scopes: Annotated[Optional[Dict[str, str]], Doc(
- """
+ ),
+ ] = None,
+ scopes: Annotated[
+ Optional[Dict[str, str]],
+ Doc(
+ """
The OAuth2 scopes that would be required by the *path operations* that
use this dependency.
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if no HTTP Authorization header is provided, required for
OAuth2 authentication, it will automatically cancel the request and
send the client an error.
@@ -412,25 +557,41 @@ class OAuth2AuthorizationCodeBearer(OAuth2):
provided in one of multiple optional ways (for example, with OAuth2
or in a cookie).
"""
- )]=True):
+ ),
+ ] = True,
+ ):
if not scopes:
scopes = {}
- flows = OAuthFlowsModel(authorizationCode=cast(Any, {
- 'authorizationUrl': authorizationUrl, 'tokenUrl': tokenUrl,
- 'refreshUrl': refreshUrl, 'scopes': scopes}))
- super().__init__(flows=flows, scheme_name=scheme_name, description=
- description, auto_error=auto_error)
-
- async def __call__(self, request: Request) ->Optional[str]:
- authorization = request.headers.get('Authorization')
+ flows = OAuthFlowsModel(
+ authorizationCode=cast(
+ Any,
+ {
+ "authorizationUrl": authorizationUrl,
+ "tokenUrl": tokenUrl,
+ "refreshUrl": refreshUrl,
+ "scopes": scopes,
+ },
+ )
+ )
+ super().__init__(
+ flows=flows,
+ scheme_name=scheme_name,
+ description=description,
+ auto_error=auto_error,
+ )
+
+ async def __call__(self, request: Request) -> Optional[str]:
+ authorization = request.headers.get("Authorization")
scheme, param = get_authorization_scheme_param(authorization)
- if not authorization or scheme.lower() != 'bearer':
+ if not authorization or scheme.lower() != "bearer":
if self.auto_error:
- raise HTTPException(status_code=HTTP_401_UNAUTHORIZED,
- detail='Not authenticated', headers={'WWW-Authenticate':
- 'Bearer'})
+ raise HTTPException(
+ status_code=HTTP_401_UNAUTHORIZED,
+ detail="Not authenticated",
+ headers={"WWW-Authenticate": "Bearer"},
+ )
else:
- return None
+ return None # pragma: nocover
return param
@@ -447,19 +608,31 @@ class SecurityScopes:
[FastAPI docs for OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/).
"""
- def __init__(self, scopes: Annotated[Optional[List[str]], Doc(
- """
+ def __init__(
+ self,
+ scopes: Annotated[
+ Optional[List[str]],
+ Doc(
+ """
This will be filled by FastAPI.
"""
- )]=None):
- self.scopes: Annotated[List[str], Doc(
- """
+ ),
+ ] = None,
+ ):
+ self.scopes: Annotated[
+ List[str],
+ Doc(
+ """
The list of all the scopes required by dependencies.
"""
- )] = scopes or []
- self.scope_str: Annotated[str, Doc(
- """
+ ),
+ ] = scopes or []
+ self.scope_str: Annotated[
+ str,
+ Doc(
+ """
All the scopes required by all the dependencies in a single string
separated by spaces, as defined in the OAuth2 specification.
"""
- )] = ' '.join(self.scopes)
+ ),
+ ] = " ".join(self.scopes)
diff --git a/fastapi/security/open_id_connect_url.py b/fastapi/security/open_id_connect_url.py
index 0df340e6..c8cceb91 100644
--- a/fastapi/security/open_id_connect_url.py
+++ b/fastapi/security/open_id_connect_url.py
@@ -1,4 +1,5 @@
from typing import Optional
+
from fastapi.openapi.models import OpenIdConnect as OpenIdConnectModel
from fastapi.security.base import SecurityBase
from starlette.exceptions import HTTPException
@@ -13,24 +14,41 @@ class OpenIdConnect(SecurityBase):
dependency.
"""
- def __init__(self, *, openIdConnectUrl: Annotated[str, Doc(
- """
+ def __init__(
+ self,
+ *,
+ openIdConnectUrl: Annotated[
+ str,
+ Doc(
+ """
The OpenID Connect URL.
- """)],
- scheme_name: Annotated[Optional[str], Doc(
- """
+ """
+ ),
+ ],
+ scheme_name: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme name.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, description: Annotated[Optional[str], Doc(
- """
+ ),
+ ] = None,
+ description: Annotated[
+ Optional[str],
+ Doc(
+ """
Security scheme description.
It will be included in the generated OpenAPI (e.g. visible at `/docs`).
"""
- )]=None, auto_error: Annotated[bool, Doc(
- """
+ ),
+ ] = None,
+ auto_error: Annotated[
+ bool,
+ Doc(
+ """
By default, if no HTTP Authorization header is provided, required for
OpenID Connect authentication, it will automatically cancel the request
and send the client an error.
@@ -45,18 +63,22 @@ class OpenIdConnect(SecurityBase):
provided in one of multiple optional ways (for example, with OpenID
Connect or in a cookie).
"""
- )]=True):
- self.model = OpenIdConnectModel(openIdConnectUrl=openIdConnectUrl,
- description=description)
+ ),
+ ] = True,
+ ):
+ self.model = OpenIdConnectModel(
+ openIdConnectUrl=openIdConnectUrl, description=description
+ )
self.scheme_name = scheme_name or self.__class__.__name__
self.auto_error = auto_error
- async def __call__(self, request: Request) ->Optional[str]:
- authorization = request.headers.get('Authorization')
+ async def __call__(self, request: Request) -> Optional[str]:
+ authorization = request.headers.get("Authorization")
if not authorization:
if self.auto_error:
- raise HTTPException(status_code=HTTP_403_FORBIDDEN, detail=
- 'Not authenticated')
+ raise HTTPException(
+ status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+ )
else:
return None
return authorization
diff --git a/fastapi/security/utils.py b/fastapi/security/utils.py
index 8d6471c1..fa7a450b 100644
--- a/fastapi/security/utils.py
+++ b/fastapi/security/utils.py
@@ -1 +1,10 @@
from typing import Optional, Tuple
+
+
+def get_authorization_scheme_param(
+ authorization_header_value: Optional[str],
+) -> Tuple[str, str]:
+ if not authorization_header_value:
+ return "", ""
+ scheme, _, param = authorization_header_value.partition(" ")
+ return scheme, param
diff --git a/fastapi/staticfiles.py b/fastapi/staticfiles.py
index c2a29a70..299015d4 100644
--- a/fastapi/staticfiles.py
+++ b/fastapi/staticfiles.py
@@ -1 +1 @@
-from starlette.staticfiles import StaticFiles as StaticFiles
+from starlette.staticfiles import StaticFiles as StaticFiles # noqa
diff --git a/fastapi/templating.py b/fastapi/templating.py
index 9070b3a7..0cb86848 100644
--- a/fastapi/templating.py
+++ b/fastapi/templating.py
@@ -1 +1 @@
-from starlette.templating import Jinja2Templates as Jinja2Templates
+from starlette.templating import Jinja2Templates as Jinja2Templates # noqa
diff --git a/fastapi/testclient.py b/fastapi/testclient.py
index 8005456e..4012406a 100644
--- a/fastapi/testclient.py
+++ b/fastapi/testclient.py
@@ -1 +1 @@
-from starlette.testclient import TestClient as TestClient
+from starlette.testclient import TestClient as TestClient # noqa
diff --git a/fastapi/types.py b/fastapi/types.py
index 5efdb0b3..3205654c 100644
--- a/fastapi/types.py
+++ b/fastapi/types.py
@@ -1,8 +1,10 @@
import types
from enum import Enum
from typing import Any, Callable, Dict, Set, Type, TypeVar, Union
+
from pydantic import BaseModel
-DecoratedCallable = TypeVar('DecoratedCallable', bound=Callable[..., Any])
-UnionType = getattr(types, 'UnionType', Union)
+
+DecoratedCallable = TypeVar("DecoratedCallable", bound=Callable[..., Any])
+UnionType = getattr(types, "UnionType", Union)
ModelNameMap = Dict[Union[Type[BaseModel], Type[Enum]], str]
IncEx = Union[Set[int], Set[str], Dict[int, Any], Dict[str, Any]]
diff --git a/fastapi/utils.py b/fastapi/utils.py
index a742b860..dfda4e67 100644
--- a/fastapi/utils.py
+++ b/fastapi/utils.py
@@ -1,35 +1,214 @@
import re
import warnings
from dataclasses import is_dataclass
-from typing import TYPE_CHECKING, Any, Dict, MutableMapping, Optional, Set, Type, Union, cast
+from typing import (
+ TYPE_CHECKING,
+ Any,
+ Dict,
+ MutableMapping,
+ Optional,
+ Set,
+ Type,
+ Union,
+ cast,
+)
from weakref import WeakKeyDictionary
+
import fastapi
-from fastapi._compat import PYDANTIC_V2, BaseConfig, ModelField, PydanticSchemaGenerationError, Undefined, UndefinedType, Validator, lenient_issubclass
+from fastapi._compat import (
+ PYDANTIC_V2,
+ BaseConfig,
+ ModelField,
+ PydanticSchemaGenerationError,
+ Undefined,
+ UndefinedType,
+ Validator,
+ lenient_issubclass,
+)
from fastapi.datastructures import DefaultPlaceholder, DefaultType
from pydantic import BaseModel, create_model
from pydantic.fields import FieldInfo
from typing_extensions import Literal
-if TYPE_CHECKING:
+
+if TYPE_CHECKING: # pragma: nocover
from .routing import APIRoute
-_CLONED_TYPES_CACHE: MutableMapping[Type[BaseModel], Type[BaseModel]
- ] = WeakKeyDictionary()
+# Cache for `create_cloned_field`
+_CLONED_TYPES_CACHE: MutableMapping[
+ Type[BaseModel], Type[BaseModel]
+] = WeakKeyDictionary()
+
+
+def is_body_allowed_for_status_code(status_code: Union[int, str, None]) -> bool:
+ if status_code is None:
+ return True
+ # Ref: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#patterned-fields-1
+ if status_code in {
+ "default",
+ "1XX",
+ "2XX",
+ "3XX",
+ "4XX",
+ "5XX",
+ }:
+ return True
+ current_status_code = int(status_code)
+ return not (current_status_code < 200 or current_status_code in {204, 205, 304})
-def create_response_field(name: str, type_: Type[Any], class_validators:
- Optional[Dict[str, Validator]]=None, default: Optional[Any]=Undefined,
- required: Union[bool, UndefinedType]=Undefined, model_config: Type[
- BaseConfig]=BaseConfig, field_info: Optional[FieldInfo]=None, alias:
- Optional[str]=None, mode: Literal['validation', 'serialization']=
- 'validation') ->ModelField:
+
+def get_path_param_names(path: str) -> Set[str]:
+ return set(re.findall("{(.*?)}", path))
+
+
+def create_response_field(
+ name: str,
+ type_: Type[Any],
+ class_validators: Optional[Dict[str, Validator]] = None,
+ default: Optional[Any] = Undefined,
+ required: Union[bool, UndefinedType] = Undefined,
+ model_config: Type[BaseConfig] = BaseConfig,
+ field_info: Optional[FieldInfo] = None,
+ alias: Optional[str] = None,
+ mode: Literal["validation", "serialization"] = "validation",
+) -> ModelField:
"""
Create a new response field. Raises if type_ is invalid.
"""
- pass
+ class_validators = class_validators or {}
+ if PYDANTIC_V2:
+ field_info = field_info or FieldInfo(
+ annotation=type_, default=default, alias=alias
+ )
+ else:
+ field_info = field_info or FieldInfo()
+ kwargs = {"name": name, "field_info": field_info}
+ if PYDANTIC_V2:
+ kwargs.update({"mode": mode})
+ else:
+ kwargs.update(
+ {
+ "type_": type_,
+ "class_validators": class_validators,
+ "default": default,
+ "required": required,
+ "model_config": model_config,
+ "alias": alias,
+ }
+ )
+ try:
+ return ModelField(**kwargs) # type: ignore[arg-type]
+ except (RuntimeError, PydanticSchemaGenerationError):
+ raise fastapi.exceptions.FastAPIError(
+ "Invalid args for response field! Hint: "
+ f"check that {type_} is a valid Pydantic field type. "
+ "If you are using a return type annotation that is not a valid Pydantic "
+ "field (e.g. Union[Response, dict, None]) you can disable generating the "
+ "response model from the type annotation with the path operation decorator "
+ "parameter response_model=None. Read more: "
+ "https://fastapi.tiangolo.com/tutorial/response-model/"
+ ) from None
+
+
+def create_cloned_field(
+ field: ModelField,
+ *,
+ cloned_types: Optional[MutableMapping[Type[BaseModel], Type[BaseModel]]] = None,
+) -> ModelField:
+ if PYDANTIC_V2:
+ return field
+ # cloned_types caches already cloned types to support recursive models and improve
+ # performance by avoiding unnecessary cloning
+ if cloned_types is None:
+ cloned_types = _CLONED_TYPES_CACHE
+
+ original_type = field.type_
+ if is_dataclass(original_type) and hasattr(original_type, "__pydantic_model__"):
+ original_type = original_type.__pydantic_model__
+ use_type = original_type
+ if lenient_issubclass(original_type, BaseModel):
+ original_type = cast(Type[BaseModel], original_type)
+ use_type = cloned_types.get(original_type)
+ if use_type is None:
+ use_type = create_model(original_type.__name__, __base__=original_type)
+ cloned_types[original_type] = use_type
+ for f in original_type.__fields__.values():
+ use_type.__fields__[f.name] = create_cloned_field(
+ f, cloned_types=cloned_types
+ )
+ new_field = create_response_field(name=field.name, type_=use_type)
+ new_field.has_alias = field.has_alias # type: ignore[attr-defined]
+ new_field.alias = field.alias # type: ignore[misc]
+ new_field.class_validators = field.class_validators # type: ignore[attr-defined]
+ new_field.default = field.default # type: ignore[misc]
+ new_field.required = field.required # type: ignore[misc]
+ new_field.model_config = field.model_config # type: ignore[attr-defined]
+ new_field.field_info = field.field_info
+ new_field.allow_none = field.allow_none # type: ignore[attr-defined]
+ new_field.validate_always = field.validate_always # type: ignore[attr-defined]
+ if field.sub_fields: # type: ignore[attr-defined]
+ new_field.sub_fields = [ # type: ignore[attr-defined]
+ create_cloned_field(sub_field, cloned_types=cloned_types)
+ for sub_field in field.sub_fields # type: ignore[attr-defined]
+ ]
+ if field.key_field: # type: ignore[attr-defined]
+ new_field.key_field = create_cloned_field( # type: ignore[attr-defined]
+ field.key_field, # type: ignore[attr-defined]
+ cloned_types=cloned_types,
+ )
+ new_field.validators = field.validators # type: ignore[attr-defined]
+ new_field.pre_validators = field.pre_validators # type: ignore[attr-defined]
+ new_field.post_validators = field.post_validators # type: ignore[attr-defined]
+ new_field.parse_json = field.parse_json # type: ignore[attr-defined]
+ new_field.shape = field.shape # type: ignore[attr-defined]
+ new_field.populate_validators() # type: ignore[attr-defined]
+ return new_field
+
+
+def generate_operation_id_for_path(
+ *, name: str, path: str, method: str
+) -> str: # pragma: nocover
+ warnings.warn(
+ "fastapi.utils.generate_operation_id_for_path() was deprecated, "
+ "it is not used internally, and will be removed soon",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ operation_id = f"{name}{path}"
+ operation_id = re.sub(r"\W", "_", operation_id)
+ operation_id = f"{operation_id}_{method.lower()}"
+ return operation_id
+
+
+def generate_unique_id(route: "APIRoute") -> str:
+ operation_id = f"{route.name}{route.path_format}"
+ operation_id = re.sub(r"\W", "_", operation_id)
+ assert route.methods
+ operation_id = f"{operation_id}_{list(route.methods)[0].lower()}"
+ return operation_id
+
+
+def deep_dict_update(main_dict: Dict[Any, Any], update_dict: Dict[Any, Any]) -> None:
+ for key, value in update_dict.items():
+ if (
+ key in main_dict
+ and isinstance(main_dict[key], dict)
+ and isinstance(value, dict)
+ ):
+ deep_dict_update(main_dict[key], value)
+ elif (
+ key in main_dict
+ and isinstance(main_dict[key], list)
+ and isinstance(update_dict[key], list)
+ ):
+ main_dict[key] = main_dict[key] + update_dict[key]
+ else:
+ main_dict[key] = value
-def get_value_or_default(first_item: Union[DefaultPlaceholder, DefaultType],
- *extra_items: Union[DefaultPlaceholder, DefaultType]) ->Union[
- DefaultPlaceholder, DefaultType]:
+def get_value_or_default(
+ first_item: Union[DefaultPlaceholder, DefaultType],
+ *extra_items: Union[DefaultPlaceholder, DefaultType],
+) -> Union[DefaultPlaceholder, DefaultType]:
"""
Pass items or `DefaultPlaceholder`s by descending priority.
@@ -37,4 +216,8 @@ def get_value_or_default(first_item: Union[DefaultPlaceholder, DefaultType],
Otherwise, the first item (a `DefaultPlaceholder`) will be returned.
"""
- pass
+ items = (first_item,) + extra_items
+ for item in items:
+ if not isinstance(item, DefaultPlaceholder):
+ return item
+ return first_item
diff --git a/fastapi/websockets.py b/fastapi/websockets.py
index b246ce86..55a4ac4a 100644
--- a/fastapi/websockets.py
+++ b/fastapi/websockets.py
@@ -1,3 +1,3 @@
-from starlette.websockets import WebSocket as WebSocket
-from starlette.websockets import WebSocketDisconnect as WebSocketDisconnect
-from starlette.websockets import WebSocketState as WebSocketState
+from starlette.websockets import WebSocket as WebSocket # noqa
+from starlette.websockets import WebSocketDisconnect as WebSocketDisconnect # noqa
+from starlette.websockets import WebSocketState as WebSocketState # noqa