| from collections.abc import Sequence
|
| from typing import Annotated, Any, Callable, Optional, Union
|
|
|
| from annotated_doc import Doc
|
| from fastapi import params
|
| from fastapi._compat import Undefined
|
| from fastapi.openapi.models import Example
|
| from pydantic import AliasChoices, AliasPath
|
| from typing_extensions import Literal, deprecated
|
|
|
| _Unset: Any = Undefined
|
|
|
|
|
| def Path(
|
| 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,
|
| validation_alias: Annotated[
|
| Union[str, AliasPath, AliasChoices, 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#declare-metadata)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = None,
|
| lt: Annotated[
|
| Optional[float],
|
| Doc(
|
| """
|
| Less than. If set, value must be less than this. Only applicable to numbers.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
|
| """
|
| ),
|
| ] = 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(
|
| default: Annotated[
|
| Any,
|
| Doc(
|
| """
|
| Default value if the parameter field is not set.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alternative-old-query-as-the-default-value)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#alias-parameters)
|
| """
|
| ),
|
| ] = None,
|
| alias_priority: Annotated[
|
| Union[int, None],
|
| Doc(
|
| """
|
| Priority of the alias. This affects whether an alias generator is used.
|
| """
|
| ),
|
| ] = _Unset,
|
| validation_alias: Annotated[
|
| Union[str, AliasPath, AliasChoices, 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata)
|
| """
|
| ),
|
| ] = None,
|
| description: Annotated[
|
| Optional[str],
|
| Doc(
|
| """
|
| Human-readable description.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#declare-more-metadata)
|
| """
|
| ),
|
| ] = None,
|
| gt: Annotated[
|
| Optional[float],
|
| Doc(
|
| """
|
| Greater than. If set, value must be greater than this. Only applicable to
|
| numbers.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = None,
|
| lt: Annotated[
|
| Optional[float],
|
| Doc(
|
| """
|
| Less than. If set, value must be less than this. Only applicable to numbers.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Path parameters numeric validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/#number-validations-greater-than-and-less-than-or-equal)
|
| """
|
| ),
|
| ] = None,
|
| min_length: Annotated[
|
| Optional[int],
|
| Doc(
|
| """
|
| Minimum length for strings.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/)
|
| """
|
| ),
|
| ] = None,
|
| max_length: Annotated[
|
| Optional[int],
|
| Doc(
|
| """
|
| Maximum length for strings.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/)
|
| """
|
| ),
|
| ] = None,
|
| pattern: Annotated[
|
| Optional[str],
|
| Doc(
|
| """
|
| RegEx pattern for strings.
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#add-regular-expressions
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
|
| """
|
| ),
|
| ] = 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`).
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#deprecating-parameters)
|
| """
|
| ),
|
| ] = 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`).
|
|
|
| Read more about it in the
|
| [FastAPI docs about Query parameters](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi
|
| """
|
| ),
|
| ] = 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(
|
| 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,
|
| validation_alias: Annotated[
|
| Union[str, AliasPath, AliasChoices, 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
|
| """
|
| ),
|
| ] = 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(
|
| 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,
|
| validation_alias: Annotated[
|
| Union[str, AliasPath, AliasChoices, 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
|
| """
|
| ),
|
| ] = 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(
|
| 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,
|
| validation_alias: Annotated[
|
| Union[str, AliasPath, AliasChoices, 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
|
| """
|
| ),
|
| ] = 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(
|
| 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,
|
| validation_alias: Annotated[
|
| Union[str, AliasPath, AliasChoices, 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
|
| """
|
| ),
|
| ] = 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(
|
| 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,
|
| validation_alias: Annotated[
|
| Union[str, AliasPath, AliasChoices, 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/)
|
| """
|
| ),
|
| ] = 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(
|
| 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times)
|
| """
|
| ),
|
| ] = True,
|
| scope: Annotated[
|
| Union[Literal["function", "request"], None],
|
| Doc(
|
| """
|
| Mainly for dependencies with `yield`, define when the dependency function
|
| should start (the code before `yield`) and when it should end (the code
|
| after `yield`).
|
|
|
| * `"function"`: start the dependency before the *path operation function*
|
| that handles the request, end the dependency after the *path operation
|
| function* ends, but **before** the response is sent back to the client.
|
| So, the dependency function will be executed **around** the *path operation
|
| **function***.
|
| * `"request"`: start the dependency before the *path operation function*
|
| that handles the request (similar to when using `"function"`), but end
|
| **after** the response is sent back to the client. So, the dependency
|
| function will be executed **around** the **request** and response cycle.
|
|
|
| Read more about it in the
|
| [FastAPI docs for FastAPI Dependencies with yield](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#early-exit-and-scope)
|
| """
|
| ),
|
| ] = None,
|
| ) -> 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, scope=scope)
|
|
|
|
|
| def Security(
|
| 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/)
|
| """
|
| ),
|
| ] = 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.
|
|
|
| Read more about it in the
|
| [FastAPI docs about sub-dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/sub-dependencies/#using-the-same-dependency-multiple-times)
|
| """
|
| ),
|
| ] = 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)
|
|
|
