Coverage for fastapi/routing.py: 100%

1import asyncio 5 ctx1abcde

2import dataclasses 5 ctx1abcde

3import email.message 5 ctx1abcde

4import inspect 5 ctx1abcde

5import json 5 ctx1abcde

6from contextlib import AsyncExitStack 5 ctx1abcde

7from enum import Enum, IntEnum 5 ctx1abcde

8from typing import ( 5 ctx1abcde

9 Any, 

10 Callable, 

11 Coroutine, 

12 Dict, 

13 List, 

14 Optional, 

15 Sequence, 

16 Set, 

17 Tuple, 

18 Type, 

19 Union, 

20) 

21 

22from fastapi import params 5 ctx1abcde

23from fastapi._compat import ( 5 ctx1abcde

24 ModelField, 

25 Undefined, 

26 _get_model_config, 

27 _model_dump, 

28 _normalize_errors, 

29 lenient_issubclass, 

30) 

31from fastapi.datastructures import Default, DefaultPlaceholder 5 ctx1abcde

32from fastapi.dependencies.models import Dependant 5 ctx1abcde

33from fastapi.dependencies.utils import ( 5 ctx1abcde

34 get_body_field, 

35 get_dependant, 

36 get_parameterless_sub_dependant, 

37 get_typed_return_annotation, 

38 solve_dependencies, 

39) 

40from fastapi.encoders import jsonable_encoder 5 ctx1abcde

41from fastapi.exceptions import ( 5 ctx1abcde

42 FastAPIError, 

43 RequestValidationError, 

44 ResponseValidationError, 

45 WebSocketRequestValidationError, 

46) 

47from fastapi.types import DecoratedCallable, IncEx 5 ctx1abcde

48from fastapi.utils import ( 5 ctx1abcde

49 create_cloned_field, 

50 create_response_field, 

51 generate_unique_id, 

52 get_value_or_default, 

53 is_body_allowed_for_status_code, 

54) 

55from pydantic import BaseModel 5 ctx1abcde

56from starlette import routing 5 ctx1abcde

57from starlette.concurrency import run_in_threadpool 5 ctx1abcde

58from starlette.exceptions import HTTPException 5 ctx1abcde

59from starlette.requests import Request 5 ctx1abcde

60from starlette.responses import JSONResponse, Response 5 ctx1abcde

61from starlette.routing import ( 5 ctx1abcde

62 BaseRoute, 

63 Match, 

64 compile_path, 

65 get_name, 

66 request_response, 

67 websocket_session, 

68) 

69from starlette.routing import Mount as Mount # noqa 5 ctx1abcde

70from starlette.types import ASGIApp, Lifespan, Scope 5 ctx1abcde

71from starlette.websockets import WebSocket 5 ctx1abcde

72from typing_extensions import Annotated, Doc, deprecated 5 ctx1abcde

73 

74 

75def _prepare_response_content( 5 ctx1abcde

76 res: Any, 

77 *, 

78 exclude_unset: bool, 

79 exclude_defaults: bool = False, 

80 exclude_none: bool = False, 

81) -> Any: 

82 if isinstance(res, BaseModel): 5 ctx1abcde

83 read_with_orm_mode = getattr(_get_model_config(res), "read_with_orm_mode", None) 5 ctx1abcde

84 if read_with_orm_mode: 5 ctx1abcde

85 # Let from_orm extract the data from this model instead of converting 

86 # it now to a dict. 

87 # Otherwise, there's no way to extract lazy data that requires attribute 

88 # access instead of dict iteration, e.g. lazy relationships. 

89 return res 5 ctx1abcde

90 return _model_dump( 5 ctx1abcde

91 res, 

92 by_alias=True, 

93 exclude_unset=exclude_unset, 

94 exclude_defaults=exclude_defaults, 

95 exclude_none=exclude_none, 

96 ) 

97 elif isinstance(res, list): 5 ctx1abcde

98 return [ 5 ctx1abcde

99 _prepare_response_content( 

100 item, 

101 exclude_unset=exclude_unset, 

102 exclude_defaults=exclude_defaults, 

103 exclude_none=exclude_none, 

104 ) 

105 for item in res 

106 ] 

107 elif isinstance(res, dict): 5 ctx1abcde

108 return { 5 ctx1abcde

109 k: _prepare_response_content( 

110 v, 

111 exclude_unset=exclude_unset, 

112 exclude_defaults=exclude_defaults, 

113 exclude_none=exclude_none, 

114 ) 

115 for k, v in res.items() 

116 } 

117 elif dataclasses.is_dataclass(res): 5 ctx1abcde

118 return dataclasses.asdict(res) 5 ctx1abcde

119 return res 5 ctx1abcde

120 

121 

122async def serialize_response( 5 ctx1abcde

123 *, 

124 field: Optional[ModelField] = None, 

125 response_content: Any, 

126 include: Optional[IncEx] = None, 

127 exclude: Optional[IncEx] = None, 

128 by_alias: bool = True, 

129 exclude_unset: bool = False, 

130 exclude_defaults: bool = False, 

131 exclude_none: bool = False, 

132 is_coroutine: bool = True, 

133) -> Any: 

134 if field: 5 ctx1abcde

135 errors = [] 5 ctx1abcde

136 if not hasattr(field, "serialize"): 5 ctx1abcde

137 # pydantic v1 

138 response_content = _prepare_response_content( 5 ctx1abcde

139 response_content, 

140 exclude_unset=exclude_unset, 

141 exclude_defaults=exclude_defaults, 

142 exclude_none=exclude_none, 

143 ) 

144 if is_coroutine: 5 ctx1abcde

145 value, errors_ = field.validate(response_content, {}, loc=("response",)) 5 ctx1abcde

146 else: 

147 value, errors_ = await run_in_threadpool( 5 ctx1abcde

148 field.validate, response_content, {}, loc=("response",) 

149 ) 

150 if isinstance(errors_, list): 5 ctx1abcde

151 errors.extend(errors_) 5 ctx1abcde

152 elif errors_: 5 ctx1abcde

153 errors.append(errors_) 5 ctx1abcde

154 if errors: 5 ctx1abcde

155 raise ResponseValidationError( 5 ctx1abcde

156 errors=_normalize_errors(errors), body=response_content 

157 ) 

158 

159 if hasattr(field, "serialize"): 5 ctx1abcde

160 return field.serialize( 5 ctx1abcde

161 value, 

162 include=include, 

163 exclude=exclude, 

164 by_alias=by_alias, 

165 exclude_unset=exclude_unset, 

166 exclude_defaults=exclude_defaults, 

167 exclude_none=exclude_none, 

168 ) 

169 

170 return jsonable_encoder( 5 ctx1abcde

171 value, 

172 include=include, 

173 exclude=exclude, 

174 by_alias=by_alias, 

175 exclude_unset=exclude_unset, 

176 exclude_defaults=exclude_defaults, 

177 exclude_none=exclude_none, 

178 ) 

179 else: 

180 return jsonable_encoder(response_content) 5 ctx1abcde

181 

182 

183async def run_endpoint_function( 5 ctx1abcde

184 *, dependant: Dependant, values: Dict[str, Any], is_coroutine: bool 

185) -> Any: 

186 # Only called by get_request_handler. Has been split into its own function to 

187 # facilitate profiling endpoints, since inner functions are harder to profile. 

188 assert dependant.call is not None, "dependant.call must be a function" 5 ctx1abcde

189 

190 if is_coroutine: 5 ctx1abcde

191 return await dependant.call(**values) 5 ctx1abcde

192 else: 

193 return await run_in_threadpool(dependant.call, **values) 5 ctx1abcde

194 

195 

196def get_request_handler( 5 ctx1abcde

197 dependant: Dependant, 

198 body_field: Optional[ModelField] = None, 

199 status_code: Optional[int] = None, 

200 response_class: Union[Type[Response], DefaultPlaceholder] = Default(JSONResponse), 

201 response_field: Optional[ModelField] = None, 

202 response_model_include: Optional[IncEx] = None, 

203 response_model_exclude: Optional[IncEx] = None, 

204 response_model_by_alias: bool = True, 

205 response_model_exclude_unset: bool = False, 

206 response_model_exclude_defaults: bool = False, 

207 response_model_exclude_none: bool = False, 

208 dependency_overrides_provider: Optional[Any] = None, 

209) -> Callable[[Request], Coroutine[Any, Any, Response]]: 

210 assert dependant.call is not None, "dependant.call must be a function" 5 ctx1abcde

211 is_coroutine = asyncio.iscoroutinefunction(dependant.call) 5 ctx1abcde

212 is_body_form = body_field and isinstance(body_field.field_info, params.Form) 5 ctx1abcde

213 if isinstance(response_class, DefaultPlaceholder): 5 ctx1abcde

214 actual_response_class: Type[Response] = response_class.value 5 ctx1abcde

215 else: 

216 actual_response_class = response_class 5 ctx1abcde

217 

218 async def app(request: Request) -> Response: 5 ctx1abcde

219 response: Union[Response, None] = None 5 ctx1abcde

220 async with AsyncExitStack() as file_stack: 5 ctx1abcde

221 try: 5 ctx1abcde

222 body: Any = None 5 ctx1abcde

223 if body_field: 5 ctx1abcde

224 if is_body_form: 5 ctx1abcde

225 body = await request.form() 5 ctx1abcde

226 file_stack.push_async_callback(body.close) 5 ctx1abcde

227 else: 

228 body_bytes = await request.body() 5 ctx1abcde

229 if body_bytes: 5 ctx1abcde

230 json_body: Any = Undefined 5 ctx1abcde

231 content_type_value = request.headers.get("content-type") 5 ctx1abcde

232 if not content_type_value: 5 ctx1abcde

233 json_body = await request.json() 5 ctx1abcde

234 else: 

235 message = email.message.Message() 5 ctx1abcde

236 message["content-type"] = content_type_value 5 ctx1abcde

237 if message.get_content_maintype() == "application": 5 ctx1abcde

238 subtype = message.get_content_subtype() 5 ctx1abcde

239 if subtype == "json" or subtype.endswith("+json"): 5 ctx1abcde

240 json_body = await request.json() 5 ctx1abcde

241 if json_body != Undefined: 5 ctx1abcde

242 body = json_body 5 ctx1abcde

243 else: 

244 body = body_bytes 5 ctx1abcde

245 except json.JSONDecodeError as e: 5 ctx1abcde

246 validation_error = RequestValidationError( 5 ctx1abcde

247 [ 

248 { 

249 "type": "json_invalid", 

250 "loc": ("body", e.pos), 

251 "msg": "JSON decode error", 

252 "input": {}, 

253 "ctx": {"error": e.msg}, 

254 } 

255 ], 

256 body=e.doc, 

257 ) 

258 raise validation_error from e 5 ctx1abcde

259 except HTTPException: 5 ctx1abcde

260 # If a middleware raises an HTTPException, it should be raised again 

261 raise 5 ctx1abcde

262 except Exception as e: 5 ctx1abcde

263 http_error = HTTPException( 5 ctx1abcde

264 status_code=400, detail="There was an error parsing the body" 

265 ) 

266 raise http_error from e 5 ctx1abcde

267 errors: List[Any] = [] 5 ctx1abcde

268 async with AsyncExitStack() as async_exit_stack: 5 ctx1abcde

269 solved_result = await solve_dependencies( 5 ctx1abcde

270 request=request, 

271 dependant=dependant, 

272 body=body, 

273 dependency_overrides_provider=dependency_overrides_provider, 

274 async_exit_stack=async_exit_stack, 

275 ) 

276 values, errors, background_tasks, sub_response, _ = solved_result 5 ctx1abcde

277 if not errors: 5 ctx1abcde

278 raw_response = await run_endpoint_function( 5 ctx1abcde

279 dependant=dependant, values=values, is_coroutine=is_coroutine 

280 ) 

281 if isinstance(raw_response, Response): 5 ctx1abcde

282 if raw_response.background is None: 5 ctx1abcde

283 raw_response.background = background_tasks 5 ctx1abcde

284 response = raw_response 5 ctx1abcde

285 else: 

286 response_args: Dict[str, Any] = {"background": background_tasks} 5 ctx1abcde

287 # If status_code was set, use it, otherwise use the default from the 

288 # response class, in the case of redirect it's 307 

289 current_status_code = ( 5 ctx1abcde

290 status_code if status_code else sub_response.status_code 

291 ) 

292 if current_status_code is not None: 5 ctx1abcde

293 response_args["status_code"] = current_status_code 5 ctx1abcde

294 if sub_response.status_code: 5 ctx1abcde

295 response_args["status_code"] = sub_response.status_code 5 ctx1abcde

296 content = await serialize_response( 5 ctx1abcde

297 field=response_field, 

298 response_content=raw_response, 

299 include=response_model_include, 

300 exclude=response_model_exclude, 

301 by_alias=response_model_by_alias, 

302 exclude_unset=response_model_exclude_unset, 

303 exclude_defaults=response_model_exclude_defaults, 

304 exclude_none=response_model_exclude_none, 

305 is_coroutine=is_coroutine, 

306 ) 

307 response = actual_response_class(content, **response_args) 5 ctx1abcde

308 if not is_body_allowed_for_status_code(response.status_code): 5 ctx1abcde

309 response.body = b"" 5 ctx1abcde

310 response.headers.raw.extend(sub_response.headers.raw) 5 ctx1abcde

311 if errors: 5 ctx1abcde

312 validation_error = RequestValidationError( 5 ctx1abcde

313 _normalize_errors(errors), body=body 

314 ) 

315 raise validation_error 5 ctx1abcde

316 if response is None: 5 ctx1abcde

317 raise FastAPIError( 5 ctx1abcde

318 "No response object was returned. There's a high chance that the " 

319 "application code is raising an exception and a dependency with yield " 

320 "has a block with a bare except, or a block with except Exception, " 

321 "and is not raising the exception again. Read more about it in the " 

322 "docs: https://fastapi.tiangolo.com/tutorial/dependencies/dependencies-with-yield/#dependencies-with-yield-and-except" 

323 ) 

324 return response 5 ctx1abcde

325 

326 return app 5 ctx1abcde

327 

328 

329def get_websocket_app( 5 ctx1abcde

330 dependant: Dependant, dependency_overrides_provider: Optional[Any] = None 

331) -> Callable[[WebSocket], Coroutine[Any, Any, Any]]: 

332 async def app(websocket: WebSocket) -> None: 5 ctx1abcde

333 async with AsyncExitStack() as async_exit_stack: 5 ctx1abcde

334 # TODO: remove this scope later, after a few releases 

335 # This scope fastapi_astack is no longer used by FastAPI, kept for 

336 # compatibility, just in case 

337 websocket.scope["fastapi_astack"] = async_exit_stack 5 ctx1abcde

338 solved_result = await solve_dependencies( 5 ctx1abcde

339 request=websocket, 

340 dependant=dependant, 

341 dependency_overrides_provider=dependency_overrides_provider, 

342 async_exit_stack=async_exit_stack, 

343 ) 

344 values, errors, _, _2, _3 = solved_result 5 ctx1abcde

345 if errors: 5 ctx1abcde

346 raise WebSocketRequestValidationError(_normalize_errors(errors)) 5 ctx1abcde

347 assert dependant.call is not None, "dependant.call must be a function" 5 ctx1abcde

348 await dependant.call(**values) 5 ctx1abcde

349 

350 return app 5 ctx1abcde

351 

352 

353class APIWebSocketRoute(routing.WebSocketRoute): 5 ctx1abcde

354 def __init__( 5 ctx1abcde

355 self, 

356 path: str, 

357 endpoint: Callable[..., Any], 

358 *, 

359 name: Optional[str] = None, 

360 dependencies: Optional[Sequence[params.Depends]] = None, 

361 dependency_overrides_provider: Optional[Any] = None, 

362 ) -> None: 

363 self.path = path 5 ctx1abcde

364 self.endpoint = endpoint 5 ctx1abcde

365 self.name = get_name(endpoint) if name is None else name 5 ctx1abcde

366 self.dependencies = list(dependencies or []) 5 ctx1abcde

367 self.path_regex, self.path_format, self.param_convertors = compile_path(path) 5 ctx1abcde

368 self.dependant = get_dependant(path=self.path_format, call=self.endpoint) 5 ctx1abcde

369 for depends in self.dependencies[::-1]: 5 ctx1abcde

370 self.dependant.dependencies.insert( 5 ctx1abcde

371 0, 

372 get_parameterless_sub_dependant(depends=depends, path=self.path_format), 

373 ) 

374 

375 self.app = websocket_session( 5 ctx1abcde

376 get_websocket_app( 

377 dependant=self.dependant, 

378 dependency_overrides_provider=dependency_overrides_provider, 

379 ) 

380 ) 

381 

382 def matches(self, scope: Scope) -> Tuple[Match, Scope]: 5 ctx1abcde

383 match, child_scope = super().matches(scope) 5 ctx1abcde

384 if match != Match.NONE: 5 ctx1abcde

385 child_scope["route"] = self 5 ctx1abcde

386 return match, child_scope 5 ctx1abcde

387 

388 

389class APIRoute(routing.Route): 5 ctx1abcde

390 def __init__( 5 ctx1abcde

391 self, 

392 path: str, 

393 endpoint: Callable[..., Any], 

394 *, 

395 response_model: Any = Default(None), 

396 status_code: Optional[int] = None, 

397 tags: Optional[List[Union[str, Enum]]] = None, 

398 dependencies: Optional[Sequence[params.Depends]] = None, 

399 summary: Optional[str] = None, 

400 description: Optional[str] = None, 

401 response_description: str = "Successful Response", 

402 responses: Optional[Dict[Union[int, str], Dict[str, Any]]] = None, 

403 deprecated: Optional[bool] = None, 

404 name: Optional[str] = None, 

405 methods: Optional[Union[Set[str], List[str]]] = None, 

406 operation_id: Optional[str] = None, 

407 response_model_include: Optional[IncEx] = None, 

408 response_model_exclude: Optional[IncEx] = None, 

409 response_model_by_alias: bool = True, 

410 response_model_exclude_unset: bool = False, 

411 response_model_exclude_defaults: bool = False, 

412 response_model_exclude_none: bool = False, 

413 include_in_schema: bool = True, 

414 response_class: Union[Type[Response], DefaultPlaceholder] = Default( 

415 JSONResponse 

416 ), 

417 dependency_overrides_provider: Optional[Any] = None, 

418 callbacks: Optional[List[BaseRoute]] = None, 

419 openapi_extra: Optional[Dict[str, Any]] = None, 

420 generate_unique_id_function: Union[ 

421 Callable[["APIRoute"], str], DefaultPlaceholder 

422 ] = Default(generate_unique_id), 

423 ) -> None: 

424 self.path = path 5 ctx1abcde

425 self.endpoint = endpoint 5 ctx1abcde

426 if isinstance(response_model, DefaultPlaceholder): 5 ctx1abcde

427 return_annotation = get_typed_return_annotation(endpoint) 5 ctx1abcde

428 if lenient_issubclass(return_annotation, Response): 5 ctx1abcde

429 response_model = None 5 ctx1abcde

430 else: 

431 response_model = return_annotation 5 ctx1abcde

432 self.response_model = response_model 5 ctx1abcde

433 self.summary = summary 5 ctx1abcde

434 self.response_description = response_description 5 ctx1abcde

435 self.deprecated = deprecated 5 ctx1abcde

436 self.operation_id = operation_id 5 ctx1abcde

437 self.response_model_include = response_model_include 5 ctx1abcde

438 self.response_model_exclude = response_model_exclude 5 ctx1abcde

439 self.response_model_by_alias = response_model_by_alias 5 ctx1abcde

440 self.response_model_exclude_unset = response_model_exclude_unset 5 ctx1abcde

441 self.response_model_exclude_defaults = response_model_exclude_defaults 5 ctx1abcde

442 self.response_model_exclude_none = response_model_exclude_none 5 ctx1abcde

443 self.include_in_schema = include_in_schema 5 ctx1abcde

444 self.response_class = response_class 5 ctx1abcde

445 self.dependency_overrides_provider = dependency_overrides_provider 5 ctx1abcde

446 self.callbacks = callbacks 5 ctx1abcde

447 self.openapi_extra = openapi_extra 5 ctx1abcde

448 self.generate_unique_id_function = generate_unique_id_function 5 ctx1abcde

449 self.tags = tags or [] 5 ctx1abcde

450 self.responses = responses or {} 5 ctx1abcde

451 self.name = get_name(endpoint) if name is None else name 5 ctx1abcde

452 self.path_regex, self.path_format, self.param_convertors = compile_path(path) 5 ctx1abcde

453 if methods is None: 5 ctx1abcde

454 methods = ["GET"] 5 ctx1abcde

455 self.methods: Set[str] = {method.upper() for method in methods} 5 ctx1abcde

456 if isinstance(generate_unique_id_function, DefaultPlaceholder): 5 ctx1abcde

457 current_generate_unique_id: Callable[ 5 ctx1abcde

458 ["APIRoute"], str 

459 ] = generate_unique_id_function.value 

460 else: 

461 current_generate_unique_id = generate_unique_id_function 5 ctx1abcde

462 self.unique_id = self.operation_id or current_generate_unique_id(self) 5 ctx1abcde

463 # normalize enums e.g. http.HTTPStatus 

464 if isinstance(status_code, IntEnum): 5 ctx1abcde

465 status_code = int(status_code) 5 ctx1abcde

466 self.status_code = status_code 5 ctx1abcde

467 if self.response_model: 5 ctx1abcde

468 assert is_body_allowed_for_status_code( 5 ctx1abcde

469 status_code 

470 ), f"Status code {status_code} must not have a response body" 

471 response_name = "Response_" + self.unique_id 5 ctx1abcde

472 self.response_field = create_response_field( 5 ctx1abcde

473 name=response_name, 

474 type_=self.response_model, 

475 mode="serialization", 

476 ) 

477 # Create a clone of the field, so that a Pydantic submodel is not returned 

478 # as is just because it's an instance of a subclass of a more limited class 

479 # e.g. UserInDB (containing hashed_password) could be a subclass of User 

480 # that doesn't have the hashed_password. But because it's a subclass, it 

481 # would pass the validation and be returned as is. 

482 # By being a new field, no inheritance will be passed as is. A new model 

483 # will always be created. 

484 # TODO: remove when deprecating Pydantic v1 

485 self.secure_cloned_response_field: Optional[ 5 ctx1abcde

486 ModelField 

487 ] = create_cloned_field(self.response_field) 

488 else: 

489 self.response_field = None # type: ignore 5 ctx1abcde

490 self.secure_cloned_response_field = None 5 ctx1abcde

491 self.dependencies = list(dependencies or []) 5 ctx1abcde

492 self.description = description or inspect.cleandoc(self.endpoint.__doc__ or "") 5 ctx1abcde

493 # if a "form feed" character (page break) is found in the description text, 

494 # truncate description text to the content preceding the first "form feed" 

495 self.description = self.description.split("\f")[0].strip() 5 ctx1abcde

496 response_fields = {} 5 ctx1abcde

497 for additional_status_code, response in self.responses.items(): 5 ctx1abcde

498 assert isinstance(response, dict), "An additional response must be a dict" 5 ctx1abcde

499 model = response.get("model") 5 ctx1abcde

500 if model: 5 ctx1abcde

501 assert is_body_allowed_for_status_code( 5 ctx1abcde

502 additional_status_code 

503 ), f"Status code {additional_status_code} must not have a response body" 

504 response_name = f"Response_{additional_status_code}_{self.unique_id}" 5 ctx1abcde

505 response_field = create_response_field(name=response_name, type_=model) 5 ctx1abcde

506 response_fields[additional_status_code] = response_field 5 ctx1abcde

507 if response_fields: 5 ctx1abcde

508 self.response_fields: Dict[Union[int, str], ModelField] = response_fields 5 ctx1abcde

509 else: 

510 self.response_fields = {} 5 ctx1abcde

511 

512 assert callable(endpoint), "An endpoint must be a callable" 5 ctx1abcde

513 self.dependant = get_dependant(path=self.path_format, call=self.endpoint) 5 ctx1abcde

514 for depends in self.dependencies[::-1]: 5 ctx1abcde

515 self.dependant.dependencies.insert( 5 ctx1abcde

516 0, 

517 get_parameterless_sub_dependant(depends=depends, path=self.path_format), 

518 ) 

519 self.body_field = get_body_field(dependant=self.dependant, name=self.unique_id) 5 ctx1abcde

520 self.app = request_response(self.get_route_handler()) 5 ctx1abcde

521 

522 def get_route_handler(self) -> Callable[[Request], Coroutine[Any, Any, Response]]: 5 ctx1abcde

523 return get_request_handler( 5 ctx1abcde

524 dependant=self.dependant, 

525 body_field=self.body_field, 

526 status_code=self.status_code, 

527 response_class=self.response_class, 

528 response_field=self.secure_cloned_response_field, 

529 response_model_include=self.response_model_include, 

530 response_model_exclude=self.response_model_exclude, 

531 response_model_by_alias=self.response_model_by_alias, 

532 response_model_exclude_unset=self.response_model_exclude_unset, 

533 response_model_exclude_defaults=self.response_model_exclude_defaults, 

534 response_model_exclude_none=self.response_model_exclude_none, 

535 dependency_overrides_provider=self.dependency_overrides_provider, 

536 ) 

537 

538 def matches(self, scope: Scope) -> Tuple[Match, Scope]: 5 ctx1abcde

539 match, child_scope = super().matches(scope) 5 ctx1abcde

540 if match != Match.NONE: 5 ctx1abcde

541 child_scope["route"] = self 5 ctx1abcde

542 return match, child_scope 5 ctx1abcde

543 

544 

545class APIRouter(routing.Router): 5 ctx1abcde

546 """ 

547 `APIRouter` class, used to group *path operations*, for example to structure 

548 an app in multiple files. It would then be included in the `FastAPI` app, or 

549 in another `APIRouter` (ultimately included in the app). 

550 

551 Read more about it in the 

552 [FastAPI docs for Bigger Applications - Multiple Files](https://fastapi.tiangolo.com/tutorial/bigger-applications/). 

553 

554 ## Example 

555 

556 ```python 

557 from fastapi import APIRouter, FastAPI 

558 

559 app = FastAPI() 

560 router = APIRouter() 

561 

562 

563 @router.get("/users/", tags=["users"]) 

564 async def read_users(): 

565 return [{"username": "Rick"}, {"username": "Morty"}] 

566 

567 

568 app.include_router(router) 

569 ``` 

570 """ 

571 

572 def __init__( 5 ctx1abcde

573 self, 

574 *, 

575 prefix: Annotated[str, Doc("An optional path prefix for the router.")] = "", 

576 tags: Annotated[ 

577 Optional[List[Union[str, Enum]]], 

578 Doc( 

579 """ 

580 A list of tags to be applied to all the *path operations* in this 

581 router. 

582 

583 It will be added to the generated OpenAPI (e.g. visible at `/docs`). 

584 

585 Read more about it in the 

586 [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). 

587 """ 

588 ), 

589 ] = None, 

590 dependencies: Annotated[ 

591 Optional[Sequence[params.Depends]], 

592 Doc( 

593 """ 

594 A list of dependencies (using `Depends()`) to be applied to all the 

595 *path operations* in this router. 

596 

597 Read more about it in the 

598 [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). 

599 """ 

600 ), 

601 ] = None, 

602 default_response_class: Annotated[ 

603 Type[Response], 

604 Doc( 

605 """ 

606 The default response class to be used. 

607 

608 Read more in the 

609 [FastAPI docs for Custom Response - HTML, Stream, File, others](https://fastapi.tiangolo.com/advanced/custom-response/#default-response-class). 

610 """ 

611 ), 

612 ] = Default(JSONResponse), 

613 responses: Annotated[ 

614 Optional[Dict[Union[int, str], Dict[str, Any]]], 

615 Doc( 

616 """ 

617 Additional responses to be shown in OpenAPI. 

618 

619 It will be added to the generated OpenAPI (e.g. visible at `/docs`). 

620 

621 Read more about it in the 

622 [FastAPI docs for Additional Responses in OpenAPI](https://fastapi.tiangolo.com/advanced/additional-responses/). 

623 

624 And in the 

625 [FastAPI docs for Bigger Applications](https://fastapi.tiangolo.com/tutorial/bigger-applications/#include-an-apirouter-with-a-custom-prefix-tags-responses-and-dependencies). 

626 """ 

627 ), 

628 ] = None, 

629 callbacks: Annotated[ 

630 Optional[List[BaseRoute]], 

631 Doc( 

632 """ 

633 OpenAPI callbacks that should apply to all *path operations* in this 

634 router. 

635 

636 It will be added to the generated OpenAPI (e.g. visible at `/docs`). 

637 

638 Read more about it in the 

639 [FastAPI docs for OpenAPI Callbacks](https://fastapi.tiangolo.com/advanced/openapi-callbacks/). 

640 """ 

641 ), 

642 ] = None, 

643 routes: Annotated[ 

644 Optional[List[BaseRoute]], 

645 Doc( 

646 """ 

647 **Note**: you probably shouldn't use this parameter, it is inherited 

648 from Starlette and supported for compatibility. 

649 

650 --- 

651 

652 A list of routes to serve incoming HTTP and WebSocket requests. 

653 """ 

654 ), 

655 deprecated( 

656 """ 

657 You normally wouldn't use this parameter with FastAPI, it is inherited 

658 from Starlette and supported for compatibility. 

659 

660 In FastAPI, you normally would use the *path operation methods*, 

661 like `router.get()`, `router.post()`, etc. 

662 """ 

663 ), 

664 ] = None, 

665 redirect_slashes: Annotated[ 

666 bool, 

667 Doc( 

668 """ 

669 Whether to detect and redirect slashes in URLs when the client doesn't 

670 use the same format. 

671 """ 

672 ), 

673 ] = True, 

674 default: Annotated[ 

675 Optional[ASGIApp], 

676 Doc( 

677 """ 

678 Default function handler for this router. Used to handle 

679 404 Not Found errors. 

680 """ 

681 ), 

682 ] = None, 

683 dependency_overrides_provider: Annotated[ 

684 Optional[Any], 

685 Doc( 

686 """ 

687 Only used internally by FastAPI to handle dependency overrides. 

688 

689 You shouldn't need to use it. It normally points to the `FastAPI` app 

690 object. 

691 """ 

692 ), 

693 ] = None, 

694 route_class: Annotated[ 

695 Type[APIRoute], 

696 Doc( 

697 """ 

698 Custom route (*path operation*) class to be used by this router. 

699 

700 Read more about it in the 

701 [FastAPI docs for Custom Request and APIRoute class](https://fastapi.tiangolo.com/how-to/custom-request-and-route/#custom-apiroute-class-in-a-router). 

702 """ 

703 ), 

704 ] = APIRoute, 

705 on_startup: Annotated[ 

706 Optional[Sequence[Callable[[], Any]]], 

707 Doc( 

708 """ 

709 A list of startup event handler functions. 

710 

711 You should instead use the `lifespan` handlers. 

712 

713 Read more in the [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). 

714 """ 

715 ), 

716 ] = None, 

717 on_shutdown: Annotated[ 

718 Optional[Sequence[Callable[[], Any]]], 

719 Doc( 

720 """ 

721 A list of shutdown event handler functions. 

722 

723 You should instead use the `lifespan` handlers. 

724 

725 Read more in the 

726 [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). 

727 """ 

728 ), 

729 ] = None, 

730 # the generic to Lifespan[AppType] is the type of the top level application 

731 # which the router cannot know statically, so we use typing.Any 

732 lifespan: Annotated[ 

733 Optional[Lifespan[Any]], 

734 Doc( 

735 """ 

736 A `Lifespan` context manager handler. This replaces `startup` and 

737 `shutdown` functions with a single context manager. 

738 

739 Read more in the 

740 [FastAPI docs for `lifespan`](https://fastapi.tiangolo.com/advanced/events/). 

741 """ 

742 ), 

743 ] = None, 

744 deprecated: Annotated[ 

745 Optional[bool], 

746 Doc( 

747 """ 

748 Mark all *path operations* in this router as deprecated. 

749 

750 It will be added to the generated OpenAPI (e.g. visible at `/docs`). 

751 

752 Read more about it in the 

753 [FastAPI docs for Path Operation Configuration](https://fastapi.tiangolo.com/tutorial/path-operation-configuration/). 

754 """ 

755 ), 

756 ] = None, 

757 include_in_schema: Annotated[ 

758 bool, 

759 Doc( 

760 """ 

761 To include (or not) all the *path operations* in this router in the 

762 generated OpenAPI. 

763 

764 This affects the generated OpenAPI (e.g. visible at `/docs`). 

765 

766 Read more about it in the 

767 [FastAPI docs for Query Parameters and String Validations](https://fastapi.tiangolo.com/tutorial/query-params-str-validations/#exclude-from-openapi). 

768 """ 

769 ), 

770 ] = True, 

771 generate_unique_id_function: Annotated[ 

772 Callable[[APIRoute], str], 

773 Doc( 

774 """ 

775 Customize the function used to generate unique IDs for the *path 

776 operations* shown in the generated OpenAPI. 

777 

778 This is particularly useful when automatically generating clients or 

779 SDKs for your API. 

780 

781 Read more about it in the 

782 [FastAPI docs about how to Generate Clients](https://fastapi.tiangolo.com/advanced/generate-clients/#custom-generate-unique-id-function). 

783 """ 

784 ), 

785 ] = Default(generate_unique_id), 

786 ) -> None: 

787 super().__init__( 5 ctx1abcde

788 routes=routes, 

789 redirect_slashes=redirect_slashes, 

790 default=default, 

791 on_startup=on_startup, 

792 on_shutdown=on_shutdown, 

793 lifespan=lifespan,