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