param_functions.py 68 KB

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