2361 lines
62 KiB
Python
2361 lines
62 KiB
Python
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[
|
|
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.
|
|
|
|
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
|
|
intentionaly 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 Depends, 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)
|