Coverage for fastapi/param_functions.py: 100%
24 statements
« prev ^ index » next coverage.py v7.6.1, created at 2024-08-08 03:53 +0000
1from typing import Any, Callable, Dict, List, Optional, Sequence, Union 1abcde
3from fastapi import params 1abcde
4from fastapi._compat import Undefined 1abcde
5from fastapi.openapi.models import Example 1abcde
6from typing_extensions import Annotated, Doc, deprecated 1abcde
8_Unset: Any = Undefined 1abcde
11def Path( # noqa: N802 1abcde
12 default: Annotated[
13 Any,
14 Doc(
15 """
16 Default value if the parameter field is not set.
18 This doesn't affect `Path` parameters as the value is always required.
19 The parameter is available only for compatibility.
20 """
21 ),
22 ] = ...,
23 *,
24 default_factory: Annotated[
25 Union[Callable[[], Any], None],
26 Doc(
27 """
28 A callable to generate the default value.
30 This doesn't affect `Path` parameters as the value is always required.
31 The parameter is available only for compatibility.
32 """
33 ),
34 ] = _Unset,
35 alias: Annotated[
36 Optional[str],
37 Doc(
38 """
39 An alternative name for the parameter field.
41 This will be used to extract the data and for the generated OpenAPI.
42 It is particularly useful when you can't use the name you want because it
43 is a Python reserved keyword or similar.
44 """
45 ),
46 ] = None,
47 alias_priority: Annotated[
48 Union[int, None],
49 Doc(
50 """
51 Priority of the alias. This affects whether an alias generator is used.
52 """
53 ),
54 ] = _Unset,
55 # TODO: update when deprecating Pydantic v1, import these types
56 # validation_alias: str | AliasPath | AliasChoices | None
57 validation_alias: Annotated[
58 Union[str, None],
59 Doc(
60 """
61 'Whitelist' validation step. The parameter field will be the single one
62 allowed by the alias or set of aliases defined.
63 """
64 ),
65 ] = None,
66 serialization_alias: Annotated[
67 Union[str, None],
68 Doc(
69 """
70 'Blacklist' validation step. The vanilla parameter field will be the
71 single one of the alias' or set of aliases' fields and all the other
72 fields will be ignored at serialization time.
73 """
74 ),
75 ] = None,
76 title: Annotated[
77 Optional[str],
78 Doc(
79 """
80 Human-readable title.
81 """
82 ),
83 ] = None,
84 description: Annotated[
85 Optional[str],
86 Doc(
87 """
88 Human-readable description.
89 """
90 ),
91 ] = None,
92 gt: Annotated[
93 Optional[float],
94 Doc(
95 """
96 Greater than. If set, value must be greater than this. Only applicable to
97 numbers.
98 """
99 ),
100 ] = None,
101 ge: Annotated[
102 Optional[float],
103 Doc(
104 """
105 Greater than or equal. If set, value must be greater than or equal to
106 this. Only applicable to numbers.
107 """
108 ),
109 ] = None,
110 lt: Annotated[
111 Optional[float],
112 Doc(
113 """
114 Less than. If set, value must be less than this. Only applicable to numbers.
115 """
116 ),
117 ] = None,
118 le: Annotated[
119 Optional[float],
120 Doc(
121 """
122 Less than or equal. If set, value must be less than or equal to this.
123 Only applicable to numbers.
124 """
125 ),
126 ] = None,
127 min_length: Annotated[
128 Optional[int],
129 Doc(
130 """
131 Minimum length for strings.
132 """
133 ),
134 ] = None,
135 max_length: Annotated[
136 Optional[int],
137 Doc(
138 """
139 Maximum length for strings.
140 """
141 ),
142 ] = None,
143 pattern: Annotated[
144 Optional[str],
145 Doc(
146 """
147 RegEx pattern for strings.
148 """
149 ),
150 ] = None,
151 regex: Annotated[
152 Optional[str],
153 Doc(
154 """
155 RegEx pattern for strings.
156 """
157 ),
158 deprecated(
159 "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
160 ),
161 ] = None,
162 discriminator: Annotated[
163 Union[str, None],
164 Doc(
165 """
166 Parameter field name for discriminating the type in a tagged union.
167 """
168 ),
169 ] = None,
170 strict: Annotated[
171 Union[bool, None],
172 Doc(
173 """
174 If `True`, strict validation is applied to the field.
175 """
176 ),
177 ] = _Unset,
178 multiple_of: Annotated[
179 Union[float, None],
180 Doc(
181 """
182 Value must be a multiple of this. Only applicable to numbers.
183 """
184 ),
185 ] = _Unset,
186 allow_inf_nan: Annotated[
187 Union[bool, None],
188 Doc(
189 """
190 Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
191 """
192 ),
193 ] = _Unset,
194 max_digits: Annotated[
195 Union[int, None],
196 Doc(
197 """
198 Maximum number of allow digits for strings.
199 """
200 ),
201 ] = _Unset,
202 decimal_places: Annotated[
203 Union[int, None],
204 Doc(
205 """
206 Maximum number of decimal places allowed for numbers.
207 """
208 ),
209 ] = _Unset,
210 examples: Annotated[
211 Optional[List[Any]],
212 Doc(
213 """
214 Example values for this field.
215 """
216 ),
217 ] = None,
218 example: Annotated[
219 Optional[Any],
220 deprecated(
221 "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
222 "although still supported. Use examples instead."
223 ),
224 ] = _Unset,
225 openapi_examples: Annotated[
226 Optional[Dict[str, Example]],
227 Doc(
228 """
229 OpenAPI-specific examples.
231 It will be added to the generated OpenAPI (e.g. visible at `/docs`).
233 Swagger UI (that provides the `/docs` interface) has better support for the
234 OpenAPI-specific examples than the JSON Schema `examples`, that's the main
235 use case for this.
237 Read more about it in the
238 [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
239 """
240 ),
241 ] = None,
242 deprecated: Annotated[
243 Union[deprecated, str, bool, None],
244 Doc(
245 """
246 Mark this parameter field as deprecated.
248 It will affect the generated OpenAPI (e.g. visible at `/docs`).
249 """
250 ),
251 ] = None,
252 include_in_schema: Annotated[
253 bool,
254 Doc(
255 """
256 To include (or not) this parameter field in the generated OpenAPI.
257 You probably don't need it, but it's available.
259 This affects the generated OpenAPI (e.g. visible at `/docs`).
260 """
261 ),
262 ] = True,
263 json_schema_extra: Annotated[
264 Union[Dict[str, Any], None],
265 Doc(
266 """
267 Any additional JSON schema data.
268 """
269 ),
270 ] = None,
271 **extra: Annotated[
272 Any,
273 Doc(
274 """
275 Include extra fields used by the JSON Schema.
276 """
277 ),
278 deprecated(
279 """
280 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
281 """
282 ),
283 ],
284) -> Any:
285 """
286 Declare a path parameter for a *path operation*.
288 Read more about it in the
289 [FastAPI docs for Path Parameters and Numeric Validations](https://fastapi.tiangolo.com/tutorial/path-params-numeric-validations/).
291 ```python
292 from typing import Annotated
294 from fastapi import FastAPI, Path
296 app = FastAPI()
299 @app.get("/items/{item_id}")
300 async def read_items(
301 item_id: Annotated[int, Path(title="The ID of the item to get")],
302 ):
303 return {"item_id": item_id}
304 ```
305 """
306 return params.Path( 1abcde
307 default=default,
308 default_factory=default_factory,
309 alias=alias,
310 alias_priority=alias_priority,
311 validation_alias=validation_alias,
312 serialization_alias=serialization_alias,
313 title=title,
314 description=description,
315 gt=gt,
316 ge=ge,
317 lt=lt,
318 le=le,
319 min_length=min_length,
320 max_length=max_length,
321 pattern=pattern,
322 regex=regex,
323 discriminator=discriminator,
324 strict=strict,
325 multiple_of=multiple_of,
326 allow_inf_nan=allow_inf_nan,
327 max_digits=max_digits,
328 decimal_places=decimal_places,
329 example=example,
330 examples=examples,
331 openapi_examples=openapi_examples,
332 deprecated=deprecated,
333 include_in_schema=include_in_schema,
334 json_schema_extra=json_schema_extra,
335 **extra,
336 )
339def Query( # noqa: N802 1abcde
340 default: Annotated[
341 Any,
342 Doc(
343 """
344 Default value if the parameter field is not set.
345 """
346 ),
347 ] = Undefined,
348 *,
349 default_factory: Annotated[
350 Union[Callable[[], Any], None],
351 Doc(
352 """
353 A callable to generate the default value.
355 This doesn't affect `Path` parameters as the value is always required.
356 The parameter is available only for compatibility.
357 """
358 ),
359 ] = _Unset,
360 alias: Annotated[
361 Optional[str],
362 Doc(
363 """
364 An alternative name for the parameter field.
366 This will be used to extract the data and for the generated OpenAPI.
367 It is particularly useful when you can't use the name you want because it
368 is a Python reserved keyword or similar.
369 """
370 ),
371 ] = None,
372 alias_priority: Annotated[
373 Union[int, None],
374 Doc(
375 """
376 Priority of the alias. This affects whether an alias generator is used.
377 """
378 ),
379 ] = _Unset,
380 # TODO: update when deprecating Pydantic v1, import these types
381 # validation_alias: str | AliasPath | AliasChoices | None
382 validation_alias: Annotated[
383 Union[str, None],
384 Doc(
385 """
386 'Whitelist' validation step. The parameter field will be the single one
387 allowed by the alias or set of aliases defined.
388 """
389 ),
390 ] = None,
391 serialization_alias: Annotated[
392 Union[str, None],
393 Doc(
394 """
395 'Blacklist' validation step. The vanilla parameter field will be the
396 single one of the alias' or set of aliases' fields and all the other
397 fields will be ignored at serialization time.
398 """
399 ),
400 ] = None,
401 title: Annotated[
402 Optional[str],
403 Doc(
404 """
405 Human-readable title.
406 """
407 ),
408 ] = None,
409 description: Annotated[
410 Optional[str],
411 Doc(
412 """
413 Human-readable description.
414 """
415 ),
416 ] = None,
417 gt: Annotated[
418 Optional[float],
419 Doc(
420 """
421 Greater than. If set, value must be greater than this. Only applicable to
422 numbers.
423 """
424 ),
425 ] = None,
426 ge: Annotated[
427 Optional[float],
428 Doc(
429 """
430 Greater than or equal. If set, value must be greater than or equal to
431 this. Only applicable to numbers.
432 """
433 ),
434 ] = None,
435 lt: Annotated[
436 Optional[float],
437 Doc(
438 """
439 Less than. If set, value must be less than this. Only applicable to numbers.
440 """
441 ),
442 ] = None,
443 le: Annotated[
444 Optional[float],
445 Doc(
446 """
447 Less than or equal. If set, value must be less than or equal to this.
448 Only applicable to numbers.
449 """
450 ),
451 ] = None,
452 min_length: Annotated[
453 Optional[int],
454 Doc(
455 """
456 Minimum length for strings.
457 """
458 ),
459 ] = None,
460 max_length: Annotated[
461 Optional[int],
462 Doc(
463 """
464 Maximum length for strings.
465 """
466 ),
467 ] = None,
468 pattern: Annotated[
469 Optional[str],
470 Doc(
471 """
472 RegEx pattern for strings.
473 """
474 ),
475 ] = None,
476 regex: Annotated[
477 Optional[str],
478 Doc(
479 """
480 RegEx pattern for strings.
481 """
482 ),
483 deprecated(
484 "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
485 ),
486 ] = None,
487 discriminator: Annotated[
488 Union[str, None],
489 Doc(
490 """
491 Parameter field name for discriminating the type in a tagged union.
492 """
493 ),
494 ] = None,
495 strict: Annotated[
496 Union[bool, None],
497 Doc(
498 """
499 If `True`, strict validation is applied to the field.
500 """
501 ),
502 ] = _Unset,
503 multiple_of: Annotated[
504 Union[float, None],
505 Doc(
506 """
507 Value must be a multiple of this. Only applicable to numbers.
508 """
509 ),
510 ] = _Unset,
511 allow_inf_nan: Annotated[
512 Union[bool, None],
513 Doc(
514 """
515 Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
516 """
517 ),
518 ] = _Unset,
519 max_digits: Annotated[
520 Union[int, None],
521 Doc(
522 """
523 Maximum number of allow digits for strings.
524 """
525 ),
526 ] = _Unset,
527 decimal_places: Annotated[
528 Union[int, None],
529 Doc(
530 """
531 Maximum number of decimal places allowed for numbers.
532 """
533 ),
534 ] = _Unset,
535 examples: Annotated[
536 Optional[List[Any]],
537 Doc(
538 """
539 Example values for this field.
540 """
541 ),
542 ] = None,
543 example: Annotated[
544 Optional[Any],
545 deprecated(
546 "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
547 "although still supported. Use examples instead."
548 ),
549 ] = _Unset,
550 openapi_examples: Annotated[
551 Optional[Dict[str, Example]],
552 Doc(
553 """
554 OpenAPI-specific examples.
556 It will be added to the generated OpenAPI (e.g. visible at `/docs`).
558 Swagger UI (that provides the `/docs` interface) has better support for the
559 OpenAPI-specific examples than the JSON Schema `examples`, that's the main
560 use case for this.
562 Read more about it in the
563 [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
564 """
565 ),
566 ] = None,
567 deprecated: Annotated[
568 Union[deprecated, str, bool, None],
569 Doc(
570 """
571 Mark this parameter field as deprecated.
573 It will affect the generated OpenAPI (e.g. visible at `/docs`).
574 """
575 ),
576 ] = None,
577 include_in_schema: Annotated[
578 bool,
579 Doc(
580 """
581 To include (or not) this parameter field in the generated OpenAPI.
582 You probably don't need it, but it's available.
584 This affects the generated OpenAPI (e.g. visible at `/docs`).
585 """
586 ),
587 ] = True,
588 json_schema_extra: Annotated[
589 Union[Dict[str, Any], None],
590 Doc(
591 """
592 Any additional JSON schema data.
593 """
594 ),
595 ] = None,
596 **extra: Annotated[
597 Any,
598 Doc(
599 """
600 Include extra fields used by the JSON Schema.
601 """
602 ),
603 deprecated(
604 """
605 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
606 """
607 ),
608 ],
609) -> Any:
610 return params.Query( 1abcde
611 default=default,
612 default_factory=default_factory,
613 alias=alias,
614 alias_priority=alias_priority,
615 validation_alias=validation_alias,
616 serialization_alias=serialization_alias,
617 title=title,
618 description=description,
619 gt=gt,
620 ge=ge,
621 lt=lt,
622 le=le,
623 min_length=min_length,
624 max_length=max_length,
625 pattern=pattern,
626 regex=regex,
627 discriminator=discriminator,
628 strict=strict,
629 multiple_of=multiple_of,
630 allow_inf_nan=allow_inf_nan,
631 max_digits=max_digits,
632 decimal_places=decimal_places,
633 example=example,
634 examples=examples,
635 openapi_examples=openapi_examples,
636 deprecated=deprecated,
637 include_in_schema=include_in_schema,
638 json_schema_extra=json_schema_extra,
639 **extra,
640 )
643def Header( # noqa: N802 1abcde
644 default: Annotated[
645 Any,
646 Doc(
647 """
648 Default value if the parameter field is not set.
649 """
650 ),
651 ] = Undefined,
652 *,
653 default_factory: Annotated[
654 Union[Callable[[], Any], None],
655 Doc(
656 """
657 A callable to generate the default value.
659 This doesn't affect `Path` parameters as the value is always required.
660 The parameter is available only for compatibility.
661 """
662 ),
663 ] = _Unset,
664 alias: Annotated[
665 Optional[str],
666 Doc(
667 """
668 An alternative name for the parameter field.
670 This will be used to extract the data and for the generated OpenAPI.
671 It is particularly useful when you can't use the name you want because it
672 is a Python reserved keyword or similar.
673 """
674 ),
675 ] = None,
676 alias_priority: Annotated[
677 Union[int, None],
678 Doc(
679 """
680 Priority of the alias. This affects whether an alias generator is used.
681 """
682 ),
683 ] = _Unset,
684 # TODO: update when deprecating Pydantic v1, import these types
685 # validation_alias: str | AliasPath | AliasChoices | None
686 validation_alias: Annotated[
687 Union[str, None],
688 Doc(
689 """
690 'Whitelist' validation step. The parameter field will be the single one
691 allowed by the alias or set of aliases defined.
692 """
693 ),
694 ] = None,
695 serialization_alias: Annotated[
696 Union[str, None],
697 Doc(
698 """
699 'Blacklist' validation step. The vanilla parameter field will be the
700 single one of the alias' or set of aliases' fields and all the other
701 fields will be ignored at serialization time.
702 """
703 ),
704 ] = None,
705 convert_underscores: Annotated[
706 bool,
707 Doc(
708 """
709 Automatically convert underscores to hyphens in the parameter field name.
711 Read more about it in the
712 [FastAPI docs for Header Parameters](https://fastapi.tiangolo.com/tutorial/header-params/#automatic-conversion)
713 """
714 ),
715 ] = True,
716 title: Annotated[
717 Optional[str],
718 Doc(
719 """
720 Human-readable title.
721 """
722 ),
723 ] = None,
724 description: Annotated[
725 Optional[str],
726 Doc(
727 """
728 Human-readable description.
729 """
730 ),
731 ] = None,
732 gt: Annotated[
733 Optional[float],
734 Doc(
735 """
736 Greater than. If set, value must be greater than this. Only applicable to
737 numbers.
738 """
739 ),
740 ] = None,
741 ge: Annotated[
742 Optional[float],
743 Doc(
744 """
745 Greater than or equal. If set, value must be greater than or equal to
746 this. Only applicable to numbers.
747 """
748 ),
749 ] = None,
750 lt: Annotated[
751 Optional[float],
752 Doc(
753 """
754 Less than. If set, value must be less than this. Only applicable to numbers.
755 """
756 ),
757 ] = None,
758 le: Annotated[
759 Optional[float],
760 Doc(
761 """
762 Less than or equal. If set, value must be less than or equal to this.
763 Only applicable to numbers.
764 """
765 ),
766 ] = None,
767 min_length: Annotated[
768 Optional[int],
769 Doc(
770 """
771 Minimum length for strings.
772 """
773 ),
774 ] = None,
775 max_length: Annotated[
776 Optional[int],
777 Doc(
778 """
779 Maximum length for strings.
780 """
781 ),
782 ] = None,
783 pattern: Annotated[
784 Optional[str],
785 Doc(
786 """
787 RegEx pattern for strings.
788 """
789 ),
790 ] = None,
791 regex: Annotated[
792 Optional[str],
793 Doc(
794 """
795 RegEx pattern for strings.
796 """
797 ),
798 deprecated(
799 "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
800 ),
801 ] = None,
802 discriminator: Annotated[
803 Union[str, None],
804 Doc(
805 """
806 Parameter field name for discriminating the type in a tagged union.
807 """
808 ),
809 ] = None,
810 strict: Annotated[
811 Union[bool, None],
812 Doc(
813 """
814 If `True`, strict validation is applied to the field.
815 """
816 ),
817 ] = _Unset,
818 multiple_of: Annotated[
819 Union[float, None],
820 Doc(
821 """
822 Value must be a multiple of this. Only applicable to numbers.
823 """
824 ),
825 ] = _Unset,
826 allow_inf_nan: Annotated[
827 Union[bool, None],
828 Doc(
829 """
830 Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
831 """
832 ),
833 ] = _Unset,
834 max_digits: Annotated[
835 Union[int, None],
836 Doc(
837 """
838 Maximum number of allow digits for strings.
839 """
840 ),
841 ] = _Unset,
842 decimal_places: Annotated[
843 Union[int, None],
844 Doc(
845 """
846 Maximum number of decimal places allowed for numbers.
847 """
848 ),
849 ] = _Unset,
850 examples: Annotated[
851 Optional[List[Any]],
852 Doc(
853 """
854 Example values for this field.
855 """
856 ),
857 ] = None,
858 example: Annotated[
859 Optional[Any],
860 deprecated(
861 "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
862 "although still supported. Use examples instead."
863 ),
864 ] = _Unset,
865 openapi_examples: Annotated[
866 Optional[Dict[str, Example]],
867 Doc(
868 """
869 OpenAPI-specific examples.
871 It will be added to the generated OpenAPI (e.g. visible at `/docs`).
873 Swagger UI (that provides the `/docs` interface) has better support for the
874 OpenAPI-specific examples than the JSON Schema `examples`, that's the main
875 use case for this.
877 Read more about it in the
878 [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
879 """
880 ),
881 ] = None,
882 deprecated: Annotated[
883 Union[deprecated, str, bool, None],
884 Doc(
885 """
886 Mark this parameter field as deprecated.
888 It will affect the generated OpenAPI (e.g. visible at `/docs`).
889 """
890 ),
891 ] = None,
892 include_in_schema: Annotated[
893 bool,
894 Doc(
895 """
896 To include (or not) this parameter field in the generated OpenAPI.
897 You probably don't need it, but it's available.
899 This affects the generated OpenAPI (e.g. visible at `/docs`).
900 """
901 ),
902 ] = True,
903 json_schema_extra: Annotated[
904 Union[Dict[str, Any], None],
905 Doc(
906 """
907 Any additional JSON schema data.
908 """
909 ),
910 ] = None,
911 **extra: Annotated[
912 Any,
913 Doc(
914 """
915 Include extra fields used by the JSON Schema.
916 """
917 ),
918 deprecated(
919 """
920 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
921 """
922 ),
923 ],
924) -> Any:
925 return params.Header( 1abcde
926 default=default,
927 default_factory=default_factory,
928 alias=alias,
929 alias_priority=alias_priority,
930 validation_alias=validation_alias,
931 serialization_alias=serialization_alias,
932 convert_underscores=convert_underscores,
933 title=title,
934 description=description,
935 gt=gt,
936 ge=ge,
937 lt=lt,
938 le=le,
939 min_length=min_length,
940 max_length=max_length,
941 pattern=pattern,
942 regex=regex,
943 discriminator=discriminator,
944 strict=strict,
945 multiple_of=multiple_of,
946 allow_inf_nan=allow_inf_nan,
947 max_digits=max_digits,
948 decimal_places=decimal_places,
949 example=example,
950 examples=examples,
951 openapi_examples=openapi_examples,
952 deprecated=deprecated,
953 include_in_schema=include_in_schema,
954 json_schema_extra=json_schema_extra,
955 **extra,
956 )
959def Cookie( # noqa: N802 1abcde
960 default: Annotated[
961 Any,
962 Doc(
963 """
964 Default value if the parameter field is not set.
965 """
966 ),
967 ] = Undefined,
968 *,
969 default_factory: Annotated[
970 Union[Callable[[], Any], None],
971 Doc(
972 """
973 A callable to generate the default value.
975 This doesn't affect `Path` parameters as the value is always required.
976 The parameter is available only for compatibility.
977 """
978 ),
979 ] = _Unset,
980 alias: Annotated[
981 Optional[str],
982 Doc(
983 """
984 An alternative name for the parameter field.
986 This will be used to extract the data and for the generated OpenAPI.
987 It is particularly useful when you can't use the name you want because it
988 is a Python reserved keyword or similar.
989 """
990 ),
991 ] = None,
992 alias_priority: Annotated[
993 Union[int, None],
994 Doc(
995 """
996 Priority of the alias. This affects whether an alias generator is used.
997 """
998 ),
999 ] = _Unset,
1000 # TODO: update when deprecating Pydantic v1, import these types
1001 # validation_alias: str | AliasPath | AliasChoices | None
1002 validation_alias: Annotated[
1003 Union[str, None],
1004 Doc(
1005 """
1006 'Whitelist' validation step. The parameter field will be the single one
1007 allowed by the alias or set of aliases defined.
1008 """
1009 ),
1010 ] = None,
1011 serialization_alias: Annotated[
1012 Union[str, None],
1013 Doc(
1014 """
1015 'Blacklist' validation step. The vanilla parameter field will be the
1016 single one of the alias' or set of aliases' fields and all the other
1017 fields will be ignored at serialization time.
1018 """
1019 ),
1020 ] = None,
1021 title: Annotated[
1022 Optional[str],
1023 Doc(
1024 """
1025 Human-readable title.
1026 """
1027 ),
1028 ] = None,
1029 description: Annotated[
1030 Optional[str],
1031 Doc(
1032 """
1033 Human-readable description.
1034 """
1035 ),
1036 ] = None,
1037 gt: Annotated[
1038 Optional[float],
1039 Doc(
1040 """
1041 Greater than. If set, value must be greater than this. Only applicable to
1042 numbers.
1043 """
1044 ),
1045 ] = None,
1046 ge: Annotated[
1047 Optional[float],
1048 Doc(
1049 """
1050 Greater than or equal. If set, value must be greater than or equal to
1051 this. Only applicable to numbers.
1052 """
1053 ),
1054 ] = None,
1055 lt: Annotated[
1056 Optional[float],
1057 Doc(
1058 """
1059 Less than. If set, value must be less than this. Only applicable to numbers.
1060 """
1061 ),
1062 ] = None,
1063 le: Annotated[
1064 Optional[float],
1065 Doc(
1066 """
1067 Less than or equal. If set, value must be less than or equal to this.
1068 Only applicable to numbers.
1069 """
1070 ),
1071 ] = None,
1072 min_length: Annotated[
1073 Optional[int],
1074 Doc(
1075 """
1076 Minimum length for strings.
1077 """
1078 ),
1079 ] = None,
1080 max_length: Annotated[
1081 Optional[int],
1082 Doc(
1083 """
1084 Maximum length for strings.
1085 """
1086 ),
1087 ] = None,
1088 pattern: Annotated[
1089 Optional[str],
1090 Doc(
1091 """
1092 RegEx pattern for strings.
1093 """
1094 ),
1095 ] = None,
1096 regex: Annotated[
1097 Optional[str],
1098 Doc(
1099 """
1100 RegEx pattern for strings.
1101 """
1102 ),
1103 deprecated(
1104 "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
1105 ),
1106 ] = None,
1107 discriminator: Annotated[
1108 Union[str, None],
1109 Doc(
1110 """
1111 Parameter field name for discriminating the type in a tagged union.
1112 """
1113 ),
1114 ] = None,
1115 strict: Annotated[
1116 Union[bool, None],
1117 Doc(
1118 """
1119 If `True`, strict validation is applied to the field.
1120 """
1121 ),
1122 ] = _Unset,
1123 multiple_of: Annotated[
1124 Union[float, None],
1125 Doc(
1126 """
1127 Value must be a multiple of this. Only applicable to numbers.
1128 """
1129 ),
1130 ] = _Unset,
1131 allow_inf_nan: Annotated[
1132 Union[bool, None],
1133 Doc(
1134 """
1135 Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
1136 """
1137 ),
1138 ] = _Unset,
1139 max_digits: Annotated[
1140 Union[int, None],
1141 Doc(
1142 """
1143 Maximum number of allow digits for strings.
1144 """
1145 ),
1146 ] = _Unset,
1147 decimal_places: Annotated[
1148 Union[int, None],
1149 Doc(
1150 """
1151 Maximum number of decimal places allowed for numbers.
1152 """
1153 ),
1154 ] = _Unset,
1155 examples: Annotated[
1156 Optional[List[Any]],
1157 Doc(
1158 """
1159 Example values for this field.
1160 """
1161 ),
1162 ] = None,
1163 example: Annotated[
1164 Optional[Any],
1165 deprecated(
1166 "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
1167 "although still supported. Use examples instead."
1168 ),
1169 ] = _Unset,
1170 openapi_examples: Annotated[
1171 Optional[Dict[str, Example]],
1172 Doc(
1173 """
1174 OpenAPI-specific examples.
1176 It will be added to the generated OpenAPI (e.g. visible at `/docs`).
1178 Swagger UI (that provides the `/docs` interface) has better support for the
1179 OpenAPI-specific examples than the JSON Schema `examples`, that's the main
1180 use case for this.
1182 Read more about it in the
1183 [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
1184 """
1185 ),
1186 ] = None,
1187 deprecated: Annotated[
1188 Union[deprecated, str, bool, None],
1189 Doc(
1190 """
1191 Mark this parameter field as deprecated.
1193 It will affect the generated OpenAPI (e.g. visible at `/docs`).
1194 """
1195 ),
1196 ] = None,
1197 include_in_schema: Annotated[
1198 bool,
1199 Doc(
1200 """
1201 To include (or not) this parameter field in the generated OpenAPI.
1202 You probably don't need it, but it's available.
1204 This affects the generated OpenAPI (e.g. visible at `/docs`).
1205 """
1206 ),
1207 ] = True,
1208 json_schema_extra: Annotated[
1209 Union[Dict[str, Any], None],
1210 Doc(
1211 """
1212 Any additional JSON schema data.
1213 """
1214 ),
1215 ] = None,
1216 **extra: Annotated[
1217 Any,
1218 Doc(
1219 """
1220 Include extra fields used by the JSON Schema.
1221 """
1222 ),
1223 deprecated(
1224 """
1225 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
1226 """
1227 ),
1228 ],
1229) -> Any:
1230 return params.Cookie( 1abcde
1231 default=default,
1232 default_factory=default_factory,
1233 alias=alias,
1234 alias_priority=alias_priority,
1235 validation_alias=validation_alias,
1236 serialization_alias=serialization_alias,
1237 title=title,
1238 description=description,
1239 gt=gt,
1240 ge=ge,
1241 lt=lt,
1242 le=le,
1243 min_length=min_length,
1244 max_length=max_length,
1245 pattern=pattern,
1246 regex=regex,
1247 discriminator=discriminator,
1248 strict=strict,
1249 multiple_of=multiple_of,
1250 allow_inf_nan=allow_inf_nan,
1251 max_digits=max_digits,
1252 decimal_places=decimal_places,
1253 example=example,
1254 examples=examples,
1255 openapi_examples=openapi_examples,
1256 deprecated=deprecated,
1257 include_in_schema=include_in_schema,
1258 json_schema_extra=json_schema_extra,
1259 **extra,
1260 )
1263def Body( # noqa: N802 1abcde
1264 default: Annotated[
1265 Any,
1266 Doc(
1267 """
1268 Default value if the parameter field is not set.
1269 """
1270 ),
1271 ] = Undefined,
1272 *,
1273 default_factory: Annotated[
1274 Union[Callable[[], Any], None],
1275 Doc(
1276 """
1277 A callable to generate the default value.
1279 This doesn't affect `Path` parameters as the value is always required.
1280 The parameter is available only for compatibility.
1281 """
1282 ),
1283 ] = _Unset,
1284 embed: Annotated[
1285 bool,
1286 Doc(
1287 """
1288 When `embed` is `True`, the parameter will be expected in a JSON body as a
1289 key instead of being the JSON body itself.
1291 This happens automatically when more than one `Body` parameter is declared.
1293 Read more about it in the
1294 [FastAPI docs for Body - Multiple Parameters](https://fastapi.tiangolo.com/tutorial/body-multiple-params/#embed-a-single-body-parameter).
1295 """
1296 ),
1297 ] = False,
1298 media_type: Annotated[
1299 str,
1300 Doc(
1301 """
1302 The media type of this parameter field. Changing it would affect the
1303 generated OpenAPI, but currently it doesn't affect the parsing of the data.
1304 """
1305 ),
1306 ] = "application/json",
1307 alias: Annotated[
1308 Optional[str],
1309 Doc(
1310 """
1311 An alternative name for the parameter field.
1313 This will be used to extract the data and for the generated OpenAPI.
1314 It is particularly useful when you can't use the name you want because it
1315 is a Python reserved keyword or similar.
1316 """
1317 ),
1318 ] = None,
1319 alias_priority: Annotated[
1320 Union[int, None],
1321 Doc(
1322 """
1323 Priority of the alias. This affects whether an alias generator is used.
1324 """
1325 ),
1326 ] = _Unset,
1327 # TODO: update when deprecating Pydantic v1, import these types
1328 # validation_alias: str | AliasPath | AliasChoices | None
1329 validation_alias: Annotated[
1330 Union[str, None],
1331 Doc(
1332 """
1333 'Whitelist' validation step. The parameter field will be the single one
1334 allowed by the alias or set of aliases defined.
1335 """
1336 ),
1337 ] = None,
1338 serialization_alias: Annotated[
1339 Union[str, None],
1340 Doc(
1341 """
1342 'Blacklist' validation step. The vanilla parameter field will be the
1343 single one of the alias' or set of aliases' fields and all the other
1344 fields will be ignored at serialization time.
1345 """
1346 ),
1347 ] = None,
1348 title: Annotated[
1349 Optional[str],
1350 Doc(
1351 """
1352 Human-readable title.
1353 """
1354 ),
1355 ] = None,
1356 description: Annotated[
1357 Optional[str],
1358 Doc(
1359 """
1360 Human-readable description.
1361 """
1362 ),
1363 ] = None,
1364 gt: Annotated[
1365 Optional[float],
1366 Doc(
1367 """
1368 Greater than. If set, value must be greater than this. Only applicable to
1369 numbers.
1370 """
1371 ),
1372 ] = None,
1373 ge: Annotated[
1374 Optional[float],
1375 Doc(
1376 """
1377 Greater than or equal. If set, value must be greater than or equal to
1378 this. Only applicable to numbers.
1379 """
1380 ),
1381 ] = None,
1382 lt: Annotated[
1383 Optional[float],
1384 Doc(
1385 """
1386 Less than. If set, value must be less than this. Only applicable to numbers.
1387 """
1388 ),
1389 ] = None,
1390 le: Annotated[
1391 Optional[float],
1392 Doc(
1393 """
1394 Less than or equal. If set, value must be less than or equal to this.
1395 Only applicable to numbers.
1396 """
1397 ),
1398 ] = None,
1399 min_length: Annotated[
1400 Optional[int],
1401 Doc(
1402 """
1403 Minimum length for strings.
1404 """
1405 ),
1406 ] = None,
1407 max_length: Annotated[
1408 Optional[int],
1409 Doc(
1410 """
1411 Maximum length for strings.
1412 """
1413 ),
1414 ] = None,
1415 pattern: Annotated[
1416 Optional[str],
1417 Doc(
1418 """
1419 RegEx pattern for strings.
1420 """
1421 ),
1422 ] = None,
1423 regex: Annotated[
1424 Optional[str],
1425 Doc(
1426 """
1427 RegEx pattern for strings.
1428 """
1429 ),
1430 deprecated(
1431 "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
1432 ),
1433 ] = None,
1434 discriminator: Annotated[
1435 Union[str, None],
1436 Doc(
1437 """
1438 Parameter field name for discriminating the type in a tagged union.
1439 """
1440 ),
1441 ] = None,
1442 strict: Annotated[
1443 Union[bool, None],
1444 Doc(
1445 """
1446 If `True`, strict validation is applied to the field.
1447 """
1448 ),
1449 ] = _Unset,
1450 multiple_of: Annotated[
1451 Union[float, None],
1452 Doc(
1453 """
1454 Value must be a multiple of this. Only applicable to numbers.
1455 """
1456 ),
1457 ] = _Unset,
1458 allow_inf_nan: Annotated[
1459 Union[bool, None],
1460 Doc(
1461 """
1462 Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
1463 """
1464 ),
1465 ] = _Unset,
1466 max_digits: Annotated[
1467 Union[int, None],
1468 Doc(
1469 """
1470 Maximum number of allow digits for strings.
1471 """
1472 ),
1473 ] = _Unset,
1474 decimal_places: Annotated[
1475 Union[int, None],
1476 Doc(
1477 """
1478 Maximum number of decimal places allowed for numbers.
1479 """
1480 ),
1481 ] = _Unset,
1482 examples: Annotated[
1483 Optional[List[Any]],
1484 Doc(
1485 """
1486 Example values for this field.
1487 """
1488 ),
1489 ] = None,
1490 example: Annotated[
1491 Optional[Any],
1492 deprecated(
1493 "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
1494 "although still supported. Use examples instead."
1495 ),
1496 ] = _Unset,
1497 openapi_examples: Annotated[
1498 Optional[Dict[str, Example]],
1499 Doc(
1500 """
1501 OpenAPI-specific examples.
1503 It will be added to the generated OpenAPI (e.g. visible at `/docs`).
1505 Swagger UI (that provides the `/docs` interface) has better support for the
1506 OpenAPI-specific examples than the JSON Schema `examples`, that's the main
1507 use case for this.
1509 Read more about it in the
1510 [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
1511 """
1512 ),
1513 ] = None,
1514 deprecated: Annotated[
1515 Union[deprecated, str, bool, None],
1516 Doc(
1517 """
1518 Mark this parameter field as deprecated.
1520 It will affect the generated OpenAPI (e.g. visible at `/docs`).
1521 """
1522 ),
1523 ] = None,
1524 include_in_schema: Annotated[
1525 bool,
1526 Doc(
1527 """
1528 To include (or not) this parameter field in the generated OpenAPI.
1529 You probably don't need it, but it's available.
1531 This affects the generated OpenAPI (e.g. visible at `/docs`).
1532 """
1533 ),
1534 ] = True,
1535 json_schema_extra: Annotated[
1536 Union[Dict[str, Any], None],
1537 Doc(
1538 """
1539 Any additional JSON schema data.
1540 """
1541 ),
1542 ] = None,
1543 **extra: Annotated[
1544 Any,
1545 Doc(
1546 """
1547 Include extra fields used by the JSON Schema.
1548 """
1549 ),
1550 deprecated(
1551 """
1552 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
1553 """
1554 ),
1555 ],
1556) -> Any:
1557 return params.Body( 1abcde
1558 default=default,
1559 default_factory=default_factory,
1560 embed=embed,
1561 media_type=media_type,
1562 alias=alias,
1563 alias_priority=alias_priority,
1564 validation_alias=validation_alias,
1565 serialization_alias=serialization_alias,
1566 title=title,
1567 description=description,
1568 gt=gt,
1569 ge=ge,
1570 lt=lt,
1571 le=le,
1572 min_length=min_length,
1573 max_length=max_length,
1574 pattern=pattern,
1575 regex=regex,
1576 discriminator=discriminator,
1577 strict=strict,
1578 multiple_of=multiple_of,
1579 allow_inf_nan=allow_inf_nan,
1580 max_digits=max_digits,
1581 decimal_places=decimal_places,
1582 example=example,
1583 examples=examples,
1584 openapi_examples=openapi_examples,
1585 deprecated=deprecated,
1586 include_in_schema=include_in_schema,
1587 json_schema_extra=json_schema_extra,
1588 **extra,
1589 )
1592def Form( # noqa: N802 1abcde
1593 default: Annotated[
1594 Any,
1595 Doc(
1596 """
1597 Default value if the parameter field is not set.
1598 """
1599 ),
1600 ] = Undefined,
1601 *,
1602 default_factory: Annotated[
1603 Union[Callable[[], Any], None],
1604 Doc(
1605 """
1606 A callable to generate the default value.
1608 This doesn't affect `Path` parameters as the value is always required.
1609 The parameter is available only for compatibility.
1610 """
1611 ),
1612 ] = _Unset,
1613 media_type: Annotated[
1614 str,
1615 Doc(
1616 """
1617 The media type of this parameter field. Changing it would affect the
1618 generated OpenAPI, but currently it doesn't affect the parsing of the data.
1619 """
1620 ),
1621 ] = "application/x-www-form-urlencoded",
1622 alias: Annotated[
1623 Optional[str],
1624 Doc(
1625 """
1626 An alternative name for the parameter field.
1628 This will be used to extract the data and for the generated OpenAPI.
1629 It is particularly useful when you can't use the name you want because it
1630 is a Python reserved keyword or similar.
1631 """
1632 ),
1633 ] = None,
1634 alias_priority: Annotated[
1635 Union[int, None],
1636 Doc(
1637 """
1638 Priority of the alias. This affects whether an alias generator is used.
1639 """
1640 ),
1641 ] = _Unset,
1642 # TODO: update when deprecating Pydantic v1, import these types
1643 # validation_alias: str | AliasPath | AliasChoices | None
1644 validation_alias: Annotated[
1645 Union[str, None],
1646 Doc(
1647 """
1648 'Whitelist' validation step. The parameter field will be the single one
1649 allowed by the alias or set of aliases defined.
1650 """
1651 ),
1652 ] = None,
1653 serialization_alias: Annotated[
1654 Union[str, None],
1655 Doc(
1656 """
1657 'Blacklist' validation step. The vanilla parameter field will be the
1658 single one of the alias' or set of aliases' fields and all the other
1659 fields will be ignored at serialization time.
1660 """
1661 ),
1662 ] = None,
1663 title: Annotated[
1664 Optional[str],
1665 Doc(
1666 """
1667 Human-readable title.
1668 """
1669 ),
1670 ] = None,
1671 description: Annotated[
1672 Optional[str],
1673 Doc(
1674 """
1675 Human-readable description.
1676 """
1677 ),
1678 ] = None,
1679 gt: Annotated[
1680 Optional[float],
1681 Doc(
1682 """
1683 Greater than. If set, value must be greater than this. Only applicable to
1684 numbers.
1685 """
1686 ),
1687 ] = None,
1688 ge: Annotated[
1689 Optional[float],
1690 Doc(
1691 """
1692 Greater than or equal. If set, value must be greater than or equal to
1693 this. Only applicable to numbers.
1694 """
1695 ),
1696 ] = None,
1697 lt: Annotated[
1698 Optional[float],
1699 Doc(
1700 """
1701 Less than. If set, value must be less than this. Only applicable to numbers.
1702 """
1703 ),
1704 ] = None,
1705 le: Annotated[
1706 Optional[float],
1707 Doc(
1708 """
1709 Less than or equal. If set, value must be less than or equal to this.
1710 Only applicable to numbers.
1711 """
1712 ),
1713 ] = None,
1714 min_length: Annotated[
1715 Optional[int],
1716 Doc(
1717 """
1718 Minimum length for strings.
1719 """
1720 ),
1721 ] = None,
1722 max_length: Annotated[
1723 Optional[int],
1724 Doc(
1725 """
1726 Maximum length for strings.
1727 """
1728 ),
1729 ] = None,
1730 pattern: Annotated[
1731 Optional[str],
1732 Doc(
1733 """
1734 RegEx pattern for strings.
1735 """
1736 ),
1737 ] = None,
1738 regex: Annotated[
1739 Optional[str],
1740 Doc(
1741 """
1742 RegEx pattern for strings.
1743 """
1744 ),
1745 deprecated(
1746 "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
1747 ),
1748 ] = None,
1749 discriminator: Annotated[
1750 Union[str, None],
1751 Doc(
1752 """
1753 Parameter field name for discriminating the type in a tagged union.
1754 """
1755 ),
1756 ] = None,
1757 strict: Annotated[
1758 Union[bool, None],
1759 Doc(
1760 """
1761 If `True`, strict validation is applied to the field.
1762 """
1763 ),
1764 ] = _Unset,
1765 multiple_of: Annotated[
1766 Union[float, None],
1767 Doc(
1768 """
1769 Value must be a multiple of this. Only applicable to numbers.
1770 """
1771 ),
1772 ] = _Unset,
1773 allow_inf_nan: Annotated[
1774 Union[bool, None],
1775 Doc(
1776 """
1777 Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
1778 """
1779 ),
1780 ] = _Unset,
1781 max_digits: Annotated[
1782 Union[int, None],
1783 Doc(
1784 """
1785 Maximum number of allow digits for strings.
1786 """
1787 ),
1788 ] = _Unset,
1789 decimal_places: Annotated[
1790 Union[int, None],
1791 Doc(
1792 """
1793 Maximum number of decimal places allowed for numbers.
1794 """
1795 ),
1796 ] = _Unset,
1797 examples: Annotated[
1798 Optional[List[Any]],
1799 Doc(
1800 """
1801 Example values for this field.
1802 """
1803 ),
1804 ] = None,
1805 example: Annotated[
1806 Optional[Any],
1807 deprecated(
1808 "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
1809 "although still supported. Use examples instead."
1810 ),
1811 ] = _Unset,
1812 openapi_examples: Annotated[
1813 Optional[Dict[str, Example]],
1814 Doc(
1815 """
1816 OpenAPI-specific examples.
1818 It will be added to the generated OpenAPI (e.g. visible at `/docs`).
1820 Swagger UI (that provides the `/docs` interface) has better support for the
1821 OpenAPI-specific examples than the JSON Schema `examples`, that's the main
1822 use case for this.
1824 Read more about it in the
1825 [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
1826 """
1827 ),
1828 ] = None,
1829 deprecated: Annotated[
1830 Union[deprecated, str, bool, None],
1831 Doc(
1832 """
1833 Mark this parameter field as deprecated.
1835 It will affect the generated OpenAPI (e.g. visible at `/docs`).
1836 """
1837 ),
1838 ] = None,
1839 include_in_schema: Annotated[
1840 bool,
1841 Doc(
1842 """
1843 To include (or not) this parameter field in the generated OpenAPI.
1844 You probably don't need it, but it's available.
1846 This affects the generated OpenAPI (e.g. visible at `/docs`).
1847 """
1848 ),
1849 ] = True,
1850 json_schema_extra: Annotated[
1851 Union[Dict[str, Any], None],
1852 Doc(
1853 """
1854 Any additional JSON schema data.
1855 """
1856 ),
1857 ] = None,
1858 **extra: Annotated[
1859 Any,
1860 Doc(
1861 """
1862 Include extra fields used by the JSON Schema.
1863 """
1864 ),
1865 deprecated(
1866 """
1867 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
1868 """
1869 ),
1870 ],
1871) -> Any:
1872 return params.Form( 1abcde
1873 default=default,
1874 default_factory=default_factory,
1875 media_type=media_type,
1876 alias=alias,
1877 alias_priority=alias_priority,
1878 validation_alias=validation_alias,
1879 serialization_alias=serialization_alias,
1880 title=title,
1881 description=description,
1882 gt=gt,
1883 ge=ge,
1884 lt=lt,
1885 le=le,
1886 min_length=min_length,
1887 max_length=max_length,
1888 pattern=pattern,
1889 regex=regex,
1890 discriminator=discriminator,
1891 strict=strict,
1892 multiple_of=multiple_of,
1893 allow_inf_nan=allow_inf_nan,
1894 max_digits=max_digits,
1895 decimal_places=decimal_places,
1896 example=example,
1897 examples=examples,
1898 openapi_examples=openapi_examples,
1899 deprecated=deprecated,
1900 include_in_schema=include_in_schema,
1901 json_schema_extra=json_schema_extra,
1902 **extra,
1903 )
1906def File( # noqa: N802 1abcde
1907 default: Annotated[
1908 Any,
1909 Doc(
1910 """
1911 Default value if the parameter field is not set.
1912 """
1913 ),
1914 ] = Undefined,
1915 *,
1916 default_factory: Annotated[
1917 Union[Callable[[], Any], None],
1918 Doc(
1919 """
1920 A callable to generate the default value.
1922 This doesn't affect `Path` parameters as the value is always required.
1923 The parameter is available only for compatibility.
1924 """
1925 ),
1926 ] = _Unset,
1927 media_type: Annotated[
1928 str,
1929 Doc(
1930 """
1931 The media type of this parameter field. Changing it would affect the
1932 generated OpenAPI, but currently it doesn't affect the parsing of the data.
1933 """
1934 ),
1935 ] = "multipart/form-data",
1936 alias: Annotated[
1937 Optional[str],
1938 Doc(
1939 """
1940 An alternative name for the parameter field.
1942 This will be used to extract the data and for the generated OpenAPI.
1943 It is particularly useful when you can't use the name you want because it
1944 is a Python reserved keyword or similar.
1945 """
1946 ),
1947 ] = None,
1948 alias_priority: Annotated[
1949 Union[int, None],
1950 Doc(
1951 """
1952 Priority of the alias. This affects whether an alias generator is used.
1953 """
1954 ),
1955 ] = _Unset,
1956 # TODO: update when deprecating Pydantic v1, import these types
1957 # validation_alias: str | AliasPath | AliasChoices | None
1958 validation_alias: Annotated[
1959 Union[str, None],
1960 Doc(
1961 """
1962 'Whitelist' validation step. The parameter field will be the single one
1963 allowed by the alias or set of aliases defined.
1964 """
1965 ),
1966 ] = None,
1967 serialization_alias: Annotated[
1968 Union[str, None],
1969 Doc(
1970 """
1971 'Blacklist' validation step. The vanilla parameter field will be the
1972 single one of the alias' or set of aliases' fields and all the other
1973 fields will be ignored at serialization time.
1974 """
1975 ),
1976 ] = None,
1977 title: Annotated[
1978 Optional[str],
1979 Doc(
1980 """
1981 Human-readable title.
1982 """
1983 ),
1984 ] = None,
1985 description: Annotated[
1986 Optional[str],
1987 Doc(
1988 """
1989 Human-readable description.
1990 """
1991 ),
1992 ] = None,
1993 gt: Annotated[
1994 Optional[float],
1995 Doc(
1996 """
1997 Greater than. If set, value must be greater than this. Only applicable to
1998 numbers.
1999 """
2000 ),
2001 ] = None,
2002 ge: Annotated[
2003 Optional[float],
2004 Doc(
2005 """
2006 Greater than or equal. If set, value must be greater than or equal to
2007 this. Only applicable to numbers.
2008 """
2009 ),
2010 ] = None,
2011 lt: Annotated[
2012 Optional[float],
2013 Doc(
2014 """
2015 Less than. If set, value must be less than this. Only applicable to numbers.
2016 """
2017 ),
2018 ] = None,
2019 le: Annotated[
2020 Optional[float],
2021 Doc(
2022 """
2023 Less than or equal. If set, value must be less than or equal to this.
2024 Only applicable to numbers.
2025 """
2026 ),
2027 ] = None,
2028 min_length: Annotated[
2029 Optional[int],
2030 Doc(
2031 """
2032 Minimum length for strings.
2033 """
2034 ),
2035 ] = None,
2036 max_length: Annotated[
2037 Optional[int],
2038 Doc(
2039 """
2040 Maximum length for strings.
2041 """
2042 ),
2043 ] = None,
2044 pattern: Annotated[
2045 Optional[str],
2046 Doc(
2047 """
2048 RegEx pattern for strings.
2049 """
2050 ),
2051 ] = None,
2052 regex: Annotated[
2053 Optional[str],
2054 Doc(
2055 """
2056 RegEx pattern for strings.
2057 """
2058 ),
2059 deprecated(
2060 "Deprecated in FastAPI 0.100.0 and Pydantic v2, use `pattern` instead."
2061 ),
2062 ] = None,
2063 discriminator: Annotated[
2064 Union[str, None],
2065 Doc(
2066 """
2067 Parameter field name for discriminating the type in a tagged union.
2068 """
2069 ),
2070 ] = None,
2071 strict: Annotated[
2072 Union[bool, None],
2073 Doc(
2074 """
2075 If `True`, strict validation is applied to the field.
2076 """
2077 ),
2078 ] = _Unset,
2079 multiple_of: Annotated[
2080 Union[float, None],
2081 Doc(
2082 """
2083 Value must be a multiple of this. Only applicable to numbers.
2084 """
2085 ),
2086 ] = _Unset,
2087 allow_inf_nan: Annotated[
2088 Union[bool, None],
2089 Doc(
2090 """
2091 Allow `inf`, `-inf`, `nan`. Only applicable to numbers.
2092 """
2093 ),
2094 ] = _Unset,
2095 max_digits: Annotated[
2096 Union[int, None],
2097 Doc(
2098 """
2099 Maximum number of allow digits for strings.
2100 """
2101 ),
2102 ] = _Unset,
2103 decimal_places: Annotated[
2104 Union[int, None],
2105 Doc(
2106 """
2107 Maximum number of decimal places allowed for numbers.
2108 """
2109 ),
2110 ] = _Unset,
2111 examples: Annotated[
2112 Optional[List[Any]],
2113 Doc(
2114 """
2115 Example values for this field.
2116 """
2117 ),
2118 ] = None,
2119 example: Annotated[
2120 Optional[Any],
2121 deprecated(
2122 "Deprecated in OpenAPI 3.1.0 that now uses JSON Schema 2020-12, "
2123 "although still supported. Use examples instead."
2124 ),
2125 ] = _Unset,
2126 openapi_examples: Annotated[
2127 Optional[Dict[str, Example]],
2128 Doc(
2129 """
2130 OpenAPI-specific examples.
2132 It will be added to the generated OpenAPI (e.g. visible at `/docs`).
2134 Swagger UI (that provides the `/docs` interface) has better support for the
2135 OpenAPI-specific examples than the JSON Schema `examples`, that's the main
2136 use case for this.
2138 Read more about it in the
2139 [FastAPI docs for Declare Request Example Data](https://fastapi.tiangolo.com/tutorial/schema-extra-example/#using-the-openapi_examples-parameter).
2140 """
2141 ),
2142 ] = None,
2143 deprecated: Annotated[
2144 Union[deprecated, str, bool, None],
2145 Doc(
2146 """
2147 Mark this parameter field as deprecated.
2149 It will affect the generated OpenAPI (e.g. visible at `/docs`).
2150 """
2151 ),
2152 ] = None,
2153 include_in_schema: Annotated[
2154 bool,
2155 Doc(
2156 """
2157 To include (or not) this parameter field in the generated OpenAPI.
2158 You probably don't need it, but it's available.
2160 This affects the generated OpenAPI (e.g. visible at `/docs`).
2161 """
2162 ),
2163 ] = True,
2164 json_schema_extra: Annotated[
2165 Union[Dict[str, Any], None],
2166 Doc(
2167 """
2168 Any additional JSON schema data.
2169 """
2170 ),
2171 ] = None,
2172 **extra: Annotated[
2173 Any,
2174 Doc(
2175 """
2176 Include extra fields used by the JSON Schema.
2177 """
2178 ),
2179 deprecated(
2180 """
2181 The `extra` kwargs is deprecated. Use `json_schema_extra` instead.
2182 """
2183 ),
2184 ],
2185) -> Any:
2186 return params.File( 1abcde
2187 default=default,
2188 default_factory=default_factory,
2189 media_type=media_type,
2190 alias=alias,
2191 alias_priority=alias_priority,
2192 validation_alias=validation_alias,
2193 serialization_alias=serialization_alias,
2194 title=title,
2195 description=description,
2196 gt=gt,
2197 ge=ge,
2198 lt=lt,
2199 le=le,
2200 min_length=min_length,
2201 max_length=max_length,
2202 pattern=pattern,
2203 regex=regex,
2204 discriminator=discriminator,
2205 strict=strict,
2206 multiple_of=multiple_of,
2207 allow_inf_nan=allow_inf_nan,
2208 max_digits=max_digits,
2209 decimal_places=decimal_places,
2210 example=example,
2211 examples=examples,
2212 openapi_examples=openapi_examples,
2213 deprecated=deprecated,
2214 include_in_schema=include_in_schema,
2215 json_schema_extra=json_schema_extra,
2216 **extra,
2217 )
2220def Depends( # noqa: N802 1abcde
2221 dependency: Annotated[
2222 Optional[Callable[..., Any]],
2223 Doc(
2224 """
2225 A "dependable" callable (like a function).
2227 Don't call it directly, FastAPI will call it for you, just pass the object
2228 directly.
2229 """
2230 ),
2231 ] = None,
2232 *,
2233 use_cache: Annotated[
2234 bool,
2235 Doc(
2236 """
2237 By default, after a dependency is called the first time in a request, if
2238 the dependency is declared again for the rest of the request (for example
2239 if the dependency is needed by several dependencies), the value will be
2240 re-used for the rest of the request.
2242 Set `use_cache` to `False` to disable this behavior and ensure the
2243 dependency is called again (if declared more than once) in the same request.
2244 """
2245 ),
2246 ] = True,
2247) -> Any:
2248 """
2249 Declare a FastAPI dependency.
2251 It takes a single "dependable" callable (like a function).
2253 Don't call it directly, FastAPI will call it for you.
2255 Read more about it in the
2256 [FastAPI docs for Dependencies](https://fastapi.tiangolo.com/tutorial/dependencies/).
2258 **Example**
2260 ```python
2261 from typing import Annotated
2263 from fastapi import Depends, FastAPI
2265 app = FastAPI()
2268 async def common_parameters(q: str | None = None, skip: int = 0, limit: int = 100):
2269 return {"q": q, "skip": skip, "limit": limit}
2272 @app.get("/items/")
2273 async def read_items(commons: Annotated[dict, Depends(common_parameters)]):
2274 return commons
2275 ```
2276 """
2277 return params.Depends(dependency=dependency, use_cache=use_cache) 1abcde
2280def Security( # noqa: N802 1abcde
2281 dependency: Annotated[
2282 Optional[Callable[..., Any]],
2283 Doc(
2284 """
2285 A "dependable" callable (like a function).
2287 Don't call it directly, FastAPI will call it for you, just pass the object
2288 directly.
2289 """
2290 ),
2291 ] = None,
2292 *,
2293 scopes: Annotated[
2294 Optional[Sequence[str]],
2295 Doc(
2296 """
2297 OAuth2 scopes required for the *path operation* that uses this Security
2298 dependency.
2300 The term "scope" comes from the OAuth2 specification, it seems to be
2301 intentionaly vague and interpretable. It normally refers to permissions,
2302 in cases to roles.
2304 These scopes are integrated with OpenAPI (and the API docs at `/docs`).
2305 So they are visible in the OpenAPI specification.
2306 )
2307 """
2308 ),
2309 ] = None,
2310 use_cache: Annotated[
2311 bool,
2312 Doc(
2313 """
2314 By default, after a dependency is called the first time in a request, if
2315 the dependency is declared again for the rest of the request (for example
2316 if the dependency is needed by several dependencies), the value will be
2317 re-used for the rest of the request.
2319 Set `use_cache` to `False` to disable this behavior and ensure the
2320 dependency is called again (if declared more than once) in the same request.
2321 """
2322 ),
2323 ] = True,
2324) -> Any:
2325 """
2326 Declare a FastAPI Security dependency.
2328 The only difference with a regular dependency is that it can declare OAuth2
2329 scopes that will be integrated with OpenAPI and the automatic UI docs (by default
2330 at `/docs`).
2332 It takes a single "dependable" callable (like a function).
2334 Don't call it directly, FastAPI will call it for you.
2336 Read more about it in the
2337 [FastAPI docs for Security](https://fastapi.tiangolo.com/tutorial/security/) and
2338 in the
2339 [FastAPI docs for OAuth2 scopes](https://fastapi.tiangolo.com/advanced/security/oauth2-scopes/).
2341 **Example**
2343 ```python
2344 from typing import Annotated
2346 from fastapi import Depends, FastAPI
2348 from .db import User
2349 from .security import get_current_active_user
2351 app = FastAPI()
2353 @app.get("/users/me/items/")
2354 async def read_own_items(
2355 current_user: Annotated[User, Security(get_current_active_user, scopes=["items"])]
2356 ):
2357 return [{"item_id": "Foo", "owner": current_user.username}]
2358 ```
2359 """
2360 return params.Security(dependency=dependency, scopes=scopes, use_cache=use_cache) 1abcde