| 123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434143514361437143814391440144114421443144414451446144714481449145014511452145314541455145614571458145914601461146214631464146514661467146814691470147114721473147414751476147714781479148014811482148314841485148614871488148914901491149214931494149514961497149814991500150115021503150415051506150715081509151015111512151315141515151615171518151915201521152215231524152515261527152815291530153115321533153415351536153715381539154015411542154315441545154615471548154915501551155215531554155515561557155815591560156115621563156415651566156715681569157015711572157315741575157615771578157915801581158215831584158515861587158815891590159115921593159415951596159715981599160016011602160316041605160616071608160916101611161216131614161516161617161816191620162116221623162416251626162716281629163016311632163316341635163616371638163916401641164216431644164516461647164816491650165116521653165416551656165716581659166016611662166316641665166616671668166916701671167216731674167516761677167816791680168116821683168416851686168716881689169016911692169316941695169616971698169917001701170217031704170517061707170817091710171117121713171417151716171717181719172017211722172317241725172617271728172917301731173217331734173517361737173817391740174117421743174417451746174717481749175017511752175317541755175617571758175917601761176217631764176517661767176817691770177117721773177417751776177717781779178017811782178317841785178617871788178917901791179217931794179517961797179817991800180118021803180418051806180718081809181018111812181318141815181618171818181918201821182218231824182518261827182818291830183118321833183418351836183718381839184018411842184318441845184618471848184918501851185218531854185518561857185818591860186118621863186418651866186718681869187018711872187318741875187618771878187918801881188218831884188518861887188818891890189118921893189418951896189718981899190019011902190319041905190619071908190919101911191219131914191519161917191819191920192119221923192419251926192719281929193019311932193319341935193619371938193919401941194219431944194519461947194819491950195119521953195419551956195719581959196019611962196319641965196619671968196919701971197219731974197519761977197819791980198119821983198419851986198719881989199019911992199319941995199619971998199920002001200220032004200520062007200820092010201120122013201420152016201720182019202020212022202320242025202620272028202920302031203220332034203520362037203820392040204120422043204420452046204720482049205020512052205320542055205620572058205920602061206220632064206520662067206820692070207120722073207420752076207720782079208020812082208320842085208620872088208920902091209220932094209520962097209820992100210121022103210421052106210721082109211021112112211321142115211621172118211921202121212221232124212521262127212821292130213121322133213421352136213721382139214021412142214321442145214621472148214921502151215221532154215521562157215821592160216121622163216421652166216721682169217021712172217321742175217621772178217921802181218221832184218521862187218821892190219121922193219421952196219721982199220022012202220322042205220622072208220922102211221222132214221522162217221822192220222122222223222422252226222722282229223022312232223322342235223622372238223922402241224222432244224522462247224822492250225122522253225422552256225722582259226022612262226322642265226622672268226922702271227222732274227522762277227822792280228122822283228422852286228722882289229022912292229322942295229622972298229923002301230223032304230523062307230823092310231123122313231423152316231723182319232023212322232323242325232623272328232923302331233223332334233523362337233823392340234123422343234423452346234723482349235023512352235323542355235623572358235923602361236223632364236523662367236823692370237123722373237423752376237723782379238023812382238323842385238623872388238923902391239223932394239523962397239823992400240124022403240424052406240724082409241024112412241324142415241624172418241924202421242224232424242524262427242824292430243124322433243424352436243724382439244024412442244324442445244624472448244924502451245224532454245524562457245824592460246124622463246424652466246724682469247024712472247324742475247624772478247924802481248224832484248524862487248824892490249124922493249424952496249724982499250025012502250325042505250625072508250925102511251225132514251525162517251825192520252125222523252425252526252725282529253025312532253325342535253625372538253925402541254225432544254525462547254825492550255125522553255425552556255725582559256025612562256325642565256625672568256925702571257225732574257525762577257825792580258125822583258425852586258725882589259025912592259325942595259625972598259926002601260226032604260526062607260826092610261126122613261426152616261726182619262026212622262326242625262626272628262926302631263226332634263526362637263826392640264126422643264426452646264726482649265026512652265326542655265626572658265926602661266226632664266526662667266826692670267126722673267426752676267726782679268026812682268326842685268626872688268926902691269226932694269526962697269826992700270127022703270427052706270727082709271027112712271327142715271627172718271927202721272227232724272527262727272827292730273127322733273427352736273727382739274027412742274327442745274627472748274927502751275227532754275527562757275827592760276127622763276427652766276727682769277027712772277327742775277627772778277927802781278227832784278527862787278827892790279127922793279427952796279727982799280028012802280328042805280628072808280928102811281228132814281528162817281828192820282128222823282428252826282728282829283028312832283328342835283628372838283928402841284228432844284528462847284828492850285128522853285428552856285728582859286028612862286328642865286628672868286928702871287228732874287528762877287828792880288128822883288428852886288728882889289028912892289328942895289628972898289929002901290229032904290529062907290829092910291129122913291429152916291729182919292029212922292329242925292629272928292929302931293229332934293529362937293829392940294129422943294429452946294729482949295029512952295329542955295629572958295929602961296229632964296529662967296829692970297129722973297429752976297729782979298029812982298329842985298629872988298929902991299229932994299529962997299829993000300130023003300430053006300730083009301030113012301330143015301630173018301930203021302230233024302530263027302830293030303130323033303430353036303730383039304030413042304330443045304630473048304930503051305230533054305530563057305830593060306130623063306430653066306730683069307030713072307330743075307630773078307930803081308230833084308530863087308830893090309130923093309430953096309730983099310031013102310331043105310631073108310931103111311231133114311531163117311831193120312131223123312431253126312731283129313031313132313331343135313631373138313931403141314231433144314531463147314831493150315131523153315431553156315731583159316031613162316331643165316631673168316931703171317231733174317531763177317831793180318131823183318431853186318731883189319031913192319331943195319631973198319932003201320232033204320532063207320832093210321132123213321432153216321732183219322032213222322332243225322632273228322932303231323232333234323532363237323832393240324132423243324432453246324732483249325032513252325332543255325632573258325932603261326232633264326532663267326832693270327132723273327432753276327732783279328032813282328332843285328632873288328932903291329232933294329532963297329832993300330133023303330433053306330733083309331033113312331333143315331633173318331933203321332233233324332533263327332833293330333133323333333433353336333733383339334033413342334333443345334633473348334933503351335233533354335533563357335833593360336133623363336433653366336733683369337033713372337333743375337633773378337933803381338233833384338533863387338833893390339133923393339433953396339733983399340034013402340334043405340634073408340934103411341234133414341534163417341834193420342134223423342434253426342734283429343034313432343334343435343634373438343934403441344234433444344534463447344834493450345134523453345434553456345734583459346034613462346334643465346634673468346934703471347234733474347534763477347834793480348134823483348434853486348734883489349034913492349334943495349634973498349935003501350235033504350535063507350835093510351135123513351435153516351735183519352035213522352335243525352635273528352935303531353235333534353535363537353835393540354135423543354435453546354735483549355035513552355335543555355635573558355935603561356235633564356535663567356835693570357135723573357435753576357735783579358035813582358335843585358635873588358935903591359235933594359535963597359835993600360136023603360436053606360736083609361036113612361336143615361636173618361936203621362236233624362536263627362836293630363136323633363436353636363736383639364036413642364336443645364636473648364936503651365236533654365536563657365836593660366136623663366436653666366736683669367036713672367336743675367636773678367936803681368236833684368536863687368836893690369136923693369436953696369736983699370037013702370337043705370637073708370937103711371237133714371537163717371837193720372137223723372437253726372737283729373037313732373337343735373637373738373937403741374237433744374537463747374837493750375137523753375437553756375737583759376037613762376337643765376637673768376937703771377237733774377537763777377837793780378137823783378437853786378737883789379037913792379337943795379637973798379938003801380238033804380538063807380838093810381138123813381438153816381738183819382038213822382338243825382638273828382938303831383238333834383538363837383838393840384138423843384438453846384738483849385038513852385338543855385638573858385938603861386238633864386538663867386838693870387138723873387438753876387738783879388038813882388338843885388638873888388938903891389238933894389538963897389838993900390139023903390439053906390739083909391039113912391339143915391639173918391939203921392239233924392539263927392839293930393139323933393439353936393739383939394039413942394339443945394639473948394939503951395239533954395539563957395839593960396139623963396439653966396739683969397039713972397339743975397639773978397939803981398239833984398539863987398839893990399139923993399439953996399739983999400040014002400340044005400640074008400940104011401240134014401540164017401840194020402140224023402440254026402740284029403040314032403340344035403640374038403940404041404240434044404540464047404840494050405140524053405440554056405740584059406040614062406340644065406640674068406940704071407240734074407540764077407840794080408140824083408440854086408740884089409040914092409340944095409640974098409941004101410241034104410541064107410841094110411141124113411441154116411741184119412041214122412341244125412641274128412941304131413241334134413541364137413841394140414141424143414441454146414741484149415041514152415341544155415641574158415941604161416241634164416541664167416841694170417141724173417441754176417741784179418041814182418341844185418641874188418941904191419241934194419541964197419841994200420142024203420442054206420742084209421042114212421342144215421642174218421942204221422242234224422542264227422842294230423142324233423442354236423742384239424042414242424342444245424642474248424942504251425242534254425542564257425842594260426142624263426442654266426742684269427042714272427342744275427642774278427942804281428242834284428542864287428842894290429142924293429442954296429742984299430043014302430343044305430643074308430943104311431243134314431543164317431843194320432143224323432443254326432743284329433043314332433343344335433643374338433943404341434243434344434543464347434843494350435143524353435443554356435743584359436043614362436343644365436643674368436943704371437243734374437543764377437843794380438143824383438443854386438743884389439043914392439343944395439643974398439944004401440244034404440544064407440844094410441144124413441444154416441744184419442044214422442344244425442644274428442944304431443244334434443544364437443844394440444144424443444444454446444744484449445044514452445344544455445644574458445944604461446244634464446544664467446844694470447144724473447444754476447744784479448044814482448344844485448644874488448944904491449244934494449544964497449844994500450145024503450445054506450745084509451045114512451345144515451645174518451945204521452245234524452545264527452845294530453145324533453445354536453745384539454045414542454345444545454645474548454945504551455245534554455545564557455845594560456145624563456445654566456745684569457045714572457345744575457645774578457945804581458245834584458545864587458845894590459145924593459445954596459745984599460046014602460346044605460646074608460946104611461246134614461546164617461846194620462146224623462446254626462746284629463046314632463346344635463646374638463946404641464246434644464546464647464846494650465146524653465446554656465746584659466046614662466346644665466646674668466946704671467246734674467546764677467846794680468146824683468446854686468746884689469046914692469346944695469646974698469947004701470247034704470547064707470847094710471147124713471447154716471747184719472047214722472347244725472647274728472947304731473247334734473547364737473847394740474147424743474447454746474747484749475047514752475347544755475647574758475947604761476247634764476547664767476847694770477147724773477447754776477747784779478047814782478347844785478647874788478947904791479247934794479547964797479847994800480148024803480448054806480748084809481048114812481348144815481648174818481948204821482248234824482548264827482848294830483148324833483448354836483748384839484048414842484348444845484648474848484948504851485248534854485548564857485848594860486148624863486448654866486748684869487048714872487348744875487648774878487948804881488248834884488548864887488848894890489148924893489448954896489748984899490049014902490349044905490649074908490949104911491249134914491549164917491849194920492149224923492449254926492749284929493049314932493349344935493649374938493949404941494249434944494549464947494849494950495149524953495449554956 |
- import contextlib
- import email.message
- import functools
- import inspect
- import json
- import types
- from collections.abc import (
- AsyncIterator,
- Awaitable,
- Callable,
- Collection,
- Coroutine,
- Generator,
- Iterator,
- Mapping,
- Sequence,
- )
- from contextlib import (
- AbstractAsyncContextManager,
- AbstractContextManager,
- AsyncExitStack,
- asynccontextmanager,
- )
- from enum import Enum, IntEnum
- from typing import (
- Annotated,
- Any,
- TypeVar,
- cast,
- )
- import anyio
- from annotated_doc import Doc
- from anyio.abc import ObjectReceiveStream
- from fastapi import params
- from fastapi._compat import (
- ModelField,
- Undefined,
- lenient_issubclass,
- )
- from fastapi.datastructures import Default, DefaultPlaceholder
- from fastapi.dependencies.models import Dependant
- from fastapi.dependencies.utils import (
- _should_embed_body_fields,
- get_body_field,
- get_dependant,
- get_flat_dependant,
- get_parameterless_sub_dependant,
- get_stream_item_type,
- get_typed_return_annotation,
- solve_dependencies,
- )
- from fastapi.encoders import jsonable_encoder
- from fastapi.exceptions import (
- EndpointContext,
- FastAPIError,
- RequestValidationError,
- ResponseValidationError,
- WebSocketRequestValidationError,
- )
- from fastapi.sse import (
- _PING_INTERVAL,
- KEEPALIVE_COMMENT,
- EventSourceResponse,
- ServerSentEvent,
- format_sse_event,
- )
- from fastapi.types import DecoratedCallable, IncEx
- from fastapi.utils import (
- create_model_field,
- generate_unique_id,
- get_value_or_default,
- is_body_allowed_for_status_code,
- )
- from starlette import routing
- from starlette._exception_handler import wrap_app_handling_exceptions
- from starlette._utils import is_async_callable
- from starlette.concurrency import iterate_in_threadpool, run_in_threadpool
- from starlette.datastructures import FormData
- from starlette.exceptions import HTTPException
- from starlette.requests import Request
- from starlette.responses import JSONResponse, Response, StreamingResponse
- from starlette.routing import (
- BaseRoute,
- Match,
- compile_path,
- get_name,
- )
- from starlette.routing import Mount as Mount # noqa
- from starlette.types import AppType, ASGIApp, Lifespan, Receive, Scope, Send
- from starlette.websockets import WebSocket
- from typing_extensions import deprecated
- # Copy of starlette.routing.request_response modified to include the
- # dependencies' AsyncExitStack
- def request_response(
- func: Callable[[Request], Awaitable[Response] | Response],
- ) -> ASGIApp:
- """
- Takes a function or coroutine `func(request) -> response`,
- and returns an ASGI application.
- """
- f: Callable[[Request], Awaitable[Response]] = (
- func # type: ignore[assignment] # ty: ignore[unused-ignore-comment]
- if is_async_callable(func)
- else functools.partial(run_in_threadpool, func) # type: ignore[call-arg] # ty: ignore[unused-ignore-comment]
- ) # ty: ignore[invalid-assignment]
- async def app(scope: Scope, receive: Receive, send: Send) -> None:
- request = Request(scope, receive, send)
- async def app(scope: Scope, receive: Receive, send: Send) -> None:
- # Starts customization
- response_awaited = False
- async with AsyncExitStack() as request_stack:
- scope["fastapi_inner_astack"] = request_stack
- async with AsyncExitStack() as function_stack:
- scope["fastapi_function_astack"] = function_stack
- response = await f(request)
- await response(scope, receive, send)
- # Continues customization
- response_awaited = True
- if not response_awaited:
- raise FastAPIError(
- "Response not awaited. There's a high chance that the "
- "application code is raising an exception and a dependency with yield "
- "has a block with a bare except, or a block with except Exception, "
- "and is not raising the exception again. Read more about it in the "
- "docs: https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#dependencies-with-yield-and-except"
- )
- # Same as in Starlette
- await wrap_app_handling_exceptions(app, request)(scope, receive, send)
- return app
- # Copy of starlette.routing.websocket_session modified to include the
- # dependencies' AsyncExitStack
- def websocket_session(
- func: Callable[[WebSocket], Awaitable[None]],
- ) -> ASGIApp:
- """
- Takes a coroutine `func(session)`, and returns an ASGI application.
- """
- # assert asyncio.iscoroutinefunction(func), "WebSocket endpoints must be async"
- async def app(scope: Scope, receive: Receive, send: Send) -> None:
- session = WebSocket(scope, receive=receive, send=send)
- async def app(scope: Scope, receive: Receive, send: Send) -> None:
- async with AsyncExitStack() as request_stack:
- scope["fastapi_inner_astack"] = request_stack
- async with AsyncExitStack() as function_stack:
- scope["fastapi_function_astack"] = function_stack
- await func(session)
- # Same as in Starlette
- await wrap_app_handling_exceptions(app, session)(scope, receive, send)
- return app
- _T = TypeVar("_T")
- # Vendored from starlette.routing to avoid importing private symbols
- class _AsyncLiftContextManager(AbstractAsyncContextManager[_T]):
- """
- Wraps a synchronous context manager to make it async.
- This is vendored from Starlette to avoid importing private symbols.
- """
- def __init__(self, cm: AbstractContextManager[_T]) -> None:
- self._cm = cm
- async def __aenter__(self) -> _T:
- return self._cm.__enter__()
- async def __aexit__(
- self,
- exc_type: type[BaseException] | None,
- exc_value: BaseException | None,
- traceback: types.TracebackType | None,
- ) -> bool | None:
- return self._cm.__exit__(exc_type, exc_value, traceback)
- # Vendored from starlette.routing to avoid importing private symbols
- def _wrap_gen_lifespan_context(
- lifespan_context: Callable[[Any], Generator[Any, Any, Any]],
- ) -> Callable[[Any], AbstractAsyncContextManager[Any]]:
- """
- Wrap a generator-based lifespan context into an async context manager.
- This is vendored from Starlette to avoid importing private symbols.
- """
- cmgr = contextlib.contextmanager(lifespan_context)
- @functools.wraps(cmgr)
- def wrapper(app: Any) -> _AsyncLiftContextManager[Any]:
- return _AsyncLiftContextManager(cmgr(app))
- return wrapper
- def _merge_lifespan_context(
- original_context: Lifespan[Any], nested_context: Lifespan[Any]
- ) -> Lifespan[Any]:
- @asynccontextmanager
- async def merged_lifespan(
- app: AppType,
- ) -> AsyncIterator[Mapping[str, Any] | None]:
- async with original_context(app) as maybe_original_state:
- async with nested_context(app) as maybe_nested_state:
- if maybe_nested_state is None and maybe_original_state is None:
- yield None # old ASGI compatibility
- else:
- yield {**(maybe_nested_state or {}), **(maybe_original_state or {})}
- return merged_lifespan # type: ignore[return-value]
- class _DefaultLifespan:
- """
- Default lifespan context manager that runs on_startup and on_shutdown handlers.
- This is a copy of the Starlette _DefaultLifespan class that was removed
- in Starlette. FastAPI keeps it to maintain backward compatibility with
- on_startup and on_shutdown event handlers.
- Ref: https://github.com/Kludex/starlette/pull/3117
- """
- def __init__(self, router: "APIRouter") -> None:
- self._router = router
- async def __aenter__(self) -> None:
- await self._router._startup()
- async def __aexit__(self, *exc_info: object) -> None:
- await self._router._shutdown()
- def __call__(self: _T, app: object) -> _T:
- return self
- # Cache for endpoint context to avoid re-extracting on every request
- _endpoint_context_cache: dict[int, EndpointContext] = {}
- def _extract_endpoint_context(func: Any) -> EndpointContext:
- """Extract endpoint context with caching to avoid repeated file I/O."""
- func_id = id(func)
- if func_id in _endpoint_context_cache:
- return _endpoint_context_cache[func_id]
- try:
- ctx: EndpointContext = {}
- if (source_file := inspect.getsourcefile(func)) is not None:
- ctx["file"] = source_file
- if (line_number := inspect.getsourcelines(func)[1]) is not None:
- ctx["line"] = line_number
- if (func_name := getattr(func, "__name__", None)) is not None:
- ctx["function"] = func_name
- except Exception:
- ctx = EndpointContext()
- _endpoint_context_cache[func_id] = ctx
- return ctx
- async def serialize_response(
- *,
- field: ModelField | None = None,
- response_content: Any,
- include: IncEx | None = None,
- exclude: IncEx | None = None,
- by_alias: bool = True,
- exclude_unset: bool = False,
- exclude_defaults: bool = False,
- exclude_none: bool = False,
- is_coroutine: bool = True,
- endpoint_ctx: EndpointContext | None = None,
- dump_json: bool = False,
- ) -> Any:
- if field:
- if is_coroutine:
- value, errors = field.validate(response_content, {}, loc=("response",))
- else:
- value, errors = await run_in_threadpool(
- field.validate, response_content, {}, loc=("response",)
- )
- if errors:
- ctx = endpoint_ctx or EndpointContext()
- raise ResponseValidationError(
- errors=errors,
- body=response_content,
- endpoint_ctx=ctx,
- )
- serializer = field.serialize_json if dump_json else field.serialize
- return serializer(
- value,
- include=include,
- exclude=exclude,
- by_alias=by_alias,
- exclude_unset=exclude_unset,
- exclude_defaults=exclude_defaults,
- exclude_none=exclude_none,
- )
- else:
- return jsonable_encoder(response_content)
- async def run_endpoint_function(
- *, dependant: Dependant, values: dict[str, Any], is_coroutine: bool
- ) -> Any:
- # Only called by get_request_handler. Has been split into its own function to
- # facilitate profiling endpoints, since inner functions are harder to profile.
- assert dependant.call is not None, "dependant.call must be a function"
- if is_coroutine:
- return await dependant.call(**values)
- else:
- return await run_in_threadpool(dependant.call, **values)
- def _build_response_args(
- *, status_code: int | None, solved_result: Any
- ) -> dict[str, Any]:
- response_args: dict[str, Any] = {
- "background": solved_result.background_tasks,
- }
- # If status_code was set, use it, otherwise use the default from the
- # response class, in the case of redirect it's 307
- current_status_code = (
- status_code if status_code else solved_result.response.status_code
- )
- if current_status_code is not None:
- response_args["status_code"] = current_status_code
- if solved_result.response.status_code:
- response_args["status_code"] = solved_result.response.status_code
- return response_args
- def get_request_handler(
- dependant: Dependant,
- body_field: ModelField | None = None,
- status_code: int | None = None,
- response_class: type[Response] | DefaultPlaceholder = Default(JSONResponse),
- response_field: ModelField | None = None,
- response_model_include: IncEx | None = None,
- response_model_exclude: IncEx | None = None,
- response_model_by_alias: bool = True,
- response_model_exclude_unset: bool = False,
- response_model_exclude_defaults: bool = False,
- response_model_exclude_none: bool = False,
- dependency_overrides_provider: Any | None = None,
- embed_body_fields: bool = False,
- strict_content_type: bool | DefaultPlaceholder = Default(True),
- stream_item_field: ModelField | None = None,
- is_json_stream: bool = False,
- ) -> Callable[[Request], Coroutine[Any, Any, Response]]:
- assert dependant.call is not None, "dependant.call must be a function"
- is_coroutine = dependant.is_coroutine_callable
- is_body_form = body_field and isinstance(body_field.field_info, params.Form)
- if isinstance(response_class, DefaultPlaceholder):
- actual_response_class: type[Response] = response_class.value
- else:
- actual_response_class = response_class
- is_sse_stream = lenient_issubclass(actual_response_class, EventSourceResponse)
- if isinstance(strict_content_type, DefaultPlaceholder):
- actual_strict_content_type: bool = strict_content_type.value
- else:
- actual_strict_content_type = strict_content_type
- async def app(request: Request) -> Response:
- response: Response | None = None
- file_stack = request.scope.get("fastapi_middleware_astack")
- assert isinstance(file_stack, AsyncExitStack), (
- "fastapi_middleware_astack not found in request scope"
- )
- # Extract endpoint context for error messages
- endpoint_ctx = (
- _extract_endpoint_context(dependant.call)
- if dependant.call
- else EndpointContext()
- )
- if dependant.path:
- # For mounted sub-apps, include the mount path prefix
- mount_path = request.scope.get("root_path", "").rstrip("/")
- endpoint_ctx["path"] = f"{request.method} {mount_path}{dependant.path}"
- # Read body and auto-close files
- try:
- body: Any = None
- if body_field:
- if is_body_form:
- body = await request.form()
- file_stack.push_async_callback(body.close)
- else:
- body_bytes = await request.body()
- if body_bytes:
- json_body: Any = Undefined
- content_type_value = request.headers.get("content-type")
- if not content_type_value:
- if not actual_strict_content_type:
- json_body = await request.json()
- else:
- message = email.message.Message()
- message["content-type"] = content_type_value
- if message.get_content_maintype() == "application":
- subtype = message.get_content_subtype()
- if subtype == "json" or subtype.endswith("+json"):
- json_body = await request.json()
- if json_body != Undefined:
- body = json_body
- else:
- body = body_bytes
- except json.JSONDecodeError as e:
- validation_error = RequestValidationError(
- [
- {
- "type": "json_invalid",
- "loc": ("body", e.pos),
- "msg": "JSON decode error",
- "input": {},
- "ctx": {"error": e.msg},
- }
- ],
- body=e.doc,
- endpoint_ctx=endpoint_ctx,
- )
- raise validation_error from e
- except HTTPException:
- # If a middleware raises an HTTPException, it should be raised again
- raise
- except Exception as e:
- http_error = HTTPException(
- status_code=400, detail="There was an error parsing the body"
- )
- raise http_error from e
- # Solve dependencies and run path operation function, auto-closing dependencies
- errors: list[Any] = []
- async_exit_stack = request.scope.get("fastapi_inner_astack")
- assert isinstance(async_exit_stack, AsyncExitStack), (
- "fastapi_inner_astack not found in request scope"
- )
- solved_result = await solve_dependencies(
- request=request,
- dependant=dependant,
- body=cast(dict[str, Any] | FormData | bytes | None, body),
- dependency_overrides_provider=dependency_overrides_provider,
- async_exit_stack=async_exit_stack,
- embed_body_fields=embed_body_fields,
- )
- errors = solved_result.errors
- assert dependant.call # For types
- if not errors:
- # Shared serializer for stream items (JSONL and SSE).
- # Validates against stream_item_field when set, then
- # serializes to JSON bytes.
- def _serialize_data(data: Any) -> bytes:
- if stream_item_field:
- value, errors_ = stream_item_field.validate(
- data, {}, loc=("response",)
- )
- if errors_:
- ctx = endpoint_ctx or EndpointContext()
- raise ResponseValidationError(
- errors=errors_,
- body=data,
- endpoint_ctx=ctx,
- )
- return stream_item_field.serialize_json(
- value,
- include=response_model_include,
- exclude=response_model_exclude,
- by_alias=response_model_by_alias,
- exclude_unset=response_model_exclude_unset,
- exclude_defaults=response_model_exclude_defaults,
- exclude_none=response_model_exclude_none,
- )
- else:
- data = jsonable_encoder(data)
- return json.dumps(data).encode("utf-8")
- if is_sse_stream:
- # Generator endpoint: stream as Server-Sent Events
- gen = dependant.call(**solved_result.values)
- def _serialize_sse_item(item: Any) -> bytes:
- if isinstance(item, ServerSentEvent):
- # User controls the event structure.
- # Serialize the data payload if present.
- # For ServerSentEvent items we skip stream_item_field
- # validation (the user may mix types intentionally).
- if item.raw_data is not None:
- data_str: str | None = item.raw_data
- elif item.data is not None:
- if hasattr(item.data, "model_dump_json"):
- data_str = item.data.model_dump_json()
- else:
- data_str = json.dumps(jsonable_encoder(item.data))
- else:
- data_str = None
- return format_sse_event(
- data_str=data_str,
- event=item.event,
- id=item.id,
- retry=item.retry,
- comment=item.comment,
- )
- else:
- # Plain object: validate + serialize via
- # stream_item_field (if set) and wrap in data field
- return format_sse_event(
- data_str=_serialize_data(item).decode("utf-8")
- )
- if dependant.is_async_gen_callable:
- sse_aiter: AsyncIterator[Any] = gen.__aiter__()
- else:
- sse_aiter = iterate_in_threadpool(gen)
- @asynccontextmanager
- async def _sse_producer_cm() -> AsyncIterator[
- ObjectReceiveStream[bytes]
- ]:
- # Use a memory stream to decouple generator iteration
- # from the keepalive timer. A producer task pulls items
- # from the generator independently, so
- # `anyio.fail_after` never wraps the generator's
- # `__anext__` directly - avoiding CancelledError that
- # would finalize the generator and also working for sync
- # generators running in a thread pool.
- #
- # This context manager is entered on the request-scoped
- # AsyncExitStack so its __aexit__ (which cancels the
- # task group) is called by the exit stack after the
- # streaming response completes — not by async generator
- # finalization via GeneratorExit.
- # Ref: https://peps.python.org/pep-0789/
- send_stream, receive_stream = anyio.create_memory_object_stream[
- bytes
- ](max_buffer_size=1)
- async def _producer() -> None:
- async with send_stream:
- async for raw_item in sse_aiter:
- await send_stream.send(_serialize_sse_item(raw_item))
- send_keepalive, receive_keepalive = (
- anyio.create_memory_object_stream[bytes](max_buffer_size=1)
- )
- async def _keepalive_inserter() -> None:
- """Read from the producer and forward to the output,
- inserting keepalive comments on timeout."""
- async with send_keepalive, receive_stream:
- try:
- while True:
- try:
- with anyio.fail_after(_PING_INTERVAL):
- data = await receive_stream.receive()
- await send_keepalive.send(data)
- except TimeoutError:
- await send_keepalive.send(KEEPALIVE_COMMENT)
- except anyio.EndOfStream:
- pass
- async with anyio.create_task_group() as tg:
- tg.start_soon(_producer)
- tg.start_soon(_keepalive_inserter)
- yield receive_keepalive
- tg.cancel_scope.cancel()
- # Enter the SSE context manager on the request-scoped
- # exit stack. The stack outlives the streaming response,
- # so __aexit__ runs via proper structured teardown, not
- # via GeneratorExit thrown into an async generator.
- sse_receive_stream = await async_exit_stack.enter_async_context(
- _sse_producer_cm()
- )
- # Ensure the receive stream is closed when the exit stack
- # unwinds, preventing ResourceWarning from __del__.
- async_exit_stack.push_async_callback(sse_receive_stream.aclose)
- async def _sse_with_checkpoints(
- stream: ObjectReceiveStream[bytes],
- ) -> AsyncIterator[bytes]:
- async for data in stream:
- yield data
- # Guarantee a checkpoint so cancellation can be
- # delivered even when the producer is faster than
- # the consumer and receive() never suspends.
- await anyio.sleep(0)
- sse_stream_content: AsyncIterator[bytes] | Iterator[bytes] = (
- _sse_with_checkpoints(sse_receive_stream)
- )
- response = StreamingResponse(
- sse_stream_content,
- media_type="text/event-stream",
- background=solved_result.background_tasks,
- )
- response.headers["Cache-Control"] = "no-cache"
- # For Nginx proxies to not buffer server sent events
- response.headers["X-Accel-Buffering"] = "no"
- response.headers.raw.extend(solved_result.response.headers.raw)
- elif is_json_stream:
- # Generator endpoint: stream as JSONL
- gen = dependant.call(**solved_result.values)
- def _serialize_item(item: Any) -> bytes:
- return _serialize_data(item) + b"\n"
- if dependant.is_async_gen_callable:
- async def _async_stream_jsonl() -> AsyncIterator[bytes]:
- async for item in gen:
- yield _serialize_item(item)
- # To allow for cancellation to trigger
- # Ref: https://github.com/fastapi/fastapi/issues/14680
- await anyio.sleep(0)
- jsonl_stream_content: AsyncIterator[bytes] | Iterator[bytes] = (
- _async_stream_jsonl()
- )
- else:
- def _sync_stream_jsonl() -> Iterator[bytes]:
- for item in gen: # ty: ignore[not-iterable]
- yield _serialize_item(item)
- jsonl_stream_content = _sync_stream_jsonl()
- response = StreamingResponse(
- jsonl_stream_content,
- media_type="application/jsonl",
- background=solved_result.background_tasks,
- )
- response.headers.raw.extend(solved_result.response.headers.raw)
- elif dependant.is_async_gen_callable or dependant.is_gen_callable:
- # Raw streaming with explicit response_class (e.g. StreamingResponse)
- gen = dependant.call(**solved_result.values)
- if dependant.is_async_gen_callable:
- async def _async_stream_raw(
- async_gen: AsyncIterator[Any],
- ) -> AsyncIterator[Any]:
- async for chunk in async_gen:
- yield chunk
- # To allow for cancellation to trigger
- # Ref: https://github.com/fastapi/fastapi/issues/14680
- await anyio.sleep(0)
- gen = _async_stream_raw(gen)
- response_args = _build_response_args(
- status_code=status_code, solved_result=solved_result
- )
- response = actual_response_class(content=gen, **response_args)
- response.headers.raw.extend(solved_result.response.headers.raw)
- else:
- raw_response = await run_endpoint_function(
- dependant=dependant,
- values=solved_result.values,
- is_coroutine=is_coroutine,
- )
- if isinstance(raw_response, Response):
- if raw_response.background is None:
- raw_response.background = solved_result.background_tasks
- response = raw_response
- else:
- response_args = _build_response_args(
- status_code=status_code, solved_result=solved_result
- )
- # Use the fast path (dump_json) when no custom response
- # class was set and a response field with a TypeAdapter
- # exists. Serializes directly to JSON bytes via Pydantic's
- # Rust core, skipping the intermediate Python dict +
- # json.dumps() step.
- use_dump_json = response_field is not None and isinstance(
- response_class, DefaultPlaceholder
- )
- content = await serialize_response(
- field=response_field,
- response_content=raw_response,
- include=response_model_include,
- exclude=response_model_exclude,
- by_alias=response_model_by_alias,
- exclude_unset=response_model_exclude_unset,
- exclude_defaults=response_model_exclude_defaults,
- exclude_none=response_model_exclude_none,
- is_coroutine=is_coroutine,
- endpoint_ctx=endpoint_ctx,
- dump_json=use_dump_json,
- )
- if use_dump_json:
- response = Response(
- content=content,
- media_type="application/json",
- **response_args,
- )
- else:
- response = actual_response_class(content, **response_args)
- if not is_body_allowed_for_status_code(response.status_code):
- response.body = b""
- response.headers.raw.extend(solved_result.response.headers.raw)
- if errors:
- validation_error = RequestValidationError(
- errors, body=body, endpoint_ctx=endpoint_ctx
- )
- raise validation_error
- # Return response
- assert response
- return response
- return app
- def get_websocket_app(
- dependant: Dependant,
- dependency_overrides_provider: Any | None = None,
- embed_body_fields: bool = False,
- ) -> Callable[[WebSocket], Coroutine[Any, Any, Any]]:
- async def app(websocket: WebSocket) -> None:
- endpoint_ctx = (
- _extract_endpoint_context(dependant.call)
- if dependant.call
- else EndpointContext()
- )
- if dependant.path:
- # For mounted sub-apps, include the mount path prefix
- mount_path = websocket.scope.get("root_path", "").rstrip("/")
- endpoint_ctx["path"] = f"WS {mount_path}{dependant.path}"
- async_exit_stack = websocket.scope.get("fastapi_inner_astack")
- assert isinstance(async_exit_stack, AsyncExitStack), (
- "fastapi_inner_astack not found in request scope"
- )
- solved_result = await solve_dependencies(
- request=websocket,
- dependant=dependant,
- dependency_overrides_provider=dependency_overrides_provider,
- async_exit_stack=async_exit_stack,
- embed_body_fields=embed_body_fields,
- )
- if solved_result.errors:
- raise WebSocketRequestValidationError(
- solved_result.errors,
- endpoint_ctx=endpoint_ctx,
- )
- assert dependant.call is not None, "dependant.call must be a function"
- await dependant.call(**solved_result.values)
- return app
- class APIWebSocketRoute(routing.WebSocketRoute):
- def __init__(
- self,
- path: str,
- endpoint: Callable[..., Any],
- *,
- name: str | None = None,
- dependencies: Sequence[params.Depends] | None = None,
- dependency_overrides_provider: Any | None = None,
- ) -> None:
- self.path = path
- self.endpoint = endpoint
- self.name = get_name(endpoint) if name is None else name
- self.dependencies = list(dependencies or [])
- self.path_regex, self.path_format, self.param_convertors = compile_path(path)
- self.dependant = get_dependant(
- path=self.path_format, call=self.endpoint, scope="function"
- )
- for depends in self.dependencies[::-1]:
- self.dependant.dependencies.insert(
- 0,
- get_parameterless_sub_dependant(depends=depends, path=self.path_format),
- )
- self._flat_dependant = get_flat_dependant(self.dependant)
- self._embed_body_fields = _should_embed_body_fields(
- self._flat_dependant.body_params
- )
- self.app = websocket_session(
- get_websocket_app(
- dependant=self.dependant,
- dependency_overrides_provider=dependency_overrides_provider,
- embed_body_fields=self._embed_body_fields,
- )
- )
- def matches(self, scope: Scope) -> tuple[Match, Scope]:
- match, child_scope = super().matches(scope)
- if match != Match.NONE:
- child_scope["route"] = self
- return match, child_scope
- class APIRoute(routing.Route):
- def __init__(
- self,
- path: str,
- endpoint: Callable[..., Any],
- *,
- response_model: Any = Default(None),
- status_code: int | None = None,
- tags: list[str | Enum] | None = None,
- dependencies: Sequence[params.Depends] | None = None,
- summary: str | None = None,
- description: str | None = None,
- response_description: str = "Successful Response",
- responses: dict[int | str, dict[str, Any]] | None = None,
- deprecated: bool | None = None,
- name: str | None = None,
- methods: set[str] | list[str] | None = None,
- operation_id: str | None = None,
- response_model_include: IncEx | None = None,
- response_model_exclude: IncEx | None = None,
- response_model_by_alias: bool = True,
- response_model_exclude_unset: bool = False,
- response_model_exclude_defaults: bool = False,
- response_model_exclude_none: bool = False,
- include_in_schema: bool = True,
- response_class: type[Response] | DefaultPlaceholder = Default(JSONResponse),
- dependency_overrides_provider: Any | None = None,
- callbacks: list[BaseRoute] | None = None,
- openapi_extra: dict[str, Any] | None = None,
- generate_unique_id_function: Callable[["APIRoute"], str]
- | DefaultPlaceholder = Default(generate_unique_id),
- strict_content_type: bool | DefaultPlaceholder = Default(True),
- ) -> None:
- self.path = path
- self.endpoint = endpoint
- self.stream_item_type: Any | None = None
- if isinstance(response_model, DefaultPlaceholder):
- return_annotation = get_typed_return_annotation(endpoint)
- if lenient_issubclass(return_annotation, Response):
- response_model = None
- else:
- stream_item = get_stream_item_type(return_annotation)
- if stream_item is not None:
- # Extract item type for JSONL or SSE streaming when
- # response_class is DefaultPlaceholder (JSONL) or
- # EventSourceResponse (SSE).
- # ServerSentEvent is excluded: it's a transport
- # wrapper, not a data model, so it shouldn't feed
- # into validation or OpenAPI schema generation.
- if (
- isinstance(response_class, DefaultPlaceholder)
- or lenient_issubclass(response_class, EventSourceResponse)
- ) and not lenient_issubclass(stream_item, ServerSentEvent):
- self.stream_item_type = stream_item
- response_model = None
- else:
- response_model = return_annotation
- self.response_model = response_model
- self.summary = summary
- self.response_description = response_description
- self.deprecated = deprecated
- self.operation_id = operation_id
- self.response_model_include = response_model_include
- self.response_model_exclude = response_model_exclude
- self.response_model_by_alias = response_model_by_alias
- self.response_model_exclude_unset = response_model_exclude_unset
- self.response_model_exclude_defaults = response_model_exclude_defaults
- self.response_model_exclude_none = response_model_exclude_none
- self.include_in_schema = include_in_schema
- self.response_class = response_class
- self.dependency_overrides_provider = dependency_overrides_provider
- self.callbacks = callbacks
- self.openapi_extra = openapi_extra
- self.generate_unique_id_function = generate_unique_id_function
- self.strict_content_type = strict_content_type
- self.tags = tags or []
- self.responses = responses or {}
- self.name = get_name(endpoint) if name is None else name
- self.path_regex, self.path_format, self.param_convertors = compile_path(path)
- if methods is None:
- methods = ["GET"]
- self.methods: set[str] = {method.upper() for method in methods}
- if isinstance(generate_unique_id_function, DefaultPlaceholder):
- current_generate_unique_id: Callable[[APIRoute], str] = (
- generate_unique_id_function.value
- )
- else:
- current_generate_unique_id = generate_unique_id_function
- self.unique_id = self.operation_id or current_generate_unique_id(self)
- # normalize enums e.g. http.HTTPStatus
- if isinstance(status_code, IntEnum):
- status_code = int(status_code)
- self.status_code = status_code
- if self.response_model:
- assert is_body_allowed_for_status_code(status_code), (
- f"Status code {status_code} must not have a response body"
- )
- response_name = "Response_" + self.unique_id
- self.response_field = create_model_field(
- name=response_name,
- type_=self.response_model,
- mode="serialization",
- )
- else:
- self.response_field = None # type: ignore # ty: ignore[unused-ignore-comment]
- if self.stream_item_type:
- stream_item_name = "StreamItem_" + self.unique_id
- self.stream_item_field: ModelField | None = create_model_field(
- name=stream_item_name,
- type_=self.stream_item_type,
- mode="serialization",
- )
- else:
- self.stream_item_field = None
- self.dependencies = list(dependencies or [])
- self.description = description or inspect.cleandoc(self.endpoint.__doc__ or "")
- # if a "form feed" character (page break) is found in the description text,
- # truncate description text to the content preceding the first "form feed"
- self.description = self.description.split("\f")[0].strip()
- response_fields = {}
- for additional_status_code, response in self.responses.items():
- assert isinstance(response, dict), "An additional response must be a dict"
- model = response.get("model")
- if model:
- assert is_body_allowed_for_status_code(additional_status_code), (
- f"Status code {additional_status_code} must not have a response body"
- )
- response_name = f"Response_{additional_status_code}_{self.unique_id}"
- response_field = create_model_field(
- name=response_name, type_=model, mode="serialization"
- )
- response_fields[additional_status_code] = response_field
- if response_fields:
- self.response_fields: dict[int | str, ModelField] = response_fields
- else:
- self.response_fields = {}
- assert callable(endpoint), "An endpoint must be a callable"
- self.dependant = get_dependant(
- path=self.path_format, call=self.endpoint, scope="function"
- )
- for depends in self.dependencies[::-1]:
- self.dependant.dependencies.insert(
- 0,
- get_parameterless_sub_dependant(depends=depends, path=self.path_format),
- )
- self._flat_dependant = get_flat_dependant(self.dependant)
- self._embed_body_fields = _should_embed_body_fields(
- self._flat_dependant.body_params
- )
- self.body_field = get_body_field(
- flat_dependant=self._flat_dependant,
- name=self.unique_id,
- embed_body_fields=self._embed_body_fields,
- )
- # Detect generator endpoints that should stream as JSONL or SSE
- is_generator = (
- self.dependant.is_async_gen_callable or self.dependant.is_gen_callable
- )
- self.is_sse_stream = is_generator and lenient_issubclass(
- response_class, EventSourceResponse
- )
- self.is_json_stream = is_generator and isinstance(
- response_class, DefaultPlaceholder
- )
- self.app = request_response(self.get_route_handler())
- def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]:
- return get_request_handler(
- dependant=self.dependant,
- body_field=self.body_field,
- status_code=self.status_code,
- response_class=self.response_class,
- response_field=self.response_field,
- response_model_include=self.response_model_include,
- response_model_exclude=self.response_model_exclude,
- response_model_by_alias=self.response_model_by_alias,
- response_model_exclude_unset=self.response_model_exclude_unset,
- response_model_exclude_defaults=self.response_model_exclude_defaults,
- response_model_exclude_none=self.response_model_exclude_none,
- dependency_overrides_provider=self.dependency_overrides_provider,
- embed_body_fields=self._embed_body_fields,
- strict_content_type=self.strict_content_type,
- stream_item_field=self.stream_item_field,
- is_json_stream=self.is_json_stream,
- )
- def matches(self, scope: Scope) -> tuple[Match, Scope]:
- match, child_scope = super().matches(scope)
- if match != Match.NONE:
- child_scope["route"] = self
- return match, child_scope
- class APIRouter(routing.Router):
- """
- `APIRouter` class, used to group *path operations*, for example to structure
- an app in multiple files. It would then be included in the `FastAPI` app, or
- in another `APIRouter` (ultimately included in the app).
- Read more about it in the
- [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/).
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- app = FastAPI()
- router = APIRouter()
- @router.get("/users/", tags=["users"])
- async def read_users():
- return [{"username": "Rick"}, {"username": "Morty"}]
- app.include_router(router)
- ```
- """
- def __init__(
- self,
- *,
- prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "",
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to all the *path operations* in this
- router.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to all the
- *path operations* in this router.
- Read more about it in the
- [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
- """
- ),
- ] = None,
- default_response_class: Annotated[
- type[Response],
- Doc(
- """
- The default response class to be used.
- Read more in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).
- """
- ),
- ] = Default(JSONResponse),
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses to be shown in OpenAPI.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/).
- And in the
- [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- OpenAPI callbacks that should apply to all *path operations* in this
- router.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- routes: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- **Note**: you probably shouldn't use this parameter, it is inherited
- from Starlette and supported for compatibility.
- ---
- A list of routes to serve incoming HTTP and WebSocket requests.
- """
- ),
- deprecated(
- """
- You normally wouldn't use this parameter with FastAPI, it is inherited
- from Starlette and supported for compatibility.
- In FastAPI, you normally would use the *path operation methods*,
- like `router.get()`, `router.post()`, etc.
- """
- ),
- ] = None,
- redirect_slashes: Annotated[
- bool,
- Doc(
- """
- Whether to detect and redirect slashes in URLs when the client doesn't
- use the same format.
- """
- ),
- ] = True,
- default: Annotated[
- ASGIApp | None,
- Doc(
- """
- Default function handler for this router. Used to handle
- 404 Not Found errors.
- """
- ),
- ] = None,
- dependency_overrides_provider: Annotated[
- Any | None,
- Doc(
- """
- Only used internally by FastAPI to handle dependency overrides.
- You shouldn't need to use it. It normally points to the `FastAPI` app
- object.
- """
- ),
- ] = None,
- route_class: Annotated[
- type[APIRoute],
- Doc(
- """
- Custom route (*path operation*) class to be used by this router.
- Read more about it in the
- [FastAPI docs for Custom Request and APIRoute class](https://fastapi.tiangolo.com/how-to/custom-request-and-route/#custom-apiroute-class-in-a-router).
- """
- ),
- ] = APIRoute,
- on_startup: Annotated[
- Sequence[Callable[[], Any]] | None,
- Doc(
- """
- A list of startup event handler functions.
- You should instead use the `lifespan` handlers.
- Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
- """
- ),
- ] = None,
- on_shutdown: Annotated[
- Sequence[Callable[[], Any]] | None,
- Doc(
- """
- A list of shutdown event handler functions.
- You should instead use the `lifespan` handlers.
- Read more in the
- [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
- """
- ),
- ] = None,
- # the generic to Lifespan[AppType] is the type of the top level application
- # which the router cannot know statically, so we use typing.Any
- lifespan: Annotated[
- Lifespan[Any] | None,
- Doc(
- """
- A `Lifespan` context manager handler. This replaces `startup` and
- `shutdown` functions with a single context manager.
- Read more in the
- [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark all *path operations* in this router as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- To include (or not) all the *path operations* in this router in the
- generated OpenAPI.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- strict_content_type: Annotated[
- bool,
- Doc(
- """
- Enable strict checking for request Content-Type headers.
- When `True` (the default), requests with a body that do not include
- a `Content-Type` header will **not** be parsed as JSON.
- This prevents potential cross-site request forgery (CSRF) attacks
- that exploit the browser's ability to send requests without a
- Content-Type header, bypassing CORS preflight checks. In particular
- applicable for apps that need to be run locally (in localhost).
- When `False`, requests without a `Content-Type` header will have
- their body parsed as JSON, which maintains compatibility with
- certain clients that don't send `Content-Type` headers.
- Read more about it in the
- [FastAPI docs for Strict Content-Type](https://fastapi.tiangolo.com/advanced/strict-content-type/).
- """
- ),
- ] = Default(True),
- ) -> None:
- # Determine the lifespan context to use
- if lifespan is None:
- # Use the default lifespan that runs on_startup/on_shutdown handlers
- lifespan_context: Lifespan[Any] = _DefaultLifespan(self)
- elif inspect.isasyncgenfunction(lifespan):
- lifespan_context = asynccontextmanager(lifespan)
- elif inspect.isgeneratorfunction(lifespan):
- lifespan_context = _wrap_gen_lifespan_context(lifespan)
- else:
- lifespan_context = lifespan
- self.lifespan_context = lifespan_context
- super().__init__(
- routes=routes,
- redirect_slashes=redirect_slashes,
- default=default,
- lifespan=lifespan_context,
- )
- if prefix:
- assert prefix.startswith("/"), "A path prefix must start with '/'"
- assert not prefix.endswith("/"), (
- "A path prefix must not end with '/', as the routes will start with '/'"
- )
- # Handle on_startup/on_shutdown locally since Starlette removed support
- # Ref: https://github.com/Kludex/starlette/pull/3117
- # TODO: deprecate this once the lifespan (or alternative) interface is improved
- self.on_startup: list[Callable[[], Any]] = (
- [] if on_startup is None else list(on_startup)
- )
- self.on_shutdown: list[Callable[[], Any]] = (
- [] if on_shutdown is None else list(on_shutdown)
- )
- self.prefix = prefix
- self.tags: list[str | Enum] = tags or []
- self.dependencies = list(dependencies or [])
- self.deprecated = deprecated
- self.include_in_schema = include_in_schema
- self.responses = responses or {}
- self.callbacks = callbacks or []
- self.dependency_overrides_provider = dependency_overrides_provider
- self.route_class = route_class
- self.default_response_class = default_response_class
- self.generate_unique_id_function = generate_unique_id_function
- self.strict_content_type = strict_content_type
- def route(
- self,
- path: str,
- methods: Collection[str] | None = None,
- name: str | None = None,
- include_in_schema: bool = True,
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- def decorator(func: DecoratedCallable) -> DecoratedCallable:
- self.add_route(
- path,
- func,
- methods=methods,
- name=name,
- include_in_schema=include_in_schema,
- )
- return func
- return decorator
- def add_api_route(
- self,
- path: str,
- endpoint: Callable[..., Any],
- *,
- response_model: Any = Default(None),
- status_code: int | None = None,
- tags: list[str | Enum] | None = None,
- dependencies: Sequence[params.Depends] | None = None,
- summary: str | None = None,
- description: str | None = None,
- response_description: str = "Successful Response",
- responses: dict[int | str, dict[str, Any]] | None = None,
- deprecated: bool | None = None,
- methods: set[str] | list[str] | None = None,
- operation_id: str | None = None,
- response_model_include: IncEx | None = None,
- response_model_exclude: IncEx | None = None,
- response_model_by_alias: bool = True,
- response_model_exclude_unset: bool = False,
- response_model_exclude_defaults: bool = False,
- response_model_exclude_none: bool = False,
- include_in_schema: bool = True,
- response_class: type[Response] | DefaultPlaceholder = Default(JSONResponse),
- name: str | None = None,
- route_class_override: type[APIRoute] | None = None,
- callbacks: list[BaseRoute] | None = None,
- openapi_extra: dict[str, Any] | None = None,
- generate_unique_id_function: Callable[[APIRoute], str]
- | DefaultPlaceholder = Default(generate_unique_id),
- strict_content_type: bool | DefaultPlaceholder = Default(True),
- ) -> None:
- route_class = route_class_override or self.route_class
- responses = responses or {}
- combined_responses = {**self.responses, **responses}
- current_response_class = get_value_or_default(
- response_class, self.default_response_class
- )
- current_tags = self.tags.copy()
- if tags:
- current_tags.extend(tags)
- current_dependencies = self.dependencies.copy()
- if dependencies:
- current_dependencies.extend(dependencies)
- current_callbacks = self.callbacks.copy()
- if callbacks:
- current_callbacks.extend(callbacks)
- current_generate_unique_id = get_value_or_default(
- generate_unique_id_function, self.generate_unique_id_function
- )
- route = route_class(
- self.prefix + path,
- endpoint=endpoint,
- response_model=response_model,
- status_code=status_code,
- tags=current_tags,
- dependencies=current_dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=combined_responses,
- deprecated=deprecated or self.deprecated,
- methods=methods,
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema and self.include_in_schema,
- response_class=current_response_class,
- name=name,
- dependency_overrides_provider=self.dependency_overrides_provider,
- callbacks=current_callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=current_generate_unique_id,
- strict_content_type=get_value_or_default(
- strict_content_type, self.strict_content_type
- ),
- )
- self.routes.append(route)
- def api_route(
- self,
- path: str,
- *,
- response_model: Any = Default(None),
- status_code: int | None = None,
- tags: list[str | Enum] | None = None,
- dependencies: Sequence[params.Depends] | None = None,
- summary: str | None = None,
- description: str | None = None,
- response_description: str = "Successful Response",
- responses: dict[int | str, dict[str, Any]] | None = None,
- deprecated: bool | None = None,
- methods: list[str] | None = None,
- operation_id: str | None = None,
- response_model_include: IncEx | None = None,
- response_model_exclude: IncEx | None = None,
- response_model_by_alias: bool = True,
- response_model_exclude_unset: bool = False,
- response_model_exclude_defaults: bool = False,
- response_model_exclude_none: bool = False,
- include_in_schema: bool = True,
- response_class: type[Response] = Default(JSONResponse),
- name: str | None = None,
- callbacks: list[BaseRoute] | None = None,
- openapi_extra: dict[str, Any] | None = None,
- generate_unique_id_function: Callable[[APIRoute], str] = Default(
- generate_unique_id
- ),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- def decorator(func: DecoratedCallable) -> DecoratedCallable:
- self.add_api_route(
- path,
- func,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=methods,
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- return func
- return decorator
- def add_api_websocket_route(
- self,
- path: str,
- endpoint: Callable[..., Any],
- name: str | None = None,
- *,
- dependencies: Sequence[params.Depends] | None = None,
- ) -> None:
- current_dependencies = self.dependencies.copy()
- if dependencies:
- current_dependencies.extend(dependencies)
- route = APIWebSocketRoute(
- self.prefix + path,
- endpoint=endpoint,
- name=name,
- dependencies=current_dependencies,
- dependency_overrides_provider=self.dependency_overrides_provider,
- )
- self.routes.append(route)
- def websocket(
- self,
- path: Annotated[
- str,
- Doc(
- """
- WebSocket path.
- """
- ),
- ],
- name: Annotated[
- str | None,
- Doc(
- """
- A name for the WebSocket. Only used internally.
- """
- ),
- ] = None,
- *,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be used for this
- WebSocket.
- Read more about it in the
- [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).
- """
- ),
- ] = None,
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Decorate a WebSocket function.
- Read more about it in the
- [FastAPI docs for WebSockets](https://fastapi.tiangolo.com/advanced/websockets/).
- **Example**
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI, WebSocket
- app = FastAPI()
- router = APIRouter()
- @router.websocket("/ws")
- async def websocket_endpoint(websocket: WebSocket):
- await websocket.accept()
- while True:
- data = await websocket.receive_text()
- await websocket.send_text(f"Message text was: {data}")
- app.include_router(router)
- ```
- """
- def decorator(func: DecoratedCallable) -> DecoratedCallable:
- self.add_api_websocket_route(
- path, func, name=name, dependencies=dependencies
- )
- return func
- return decorator
- def websocket_route(
- self, path: str, name: str | None = None
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- def decorator(func: DecoratedCallable) -> DecoratedCallable:
- self.add_websocket_route(path, func, name=name)
- return func
- return decorator
- def include_router(
- self,
- router: Annotated["APIRouter", Doc("The `APIRouter` to include.")],
- *,
- prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "",
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to all the *path operations* in this
- router.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to all the
- *path operations* in this router.
- Read more about it in the
- [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
- """
- ),
- ] = None,
- default_response_class: Annotated[
- type[Response],
- Doc(
- """
- The default response class to be used.
- Read more in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class).
- """
- ),
- ] = Default(JSONResponse),
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses to be shown in OpenAPI.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/).
- And in the
- [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies).
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- OpenAPI callbacks that should apply to all *path operations* in this
- router.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark all *path operations* in this router as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include (or not) all the *path operations* in this router in the
- generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = True,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> None:
- """
- Include another `APIRouter` in the same current `APIRouter`.
- Read more about it in the
- [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/).
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- app = FastAPI()
- internal_router = APIRouter()
- users_router = APIRouter()
- @users_router.get("/users/")
- def read_users():
- return [{"name": "Rick"}, {"name": "Morty"}]
- internal_router.include_router(users_router)
- app.include_router(internal_router)
- ```
- """
- assert self is not router, (
- "Cannot include the same APIRouter instance into itself. "
- "Did you mean to include a different router?"
- )
- if prefix:
- assert prefix.startswith("/"), "A path prefix must start with '/'"
- assert not prefix.endswith("/"), (
- "A path prefix must not end with '/', as the routes will start with '/'"
- )
- else:
- for r in router.routes:
- path = getattr(r, "path") # noqa: B009
- name = getattr(r, "name", "unknown")
- if path is not None and not path:
- raise FastAPIError(
- f"Prefix and path cannot be both empty (path operation: {name})"
- )
- if responses is None:
- responses = {}
- for route in router.routes:
- if isinstance(route, APIRoute):
- combined_responses = {**responses, **route.responses}
- use_response_class = get_value_or_default(
- route.response_class,
- router.default_response_class,
- default_response_class,
- self.default_response_class,
- )
- current_tags = []
- if tags:
- current_tags.extend(tags)
- if route.tags:
- current_tags.extend(route.tags)
- current_dependencies: list[params.Depends] = []
- if dependencies:
- current_dependencies.extend(dependencies)
- if route.dependencies:
- current_dependencies.extend(route.dependencies)
- current_callbacks = []
- if callbacks:
- current_callbacks.extend(callbacks)
- if route.callbacks:
- current_callbacks.extend(route.callbacks)
- current_generate_unique_id = get_value_or_default(
- route.generate_unique_id_function,
- router.generate_unique_id_function,
- generate_unique_id_function,
- self.generate_unique_id_function,
- )
- self.add_api_route(
- prefix + route.path,
- route.endpoint,
- response_model=route.response_model,
- status_code=route.status_code,
- tags=current_tags,
- dependencies=current_dependencies,
- summary=route.summary,
- description=route.description,
- response_description=route.response_description,
- responses=combined_responses,
- deprecated=route.deprecated or deprecated or self.deprecated,
- methods=route.methods,
- operation_id=route.operation_id,
- response_model_include=route.response_model_include,
- response_model_exclude=route.response_model_exclude,
- response_model_by_alias=route.response_model_by_alias,
- response_model_exclude_unset=route.response_model_exclude_unset,
- response_model_exclude_defaults=route.response_model_exclude_defaults,
- response_model_exclude_none=route.response_model_exclude_none,
- include_in_schema=route.include_in_schema
- and self.include_in_schema
- and include_in_schema,
- response_class=use_response_class,
- name=route.name,
- route_class_override=type(route),
- callbacks=current_callbacks,
- openapi_extra=route.openapi_extra,
- generate_unique_id_function=current_generate_unique_id,
- strict_content_type=get_value_or_default(
- route.strict_content_type,
- router.strict_content_type,
- self.strict_content_type,
- ),
- )
- elif isinstance(route, routing.Route):
- methods = list(route.methods or [])
- self.add_route(
- prefix + route.path,
- route.endpoint,
- methods=methods,
- include_in_schema=route.include_in_schema,
- name=route.name,
- )
- elif isinstance(route, APIWebSocketRoute):
- current_dependencies = []
- if dependencies:
- current_dependencies.extend(dependencies)
- if route.dependencies:
- current_dependencies.extend(route.dependencies)
- self.add_api_websocket_route(
- prefix + route.path,
- route.endpoint,
- dependencies=current_dependencies,
- name=route.name,
- )
- elif isinstance(route, routing.WebSocketRoute):
- self.add_websocket_route(
- prefix + route.path, route.endpoint, name=route.name
- )
- for handler in router.on_startup:
- self.add_event_handler("startup", handler)
- for handler in router.on_shutdown:
- self.add_event_handler("shutdown", handler)
- self.lifespan_context = _merge_lifespan_context(
- self.lifespan_context,
- router.lifespan_context,
- )
- def get(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP GET operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- app = FastAPI()
- router = APIRouter()
- @router.get("/items/")
- def read_items():
- return [{"name": "Empanada"}, {"name": "Arepa"}]
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["GET"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- def put(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP PUT operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- from pydantic import BaseModel
- class Item(BaseModel):
- name: str
- description: str | None = None
- app = FastAPI()
- router = APIRouter()
- @router.put("/items/{item_id}")
- def replace_item(item_id: str, item: Item):
- return {"message": "Item replaced", "id": item_id}
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["PUT"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- def post(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP POST operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- from pydantic import BaseModel
- class Item(BaseModel):
- name: str
- description: str | None = None
- app = FastAPI()
- router = APIRouter()
- @router.post("/items/")
- def create_item(item: Item):
- return {"message": "Item created"}
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["POST"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- def delete(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP DELETE operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- app = FastAPI()
- router = APIRouter()
- @router.delete("/items/{item_id}")
- def delete_item(item_id: str):
- return {"message": "Item deleted"}
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["DELETE"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- def options(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP OPTIONS operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- app = FastAPI()
- router = APIRouter()
- @router.options("/items/")
- def get_item_options():
- return {"additions": ["Aji", "Guacamole"]}
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["OPTIONS"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- def head(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP HEAD operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- from pydantic import BaseModel
- class Item(BaseModel):
- name: str
- description: str | None = None
- app = FastAPI()
- router = APIRouter()
- @router.head("/items/", status_code=204)
- def get_items_headers(response: Response):
- response.headers["X-Cat-Dog"] = "Alone in the world"
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["HEAD"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- def patch(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP PATCH operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- from pydantic import BaseModel
- class Item(BaseModel):
- name: str
- description: str | None = None
- app = FastAPI()
- router = APIRouter()
- @router.patch("/items/")
- def update_item(item: Item):
- return {"message": "Item updated in place"}
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["PATCH"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- def trace(
- self,
- path: Annotated[
- str,
- Doc(
- """
- The URL path to be used for this *path operation*.
- For example, in `http://example.com/items`, the path is `/items`.
- """
- ),
- ],
- *,
- response_model: Annotated[
- Any,
- Doc(
- """
- The type to use for the response.
- It could be any valid Pydantic *field* type. So, it doesn't have to
- be a Pydantic model, it could be other things, like a `list`, `dict`,
- etc.
- It will be used for:
- * Documentation: the generated OpenAPI (and the UI at `/docs`) will
- show it as the response (JSON Schema).
- * Serialization: you could return an arbitrary object and the
- `response_model` would be used to serialize that object into the
- corresponding JSON.
- * Filtering: the JSON sent to the client will only contain the data
- (fields) defined in the `response_model`. If you returned an object
- that contains an attribute `password` but the `response_model` does
- not include that field, the JSON sent to the client would not have
- that `password`.
- * Validation: whatever you return will be serialized with the
- `response_model`, converting any data as necessary to generate the
- corresponding JSON. But if the data in the object returned is not
- valid, that would mean a violation of the contract with the client,
- so it's an error from the API developer. So, FastAPI will raise an
- error and return a 500 error code (Internal Server Error).
- Read more about it in the
- [FastAPI docs for Response Model](https://fastapi.tiangolo.com/tutorial/response-model/).
- """
- ),
- ] = Default(None),
- status_code: Annotated[
- int | None,
- Doc(
- """
- The default status code to be used for the response.
- You could override the status code by returning a response directly.
- Read more about it in the
- [FastAPI docs for Response Status Code](https://fastapi.tiangolo.com/tutorial/response-status-code/).
- """
- ),
- ] = None,
- tags: Annotated[
- list[str | Enum] | None,
- Doc(
- """
- A list of tags to be applied to the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/#tags).
- """
- ),
- ] = None,
- dependencies: Annotated[
- Sequence[params.Depends] | None,
- Doc(
- """
- A list of dependencies (using `Depends()`) to be applied to the
- *path operation*.
- Read more about it in the
- [FastAPI docs for Dependencies in path operation decorators](https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-in-path-operation-decorators/).
- """
- ),
- ] = None,
- summary: Annotated[
- str | None,
- Doc(
- """
- A summary for the *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- description: Annotated[
- str | None,
- Doc(
- """
- A description for the *path operation*.
- If not provided, it will be extracted automatically from the docstring
- of the *path operation function*.
- It can contain Markdown.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/).
- """
- ),
- ] = None,
- response_description: Annotated[
- str,
- Doc(
- """
- The description for the default response.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = "Successful Response",
- responses: Annotated[
- dict[int | str, dict[str, Any]] | None,
- Doc(
- """
- Additional responses that could be returned by this *path operation*.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- deprecated: Annotated[
- bool | None,
- Doc(
- """
- Mark this *path operation* as deprecated.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- """
- ),
- ] = None,
- operation_id: Annotated[
- str | None,
- Doc(
- """
- Custom operation ID to be used by this *path operation*.
- By default, it is generated automatically.
- If you provide a custom operation ID, you need to make sure it is
- unique for the whole API.
- You can customize the
- operation ID generation with the parameter
- `generate_unique_id_function` in the `FastAPI` class.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = None,
- response_model_include: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to include only certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_exclude: Annotated[
- IncEx | None,
- Doc(
- """
- Configuration passed to Pydantic to exclude certain fields in the
- response data.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = None,
- response_model_by_alias: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response model
- should be serialized by alias when an alias is used.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_include-and-response_model_exclude).
- """
- ),
- ] = True,
- response_model_exclude_unset: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that were not set and
- have their default values. This is different from
- `response_model_exclude_defaults` in that if the fields are set,
- they will be included in the response, even if the value is the same
- as the default.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_defaults: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data
- should have all the fields, including the ones that have the same value
- as the default. This is different from `response_model_exclude_unset`
- in that if the fields are set but contain the same default values,
- they will be excluded from the response.
- When `True`, default values are omitted from the response.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#use-the-response_model_exclude_unset-parameter).
- """
- ),
- ] = False,
- response_model_exclude_none: Annotated[
- bool,
- Doc(
- """
- Configuration passed to Pydantic to define if the response data should
- exclude fields set to `None`.
- This is much simpler (less smart) than `response_model_exclude_unset`
- and `response_model_exclude_defaults`. You probably want to use one of
- those two instead of this one, as those allow returning `None` values
- when it makes sense.
- Read more about it in the
- [FastAPI docs for Response Model - Return Type](https://fastapi.tiangolo.com/tutorial/response-model/#response_model_exclude_none).
- """
- ),
- ] = False,
- include_in_schema: Annotated[
- bool,
- Doc(
- """
- Include this *path operation* in the generated OpenAPI schema.
- This affects the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-parameters-from-openapi).
- """
- ),
- ] = True,
- response_class: Annotated[
- type[Response],
- Doc(
- """
- Response class to be used for this *path operation*.
- This will not be used if you return a response directly.
- Read more about it in the
- [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#redirectresponse).
- """
- ),
- ] = Default(JSONResponse),
- name: Annotated[
- str | None,
- Doc(
- """
- Name for this *path operation*. Only used internally.
- """
- ),
- ] = None,
- callbacks: Annotated[
- list[BaseRoute] | None,
- Doc(
- """
- List of *path operations* that will be used as OpenAPI callbacks.
- This is only for OpenAPI documentation, the callbacks won't be used
- directly.
- It will be added to the generated OpenAPI (e.g. visible at `/docs`).
- Read more about it in the
- [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/).
- """
- ),
- ] = None,
- openapi_extra: Annotated[
- dict[str, Any] | None,
- Doc(
- """
- Extra metadata to be included in the OpenAPI schema for this *path
- operation*.
- Read more about it in the
- [FastAPI docs for Path Operation Advanced Configuration](https://fastapi.tiangolo.com/advanced/path-operation-advanced-configuration/#custom-openapi-path-operation-schema).
- """
- ),
- ] = None,
- generate_unique_id_function: Annotated[
- Callable[[APIRoute], str],
- Doc(
- """
- Customize the function used to generate unique IDs for the *path
- operations* shown in the generated OpenAPI.
- This is particularly useful when automatically generating clients or
- SDKs for your API.
- Read more about it in the
- [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function).
- """
- ),
- ] = Default(generate_unique_id),
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add a *path operation* using an HTTP TRACE operation.
- ## Example
- ```python
- from fastapi import APIRouter, FastAPI
- from pydantic import BaseModel
- class Item(BaseModel):
- name: str
- description: str | None = None
- app = FastAPI()
- router = APIRouter()
- @router.trace("/items/{item_id}")
- def trace_item(item_id: str):
- return None
- app.include_router(router)
- ```
- """
- return self.api_route(
- path=path,
- response_model=response_model,
- status_code=status_code,
- tags=tags,
- dependencies=dependencies,
- summary=summary,
- description=description,
- response_description=response_description,
- responses=responses,
- deprecated=deprecated,
- methods=["TRACE"],
- operation_id=operation_id,
- response_model_include=response_model_include,
- response_model_exclude=response_model_exclude,
- response_model_by_alias=response_model_by_alias,
- response_model_exclude_unset=response_model_exclude_unset,
- response_model_exclude_defaults=response_model_exclude_defaults,
- response_model_exclude_none=response_model_exclude_none,
- include_in_schema=include_in_schema,
- response_class=response_class,
- name=name,
- callbacks=callbacks,
- openapi_extra=openapi_extra,
- generate_unique_id_function=generate_unique_id_function,
- )
- # TODO: remove this once the lifespan (or alternative) interface is improved
- async def _startup(self) -> None:
- """
- Run any `.on_startup` event handlers.
- This method is kept for backward compatibility after Starlette removed
- support for on_startup/on_shutdown handlers.
- Ref: https://github.com/Kludex/starlette/pull/3117
- """
- for handler in self.on_startup:
- if is_async_callable(handler):
- await handler()
- else:
- handler()
- # TODO: remove this once the lifespan (or alternative) interface is improved
- async def _shutdown(self) -> None:
- """
- Run any `.on_shutdown` event handlers.
- This method is kept for backward compatibility after Starlette removed
- support for on_startup/on_shutdown handlers.
- Ref: https://github.com/Kludex/starlette/pull/3117
- """
- for handler in self.on_shutdown:
- if is_async_callable(handler):
- await handler()
- else:
- handler()
- # TODO: remove this once the lifespan (or alternative) interface is improved
- def add_event_handler(
- self,
- event_type: str,
- func: Callable[[], Any],
- ) -> None:
- """
- Add an event handler function for startup or shutdown.
- This method is kept for backward compatibility after Starlette removed
- support for on_startup/on_shutdown handlers.
- Ref: https://github.com/Kludex/starlette/pull/3117
- """
- assert event_type in ("startup", "shutdown")
- if event_type == "startup":
- self.on_startup.append(func)
- else:
- self.on_shutdown.append(func)
- @deprecated(
- """
- on_event is deprecated, use lifespan event handlers instead.
- Read more about it in the
- [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/).
- """
- )
- def on_event(
- self,
- event_type: Annotated[
- str,
- Doc(
- """
- The type of event. `startup` or `shutdown`.
- """
- ),
- ],
- ) -> Callable[[DecoratedCallable], DecoratedCallable]:
- """
- Add an event handler for the router.
- `on_event` is deprecated, use `lifespan` event handlers instead.
- Read more about it in the
- [FastAPI docs for Lifespan Events](https://fastapi.tiangolo.com/advanced/events/#alternative-events-deprecated).
- """
- def decorator(func: DecoratedCallable) -> DecoratedCallable:
- self.add_event_handler(event_type, func)
- return func
- return decorator
|