Coverage for typer / models.py: 100%

128 statements  

« prev     ^ index     » next       coverage.py v7.13.1, created at 2026-11-18 11:12 +0000

1import inspect 1abcdefghij

2import io 1abcdefghij

3from collections.abc import Callable, Sequence 1abcdefghij

4from typing import TYPE_CHECKING, Any, Optional, TypeVar 1abcdefghij

5 

6from . import _click 1abcdefghij

7from ._click.shell_completion import CompletionItem 1abcdefghij

8 

9if TYPE_CHECKING: # pragma: no cover 1abcdefghij

10 from .core import TyperCommand, TyperGroup 

11 from .main import Typer 

12 

13 

14NoneType = type(None) 1abcdefghij

15 

16AnyType = type[Any] 1abcdefghij

17 

18Required = ... 1abcdefghij

19 

20 

21class Context(_click.Context): 1abcdefghij

22 """ 

23 The [`Context`](https://click.palletsprojects.com/en/stable/api/#click.Context) has some additional data about the current execution of your program. 

24 When declaring it in a [callback](https://typer.tiangolo.com/tutorial/options/callback-and-context/) function, 

25 you can access this additional information. 

26 """ 

27 

28 pass 1abcdefghij

29 

30 

31class FileText(io.TextIOWrapper): 1abcdefghij

32 """ 1abcdefghij

33 Gives you a file-like object for reading text, and you will get a `str` data from it. 

34 The default mode of this class is `mode="r"`. 

35 

36 **Example** 

37 

38 ```python 

39 from typing import Annotated 

40 

41 import typer 

42 

43 app = typer.Typer() 

44 

45 @app.command() 

46 def main(config: Annotated[typer.FileText, typer.Option()]): 

47 for line in config: 

48 print(f"Config line: {line}") 

49 

50 if __name__ == "__main__": 

51 app() 

52 ``` 

53 """ 

54 

55 pass 1abcdefghij

56 

57 

58class FileTextWrite(FileText): 1abcdefghij

59 """ 1abcdefghij

60 You can use this class for writing text. Alternatively, you can use `FileText` with `mode="w"`. 

61 The default mode of this class is `mode="w"`. 

62 

63 **Example** 

64 

65 ```python 

66 from typing import Annotated 

67 

68 import typer 

69 

70 app = typer.Typer() 

71 

72 @app.command() 

73 def main(config: Annotated[typer.FileTextWrite, typer.Option()]): 

74 config.write("Some config written by the app") 

75 print("Config written") 

76 

77 if __name__ == "__main__": 

78 app() 

79 ``` 

80 """ 

81 

82 pass 1abcdefghij

83 

84 

85class FileBinaryRead(io.BufferedReader): 1abcdefghij

86 """ 1abcdefghij

87 You can use this class to read binary data, receiving `bytes`. 

88 The default mode of this class is `mode="rb"`. 

89 It is useful for reading binary files like images: 

90 

91 **Example** 

92 

93 ```python 

94 from typing import Annotated 

95 

96 import typer 

97 

98 app = typer.Typer() 

99 

100 @app.command() 

101 def main(file: Annotated[typer.FileBinaryRead, typer.Option()]): 

102 processed_total = 0 

103 for bytes_chunk in file: 

104 # Process the bytes in bytes_chunk 

105 processed_total += len(bytes_chunk) 

106 print(f"Processed bytes total: {processed_total}") 

107 

108 if __name__ == "__main__": 

109 app() 

110 ``` 

111 """ 

112 

113 pass 1abcdefghij

114 

115 

116class FileBinaryWrite(io.BufferedWriter): 1abcdefghij

117 """ 1abcdefghij

118 You can use this class to write binary data: you pass `bytes` to it instead of strings. 

119 The default mode of this class is `mode="wb"`. 

120 It is useful for writing binary files like images: 

121 

122 **Example** 

123 

124 ```python 

125 from typing import Annotated 

126 

127 import typer 

128 

129 app = typer.Typer() 

130 

131 @app.command() 

132 def main(file: Annotated[typer.FileBinaryWrite, typer.Option()]): 

133 first_line_str = "some settings\\n" 

134 # You cannot write str directly to a binary file; encode it first 

135 first_line_bytes = first_line_str.encode("utf-8") 

136 # Then you can write the bytes 

137 file.write(first_line_bytes) 

138 # This is already bytes, it starts with b" 

139 second_line = b"la cig\xc3\xbce\xc3\xb1a trae al ni\xc3\xb1o" 

140 file.write(second_line) 

141 print("Binary file written") 

142 

143 if __name__ == "__main__": 

144 app() 

145 ``` 

146 """ 

147 

148 pass 1abcdefghij

149 

150 

151class CallbackParam(_click.Parameter): 1abcdefghij

152 """ 

153 In a callback function, you can declare a function parameter with type `CallbackParam` 

154 to access the specific Click [`Parameter`](https://click.palletsprojects.com/en/stable/api/#click.Parameter) object. 

155 """ 

156 

157 pass 1abcdefghij

158 

159 

160class DefaultPlaceholder: 1abcdefghij

161 """ 

162 You shouldn't use this class directly. 

163 

164 It's used internally to recognize when a default value has been overwritten, even 

165 if the new value is `None`. 

166 """ 

167 

168 def __init__(self, value: Any): 1abcdefghij

169 self.value = value 1abcdefghij

170 

171 def __bool__(self) -> bool: 1abcdefghij

172 return bool(self.value) 1abcdefghij

173 

174 

175DefaultType = TypeVar("DefaultType") 1abcdefghij

176 

177CommandFunctionType = TypeVar("CommandFunctionType", bound=Callable[..., Any]) 1abcdefghij

178 

179 

180def Default(value: DefaultType) -> DefaultType: 1abcdefghij

181 """ 

182 You shouldn't use this function directly. 

183 

184 It's used internally to recognize when a default value has been overwritten, even 

185 if the new value is `None`. 

186 """ 

187 return DefaultPlaceholder(value) # type: ignore 1abcdefghij

188 

189 

190class CommandInfo: 1abcdefghij

191 def __init__( 1abcdefghij

192 self, 

193 name: str | None = None, 

194 *, 

195 cls: type["TyperCommand"] | None = None, 

196 context_settings: dict[Any, Any] | None = None, 

197 callback: Callable[..., Any] | None = None, 

198 help: str | None = None, 

199 epilog: str | None = None, 

200 short_help: str | None = None, 

201 options_metavar: str = "[OPTIONS]", 

202 add_help_option: bool = True, 

203 no_args_is_help: bool = False, 

204 hidden: bool = False, 

205 deprecated: bool = False, 

206 # Rich settings 

207 rich_help_panel: str | None = None, 

208 ): 

209 self.name = name 1abcdefghij

210 self.cls = cls 1abcdefghij

211 self.context_settings = context_settings 1abcdefghij

212 self.callback = callback 1abcdefghij

213 self.help = help 1abcdefghij

214 self.epilog = epilog 1abcdefghij

215 self.short_help = short_help 1abcdefghij

216 self.options_metavar = options_metavar 1abcdefghij

217 self.add_help_option = add_help_option 1abcdefghij

218 self.no_args_is_help = no_args_is_help 1abcdefghij

219 self.hidden = hidden 1abcdefghij

220 self.deprecated = deprecated 1abcdefghij

221 # Rich settings 

222 self.rich_help_panel = rich_help_panel 1abcdefghij

223 

224 

225class TyperInfo: 1abcdefghij

226 def __init__( 1abcdefghij

227 self, 

228 typer_instance: Optional["Typer"] = Default(None), 

229 *, 

230 name: str | None = Default(None), 

231 cls: type["TyperGroup"] | None = Default(None), 

232 invoke_without_command: bool = Default(False), 

233 no_args_is_help: bool = Default(False), 

234 subcommand_metavar: str | None = Default(None), 

235 chain: bool = Default(False), 

236 result_callback: Callable[..., Any] | None = Default(None), 

237 # Command 

238 context_settings: dict[Any, Any] | None = Default(None), 

239 callback: Callable[..., Any] | None = Default(None), 

240 help: str | None = Default(None), 

241 epilog: str | None = Default(None), 

242 short_help: str | None = Default(None), 

243 options_metavar: str = Default("[OPTIONS]"), 

244 add_help_option: bool = Default(True), 

245 hidden: bool = Default(False), 

246 deprecated: bool = Default(False), 

247 # Rich settings 

248 rich_help_panel: str | None = Default(None), 

249 ): 

250 self.typer_instance = typer_instance 1abcdefghij

251 self.name = name 1abcdefghij

252 self.cls = cls 1abcdefghij

253 self.invoke_without_command = invoke_without_command 1abcdefghij

254 self.no_args_is_help = no_args_is_help 1abcdefghij

255 self.subcommand_metavar = subcommand_metavar 1abcdefghij

256 self.chain = chain 1abcdefghij

257 self.result_callback = result_callback 1abcdefghij

258 self.context_settings = context_settings 1abcdefghij

259 self.callback = callback 1abcdefghij

260 self.help = help 1abcdefghij

261 self.epilog = epilog 1abcdefghij

262 self.short_help = short_help 1abcdefghij

263 self.options_metavar = options_metavar 1abcdefghij

264 self.add_help_option = add_help_option 1abcdefghij

265 self.hidden = hidden 1abcdefghij

266 self.deprecated = deprecated 1abcdefghij

267 self.rich_help_panel = rich_help_panel 1abcdefghij

268 

269 

270class ParameterInfo: 1abcdefghij

271 def __init__( 1abcdefghij

272 self, 

273 *, 

274 default: Any | None = None, 

275 param_decls: Sequence[str] | None = None, 

276 callback: Callable[..., Any] | None = None, 

277 metavar: str | None = None, 

278 expose_value: bool = True, 

279 is_eager: bool = False, 

280 envvar: str | list[str] | None = None, 

281 # Note that shell_complete is not fully supported and will be removed in future versions 

282 # TODO: Remove shell_complete in a future version (after 0.16.0) 

283 shell_complete: Callable[ 

284 [_click.Context, _click.Parameter, str], 

285 list["CompletionItem"] | list[str], 

286 ] 

287 | None = None, 

288 autocompletion: Callable[..., Any] | None = None, 

289 default_factory: Callable[[], Any] | None = None, 

290 # Custom type 

291 parser: Callable[[str], Any] | None = None, 

292 # TyperArgument 

293 show_default: bool | str = True, 

294 show_choices: bool = True, 

295 show_envvar: bool = True, 

296 help: str | None = None, 

297 hidden: bool = False, 

298 # Choice 

299 case_sensitive: bool = True, 

300 # Numbers 

301 min: int | float | None = None, 

302 max: int | float | None = None, 

303 clamp: bool = False, 

304 # DateTime 

305 formats: list[str] | None = None, 

306 # File 

307 mode: str | None = None, 

308 encoding: str | None = None, 

309 errors: str | None = "strict", 

310 lazy: bool | None = None, 

311 atomic: bool = False, 

312 # Path 

313 exists: bool = False, 

314 file_okay: bool = True, 

315 dir_okay: bool = True, 

316 writable: bool = False, 

317 readable: bool = True, 

318 resolve_path: bool = False, 

319 allow_dash: bool = False, 

320 path_type: None | type[str] | type[bytes] = None, 

321 # Rich settings 

322 rich_help_panel: str | None = None, 

323 ): 

324 self.default = default 1abcdefghij

325 self.param_decls = param_decls 1abcdefghij

326 self.callback = callback 1abcdefghij

327 self.metavar = metavar 1abcdefghij

328 self.expose_value = expose_value 1abcdefghij

329 self.is_eager = is_eager 1abcdefghij

330 self.envvar = envvar 1abcdefghij

331 self.shell_complete = shell_complete 1abcdefghij

332 self.autocompletion = autocompletion 1abcdefghij

333 self.default_factory = default_factory 1abcdefghij

334 # Custom type 

335 self.parser = parser 1abcdefghij

336 # TyperArgument 

337 self.show_default = show_default 1abcdefghij

338 self.show_choices = show_choices 1abcdefghij

339 self.show_envvar = show_envvar 1abcdefghij

340 self.help = help 1abcdefghij

341 self.hidden = hidden 1abcdefghij

342 # Choice 

343 self.case_sensitive = case_sensitive 1abcdefghij

344 # Numbers 

345 self.min = min 1abcdefghij

346 self.max = max 1abcdefghij

347 self.clamp = clamp 1abcdefghij

348 # DateTime 

349 self.formats = formats 1abcdefghij

350 # File 

351 self.mode = mode 1abcdefghij

352 self.encoding = encoding 1abcdefghij

353 self.errors = errors 1abcdefghij

354 self.lazy = lazy 1abcdefghij

355 self.atomic = atomic 1abcdefghij

356 # Path 

357 self.exists = exists 1abcdefghij

358 self.file_okay = file_okay 1abcdefghij

359 self.dir_okay = dir_okay 1abcdefghij

360 self.writable = writable 1abcdefghij

361 self.readable = readable 1abcdefghij

362 self.resolve_path = resolve_path 1abcdefghij

363 self.allow_dash = allow_dash 1abcdefghij

364 self.path_type = path_type 1abcdefghij

365 # Rich settings 

366 self.rich_help_panel = rich_help_panel 1abcdefghij

367 

368 

369class OptionInfo(ParameterInfo): 1abcdefghij

370 def __init__( 1abcdefghij

371 self, 

372 *, 

373 # ParameterInfo 

374 default: Any | None = None, 

375 param_decls: Sequence[str] | None = None, 

376 callback: Callable[..., Any] | None = None, 

377 metavar: str | None = None, 

378 expose_value: bool = True, 

379 is_eager: bool = False, 

380 envvar: str | list[str] | None = None, 

381 # Note that shell_complete is not fully supported and will be removed in future versions 

382 # TODO: Remove shell_complete in a future version (after 0.16.0) 

383 shell_complete: Callable[ 

384 [_click.Context, _click.Parameter, str], 

385 list["CompletionItem"] | list[str], 

386 ] 

387 | None = None, 

388 autocompletion: Callable[..., Any] | None = None, 

389 default_factory: Callable[[], Any] | None = None, 

390 # Custom type 

391 parser: Callable[[str], Any] | None = None, 

392 # Option 

393 show_default: bool | str = True, 

394 prompt: bool | str = False, 

395 confirmation_prompt: bool = False, 

396 prompt_required: bool = True, 

397 hide_input: bool = False, 

398 # TODO: remove is_flag and flag_value in a future release 

399 is_flag: bool | None = None, 

400 flag_value: Any | None = None, 

401 count: bool = False, 

402 allow_from_autoenv: bool = True, 

403 help: str | None = None, 

404 hidden: bool = False, 

405 show_choices: bool = True, 

406 show_envvar: bool = True, 

407 # Choice 

408 case_sensitive: bool = True, 

409 # Numbers 

410 min: int | float | None = None, 

411 max: int | float | None = None, 

412 clamp: bool = False, 

413 # DateTime 

414 formats: list[str] | None = None, 

415 # File 

416 mode: str | None = None, 

417 encoding: str | None = None, 

418 errors: str | None = "strict", 

419 lazy: bool | None = None, 

420 atomic: bool = False, 

421 # Path 

422 exists: bool = False, 

423 file_okay: bool = True, 

424 dir_okay: bool = True, 

425 writable: bool = False, 

426 readable: bool = True, 

427 resolve_path: bool = False, 

428 allow_dash: bool = False, 

429 path_type: None | type[str] | type[bytes] = None, 

430 # Rich settings 

431 rich_help_panel: str | None = None, 

432 ): 

433 super().__init__( 1abcdefghij

434 default=default, 

435 param_decls=param_decls, 

436 callback=callback, 

437 metavar=metavar, 

438 expose_value=expose_value, 

439 is_eager=is_eager, 

440 envvar=envvar, 

441 shell_complete=shell_complete, 

442 autocompletion=autocompletion, 

443 default_factory=default_factory, 

444 # Custom type 

445 parser=parser, 

446 # TyperArgument 

447 show_default=show_default, 

448 show_choices=show_choices, 

449 show_envvar=show_envvar, 

450 help=help, 

451 hidden=hidden, 

452 # Choice 

453 case_sensitive=case_sensitive, 

454 # Numbers 

455 min=min, 

456 max=max, 

457 clamp=clamp, 

458 # DateTime 

459 formats=formats, 

460 # File 

461 mode=mode, 

462 encoding=encoding, 

463 errors=errors, 

464 lazy=lazy, 

465 atomic=atomic, 

466 # Path 

467 exists=exists, 

468 file_okay=file_okay, 

469 dir_okay=dir_okay, 

470 writable=writable, 

471 readable=readable, 

472 resolve_path=resolve_path, 

473 allow_dash=allow_dash, 

474 path_type=path_type, 

475 # Rich settings 

476 rich_help_panel=rich_help_panel, 

477 ) 

478 if is_flag is not None or flag_value is not None: 1abcdefghij

479 import warnings 1abcdefghij

480 

481 warnings.warn( 1abcdefghij

482 "The 'is_flag' and 'flag_value' parameters are not supported by Typer " 

483 "and will be removed entirely in a future release.", 

484 DeprecationWarning, 

485 stacklevel=2, 

486 ) 

487 self.prompt = prompt 1abcdefghij

488 self.confirmation_prompt = confirmation_prompt 1abcdefghij

489 self.prompt_required = prompt_required 1abcdefghij

490 self.hide_input = hide_input 1abcdefghij

491 self.count = count 1abcdefghij

492 self.allow_from_autoenv = allow_from_autoenv 1abcdefghij

493 

494 

495class ArgumentInfo(ParameterInfo): 1abcdefghij

496 def __init__( 1abcdefghij

497 self, 

498 *, 

499 # ParameterInfo 

500 default: Any | None = None, 

501 param_decls: Sequence[str] | None = None, 

502 callback: Callable[..., Any] | None = None, 

503 metavar: str | None = None, 

504 expose_value: bool = True, 

505 is_eager: bool = False, 

506 envvar: str | list[str] | None = None, 

507 # Note that shell_complete is not fully supported and will be removed in future versions 

508 # TODO: Remove shell_complete in a future version (after 0.16.0) 

509 shell_complete: Callable[ 

510 [_click.Context, _click.Parameter, str], 

511 list["CompletionItem"] | list[str], 

512 ] 

513 | None = None, 

514 autocompletion: Callable[..., Any] | None = None, 

515 default_factory: Callable[[], Any] | None = None, 

516 # Custom type 

517 parser: Callable[[str], Any] | None = None, 

518 # TyperArgument 

519 show_default: bool | str = True, 

520 show_choices: bool = True, 

521 show_envvar: bool = True, 

522 help: str | None = None, 

523 hidden: bool = False, 

524 # Choice 

525 case_sensitive: bool = True, 

526 # Numbers 

527 min: int | float | None = None, 

528 max: int | float | None = None, 

529 clamp: bool = False, 

530 # DateTime 

531 formats: list[str] | None = None, 

532 # File 

533 mode: str | None = None, 

534 encoding: str | None = None, 

535 errors: str | None = "strict", 

536 lazy: bool | None = None, 

537 atomic: bool = False, 

538 # Path 

539 exists: bool = False, 

540 file_okay: bool = True, 

541 dir_okay: bool = True, 

542 writable: bool = False, 

543 readable: bool = True, 

544 resolve_path: bool = False, 

545 allow_dash: bool = False, 

546 path_type: None | type[str] | type[bytes] = None, 

547 # Rich settings 

548 rich_help_panel: str | None = None, 

549 ): 

550 super().__init__( 1abcdefghij

551 default=default, 

552 param_decls=param_decls, 

553 callback=callback, 

554 metavar=metavar, 

555 expose_value=expose_value, 

556 is_eager=is_eager, 

557 envvar=envvar, 

558 shell_complete=shell_complete, 

559 autocompletion=autocompletion, 

560 default_factory=default_factory, 

561 # Custom type 

562 parser=parser, 

563 # TyperArgument 

564 show_default=show_default, 

565 show_choices=show_choices, 

566 show_envvar=show_envvar, 

567 help=help, 

568 hidden=hidden, 

569 # Choice 

570 case_sensitive=case_sensitive, 

571 # Numbers 

572 min=min, 

573 max=max, 

574 clamp=clamp, 

575 # DateTime 

576 formats=formats, 

577 # File 

578 mode=mode, 

579 encoding=encoding, 

580 errors=errors, 

581 lazy=lazy, 

582 atomic=atomic, 

583 # Path 

584 exists=exists, 

585 file_okay=file_okay, 

586 dir_okay=dir_okay, 

587 writable=writable, 

588 readable=readable, 

589 resolve_path=resolve_path, 

590 allow_dash=allow_dash, 

591 path_type=path_type, 

592 # Rich settings 

593 rich_help_panel=rich_help_panel, 

594 ) 

595 

596 

597class ParamMeta: 1abcdefghij

598 empty = inspect.Parameter.empty 1abcdefghij

599 

600 def __init__( 1abcdefghij

601 self, 

602 *, 

603 name: str, 

604 default: Any = inspect.Parameter.empty, 

605 annotation: Any = inspect.Parameter.empty, 

606 ) -> None: 

607 self.name = name 1abcdefghij

608 self.default = default 1abcdefghij

609 self.annotation = annotation 1abcdefghij

610 

611 

612class DeveloperExceptionConfig: 1abcdefghij

613 def __init__( 1abcdefghij

614 self, 

615 *, 

616 pretty_exceptions_enable: bool = True, 

617 pretty_exceptions_show_locals: bool = True, 

618 pretty_exceptions_short: bool = True, 

619 ) -> None: 

620 self.pretty_exceptions_enable = pretty_exceptions_enable 1abcdefghij

621 self.pretty_exceptions_show_locals = pretty_exceptions_show_locals 1abcdefghij

622 self.pretty_exceptions_short = pretty_exceptions_short 1abcdefghij