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( # 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[
Union[bool, None],
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).
"""
),
] = None,
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.
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(
"""
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,
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(
"""
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.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,
)
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.
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.
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.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(
"""
By default, after a dependency is called the first time in a request, if
the dependency is declared again for the rest of the request (for example
if the dependency is needed by several dependencies), the value will be
re-used for the rest of the request.
Set `use_cache` to `False` to disable this behavior and ensure the
dependency is called again (if declared more than once) in the same request.
"""
),
] = True,
) -> Any:
"""
Declare a FastAPI dependency.
It takes a single "dependable" callable (like a function).
Don't call it directly, FastAPI will call it for you.
Read more about it in the
[FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/).
**Example**
```python
from typing import Annotated
from fastapi import Depends, FastAPI
app = FastAPI()
async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
return {"q": q, "skip": skip, "limit": limit}
@app.get("/items/")
async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
return commons
```
"""
return params.Depends(dependency=dependency, use_cache=use_cache)
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(
"""
OAuth2 scopes required for the *path operation* that uses this Security
dependency.
The term "scope" comes from the OAuth2 specification, it seems to be
intentionally vague and interpretable. It normally refers to permissions,
in cases to roles.
These scopes are integrated with OpenAPI (and the API docs at `/docs`).
So they are visible in the OpenAPI specification.
)
"""
),
] = None,
use_cache: Annotated[
bool,
Doc(
"""
By default, after a dependency is called the first time in a request, if
the dependency is declared again for the rest of the request (for example
if the dependency is needed by several dependencies), the value will be
re-used for the rest of the request.
Set `use_cache` to `False` to disable this behavior and ensure the
dependency is called again (if declared more than once) in the same request.
"""
),
] = True,
) -> Any:
"""
Declare a FastAPI Security dependency.
The only difference with a regular dependency is that it can declare OAuth2
scopes that will be integrated with OpenAPI and the automatic UI docs (by default
at `/docs`).
It takes a single "dependable" callable (like a function).
Don't call it directly, FastAPI will call it for you.
Read more about it in the
[FastAPI docs for Security](https://fastapi.tiangolo.com/tutorial/security/) and
in the
[FastAPI docs for OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/).
**Example**
```python
from typing import Annotated
from fastapi import Security, FastAPI
from .db import User
from .security import get_current_active_user
app = FastAPI()
@app.get("/users/me/items/")
async def read_own_items(
current_user: Annotated[User, Security(get_current_active_user, scopes=["items"])]
):
return [{"item_id": "Foo", "owner": current_user.username}]
```
"""
return params.Security(dependency=dependency, scopes=scopes, use_cache=use_cache)
