Coverage for typer/params.py: 100%

1from collections.abc import Callable 7 ctx1aebfcdg

2from typing import TYPE_CHECKING, Annotated, Any, overload 7 ctx1aebfcdg

4from annotated_doc import Doc 7 ctx1aebfcdg

6from . import _click 7 ctx1aebfcdg

7from ._click import types 7 ctx1aebfcdg

8from ._click.shell_completion import CompletionItem 7 ctx1aebfcdg

9from .models import ArgumentInfo, OptionInfo 7 ctx1aebfcdg

11if TYPE_CHECKING: # pragma: no cover 7 ctx1aebfcdg

12 pass

15# Overload for Option created with custom type 'parser'

16@overload 7 ctx1aebfcdg

17def Option( 7 ctx1aebfcdg

18 # Parameter

19 default: Any | None = ..., 4 ctx1abcd

20 *param_decls: str, 4 ctx1abcd

21 callback: Callable[..., Any] | None = None, 7 ctx1aebfcdg

22 metavar: str | None = None, 7 ctx1aebfcdg

23 expose_value: bool = True, 7 ctx1aebfcdg

24 is_eager: bool = False, 7 ctx1aebfcdg

25 envvar: str | list[str] | None = None, 7 ctx1aebfcdg

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

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

28 shell_complete: Callable[ 4 ctx1abcd

29 [_click.Context, _click.Parameter, str], 4 ctx1abcd

30 list["CompletionItem"] | list[str], 4 ctx1abcd

31 ]

32 | None = None, 7 ctx1aebfcdg

33 autocompletion: Callable[..., Any] | None = None, 7 ctx1aebfcdg

34 default_factory: Callable[[], Any] | None = None, 7 ctx1aebfcdg

35 # Custom type

36 parser: Callable[[str], Any] | None = None, 7 ctx1aebfcdg

37 # Option

38 show_default: bool | str = True, 7 ctx1aebfcdg

39 prompt: bool | str = False, 7 ctx1aebfcdg

40 confirmation_prompt: bool = False, 7 ctx1aebfcdg

41 prompt_required: bool = True, 7 ctx1aebfcdg

42 hide_input: bool = False, 7 ctx1aebfcdg

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

44 is_flag: bool | None = None, 7 ctx1aebfcdg

45 flag_value: Any | None = None, 7 ctx1aebfcdg

46 count: bool = False, 7 ctx1aebfcdg

47 allow_from_autoenv: bool = True, 7 ctx1aebfcdg

48 help: str | None = None, 7 ctx1aebfcdg

49 hidden: bool = False, 7 ctx1aebfcdg

50 show_choices: bool = True, 7 ctx1aebfcdg

51 show_envvar: bool = True, 7 ctx1aebfcdg

52 # Choice

53 case_sensitive: bool = True, 7 ctx1aebfcdg

54 # Numbers

55 min: int | float | None = None, 7 ctx1aebfcdg

56 max: int | float | None = None, 7 ctx1aebfcdg

57 clamp: bool = False, 7 ctx1aebfcdg

58 # DateTime

59 formats: list[str] | None = None, 7 ctx1aebfcdg

60 # File

61 mode: str | None = None, 7 ctx1aebfcdg

62 encoding: str | None = None, 7 ctx1aebfcdg

63 errors: str | None = "strict", 7 ctx1aebfcdg

64 lazy: bool | None = None, 7 ctx1aebfcdg

65 atomic: bool = False, 7 ctx1aebfcdg

66 # Path

67 exists: bool = False, 7 ctx1aebfcdg

68 file_okay: bool = True, 7 ctx1aebfcdg

69 dir_okay: bool = True, 7 ctx1aebfcdg

70 writable: bool = False, 7 ctx1aebfcdg

71 readable: bool = True, 7 ctx1aebfcdg

72 resolve_path: bool = False, 7 ctx1aebfcdg

73 allow_dash: bool = False, 7 ctx1aebfcdg

74 path_type: None | type[str] | type[bytes] = None, 7 ctx1aebfcdg

75 # Rich settings

76 rich_help_panel: str | None = None, 7 ctx1aebfcdg

77) -> Any: ... 4 ctx1abcd

80# Overload for Option created with custom type 'click_type'

81@overload 7 ctx1aebfcdg

82def Option( 7 ctx1aebfcdg

83 # Parameter

84 default: Any | None = ..., 4 ctx1abcd

85 *param_decls: str, 4 ctx1abcd

86 callback: Callable[..., Any] | None = None, 7 ctx1aebfcdg

87 metavar: str | None = None, 7 ctx1aebfcdg

88 expose_value: bool = True, 7 ctx1aebfcdg

89 is_eager: bool = False, 7 ctx1aebfcdg

90 envvar: str | list[str] | None = None, 7 ctx1aebfcdg

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

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

93 shell_complete: Callable[ 4 ctx1abcd

94 [_click.Context, _click.Parameter, str], 4 ctx1abcd

95 list["CompletionItem"] | list[str], 4 ctx1abcd

96 ]

97 | None = None, 7 ctx1aebfcdg

98 autocompletion: Callable[..., Any] | None = None, 7 ctx1aebfcdg

99 default_factory: Callable[[], Any] | None = None, 7 ctx1aebfcdg

100 # Custom type

101 click_type: types.ParamType | None = None, 7 ctx1aebfcdg

102 # Option

103 show_default: bool | str = True, 7 ctx1aebfcdg

104 prompt: bool | str = False, 7 ctx1aebfcdg

105 confirmation_prompt: bool = False, 7 ctx1aebfcdg

106 prompt_required: bool = True, 7 ctx1aebfcdg

107 hide_input: bool = False, 7 ctx1aebfcdg

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

109 is_flag: bool | None = None, 7 ctx1aebfcdg

110 flag_value: Any | None = None, 7 ctx1aebfcdg

111 count: bool = False, 7 ctx1aebfcdg

112 allow_from_autoenv: bool = True, 7 ctx1aebfcdg

113 help: str | None = None, 7 ctx1aebfcdg

114 hidden: bool = False, 7 ctx1aebfcdg

115 show_choices: bool = True, 7 ctx1aebfcdg

116 show_envvar: bool = True, 7 ctx1aebfcdg

117 # Choice

118 case_sensitive: bool = True, 7 ctx1aebfcdg

119 # Numbers

120 min: int | float | None = None, 7 ctx1aebfcdg

121 max: int | float | None = None, 7 ctx1aebfcdg

122 clamp: bool = False, 7 ctx1aebfcdg

123 # DateTime

124 formats: list[str] | None = None, 7 ctx1aebfcdg

125 # File

126 mode: str | None = None, 7 ctx1aebfcdg

127 encoding: str | None = None, 7 ctx1aebfcdg

128 errors: str | None = "strict", 7 ctx1aebfcdg

129 lazy: bool | None = None, 7 ctx1aebfcdg

130 atomic: bool = False, 7 ctx1aebfcdg

131 # Path

132 exists: bool = False, 7 ctx1aebfcdg

133 file_okay: bool = True, 7 ctx1aebfcdg

134 dir_okay: bool = True, 7 ctx1aebfcdg

135 writable: bool = False, 7 ctx1aebfcdg

136 readable: bool = True, 7 ctx1aebfcdg

137 resolve_path: bool = False, 7 ctx1aebfcdg

138 allow_dash: bool = False, 7 ctx1aebfcdg

139 path_type: None | type[str] | type[bytes] = None, 7 ctx1aebfcdg

140 # Rich settings

141 rich_help_panel: str | None = None, 7 ctx1aebfcdg

142) -> Any: ... 4 ctx1abcd

143

144

145def Option( 7 ctx1aebfcdg

146 # Parameter

147 default: Annotated[

148 Any | None,

149 Doc(

150 """

151 Usually, [CLI options](https://typer.tiangolo.com/tutorial/options/) are optional and have a default value, passed on like this:

152

153 **Example**

154

155 ```python

156 @app.command()

157 def main(network: str = typer.Option("CNN")):

158 print(f"Training neural network of type: {network}")

159 ```

160

161 Note that this usage is deprecated, and we recommend to use `Annotated` instead:

162 ```

163 @app.command()

164 def main(network: Annotated[str, typer.Option()] = "CNN"):

165 print(f"Hello {name}!")

166 ```

167

168 You can also use `...` ([Ellipsis](https://docs.python.org/3/library/constants.html#Ellipsis)) as the "default" value to clarify that this is a required CLI option.

169 """

170 ),

171 ] = ...,

172 *param_decls: Annotated[

173 str,

174 Doc(

175 """

176 Positional argument that defines how users can call this option on the command line. This may be one or multiple aliases, all strings.

177 If not defined, Typer will automatically use the function parameter as default name.

178 See [the tutorial about CLI Option Names](https://typer.tiangolo.com/tutorial/options/name/) for more details.

179

180 **Example**

181

182 ```python

183 @app.command()

184 def main(user_name: Annotated[str, typer.Option("--user", "-u", "-x")]):

185 print(f"Hello {user_name}")

186 ```

187 """

188 ),

189 ],

190 callback: Annotated[

191 Callable[..., Any] | None,

192 Doc(

193 """

194 Add a callback to this CLI Option, to execute additional logic after its value was received from the terminal.

195 See [the tutorial about callbacks](https://typer.tiangolo.com/tutorial/options/callback-and-context/) for more details.

196

197 **Example**

198

199 ```python

200 def name_callback(value: str):

201 if value != "Deadpool":

202 raise typer.BadParameter("Only Deadpool is allowed")

203 return value

204

205 @app.command()

206 def main(name: Annotated[str, typer.Option(callback=name_callback)]):

207 print(f"Hello {name}")

208 ```

209 """

210 ),

211 ] = None,

212 metavar: Annotated[

213 str | None,

214 Doc(

215 """

216 Customize the name displayed in the [help text](https://typer.tiangolo.com/tutorial/options/help/) to represent this CLI option.

217 Note that this doesn't influence the way the option must be called.

218

219 **Example**

220

221 ```python

222 @app.command()

223 def main(user: Annotated[str, typer.Option(metavar="User name")]):

224 print(f"Hello {user}")

225 ```

226 """

227 ),

228 ] = None,

229 expose_value: Annotated[

230 bool,

231 Doc(

232 """

233 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

234

235 ---

236

237 If this is `True` then the value is passed onwards to the command callback and stored on the context, otherwise it’s skipped.

238 """

239 ),

240 ] = True,

241 is_eager: Annotated[

242 bool,

243 Doc(

244 """

245 Mark a CLI Option to be "eager", ensuring it gets processed before other CLI parameters. This could be relevant when there are other parameters with callbacks that could exit the program early.

246 For more information and an extended example, see the documentation [here](https://typer.tiangolo.com/tutorial/options/version/#fix-with-is_eager).

247 """

248 ),

249 ] = False,

250 envvar: Annotated[

251 str | list[str] | None,

252 Doc(

253 """

254 Configure a CLI Option to read its value from an environment variable if it is not provided in the command line.

255 For more information, see the [documentation on Environment Variables](https://typer.tiangolo.com/tutorial/arguments/envvar/).

256

257 **Example**

258

259 ```python

260 @app.command()

261 def main(user: Annotated[str, typer.Option(envvar="ME")]):

262 print(f"Hello {user}")

263 ```

264 """

265 ),

266 ] = None,

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

268 shell_complete: Annotated[

269 Callable[

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

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

272 ]

273 | None,

274 Doc(

275 """

276 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

277 It is however not fully functional, and will likely be removed in future versions.

278 """

279 ),

280 ] = None,

281 autocompletion: Annotated[

282 Callable[..., Any] | None,

283 Doc(

284 """

285 Provide a custom function that helps to autocomplete the values of this CLI Option.

286 See [the tutorial on parameter autocompletion](https://typer.tiangolo.com/tutorial/options-autocompletion) for more details.

287

288 **Example**

289

290 ```python

291 def complete():

292 return ["Me", "Myself", "I"]

293

294 @app.command()

295 def main(name: Annotated[str, typer.Option(autocompletion=complete)]):

296 print(f"Hello {name}")

297 ```

298 """

299 ),

300 ] = None,

301 default_factory: Annotated[

302 Callable[[], Any] | None,

303 Doc(

304 """

305 Provide a custom function that dynamically generates a [default](https://typer.tiangolo.com/tutorial/arguments/default) for this CLI Option.

306

307 **Example**

308

309 ```python

310 def get_name():

311 return random.choice(["Me", "Myself", "I"])

312

313 @app.command()

314 def main(name: Annotated[str, typer.Option(default_factory=get_name)]):

315 print(f"Hello {name}")

316 ```

317 """

318 ),

319 ] = None,

320 # Custom type

321 parser: Annotated[

322 Callable[[str], Any] | None,

323 Doc(

324 """

325 Use your own custom types in Typer applications by defining a `parser` function that parses input into your own types:

326

327 **Example**

328

329 ```python

330 class CustomClass:

331 def __init__(self, value: str):

332 self.value = value

333

334 def __str__(self):

335 return f"<CustomClass: value={self.value}>"

336

337 def my_parser(value: str):

338 return CustomClass(value * 2)

339

340 @app.command()

341 def main(opt: Annotated[CustomClass, typer.Option(parser=my_parser)] = "Foo"):

342 print(f"--opt is {opt}")

343 ```

344 """

345 ),

346 ] = None,

347 click_type: Annotated[

348 types.ParamType | None,

349 Doc(

350 """

351 Define this parameter to use a [custom Click type](https://click.palletsprojects.com/en/stable/parameters/#implementing-custom-types) in your Typer applications.

352

353 **Example**

354

355 ```python

356 class MyClass:

357 def __init__(self, value: str):

358 self.value = value

359

360 def __str__(self):

361 return f"<MyClass: value={self.value}>"

362

363 class MyParser(click.ParamType):

364 name = "MyClass"

365

366 def convert(self, value, param, ctx):

367 return MyClass(value * 3)

368

369 @app.command()

370 def main(opt: Annotated[MyClass, typer.Option(click_type=MyParser())] = "Foo"):

371 print(f"--opt is {opt}")

372 ```

373 """

374 ),

375 ] = None,

376 # Option

377 show_default: Annotated[

378 bool | str,

379 Doc(

380 """

381 When set to `False`, don't show the default value of this CLI Option in the [help text](https://typer.tiangolo.com/tutorial/options/help/).

382

383 **Example**

384

385 ```python

386 @app.command()

387 def main(name: Annotated[str, typer.Option(show_default=False)] = "Rick"):

388 print(f"Hello {name}")

389 ```

390 """

391 ),

392 ] = True,

393 prompt: Annotated[

394 bool | str,

395 Doc(

396 """

397 When set to `True`, a prompt will appear to ask for the value of this CLI Option if it was not provided:

398

399 **Example**

400

401 ```python

402 @app.command()

403 def main(name: str, lastname: Annotated[str, typer.Option(prompt=True)]):

404 print(f"Hello {name} {lastname}")

405 ```

406 """

407 ),

408 ] = False,

409 confirmation_prompt: Annotated[

410 bool,

411 Doc(

412 """

413 When set to `True`, a user will need to type a prompted value twice (may be useful for passwords etc.).

414

415 **Example**

416

417 ```python

418 @app.command()

419 def main(project: Annotated[str, typer.Option(prompt=True, confirmation_prompt=True)]):

420 print(f"Deleting project {project}")

421 ```

422 """

423 ),

424 ] = False,

425 prompt_required: Annotated[

426 bool,

427 Doc(

428 """

429 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

430

431 ---

432

433 If this is `False` then a prompt is only shown if the option's flag is given without a value.

434 """

435 ),

436 ] = True,

437 hide_input: Annotated[

438 bool,

439 Doc(

440 """

441 When you've configured a prompt, for instance for [querying a password](https://typer.tiangolo.com/tutorial/options/password/),

442 don't show anything on the screen while the user is typing the value.

443

444 **Example**

445

446 ```python

447 @app.command()

448 def login(

449 name: str,

450 password: Annotated[str, typer.Option(prompt=True, hide_input=True)],

451 ):

452 print(f"Hello {name}. Doing something very secure with password.")

453 ```

454 """

455 ),

456 ] = False,

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

458 is_flag: Annotated[

459 bool | None,

460 Doc(

461 """

462 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

463 It is however not fully functional, and will likely be removed in future versions.

464 """

465 ),

466 ] = None,

467 flag_value: Annotated[

468 Any | None,

469 Doc(

470 """

471 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

472 It is however not fully functional, and will likely be removed in future versions.

473 """

474 ),

475 ] = None,

476 count: Annotated[

477 bool,

478 Doc(

479 """

480 Make a CLI Option work as a [counter](https://typer.tiangolo.com/tutorial/parameter-types/number/#counter-cli-options).

481 The CLI option will have the `int` value representing the number of times the option was used on the command line.

482

483 **Example**

484

485 ```python

486 @app.command()

487 def main(verbose: Annotated[int, typer.Option("--verbose", "-v", count=True)] = 0):

488 print(f"Verbose level is {verbose}")

489 ```

490 """

491 ),

492 ] = False,

493 allow_from_autoenv: Annotated[

494 bool,

495 Doc(

496 """

497 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

498

499 ---

500

501 If this is enabled then the value of this parameter will be pulled from an environment variable in case a prefix is defined on the context.

502 """

503 ),

504 ] = True,

505 help: Annotated[

506 str | None,

507 Doc(

508 """

509 Help text for this CLI Option.

510 See [the tutorial about CLI Options with help](https://typer.tiangolo.com/tutorial/options/help/) for more dedails.

511

512 **Example**

513

514 ```python

515 @app.command()

516 def greet(name: Annotated[str, typer.Option(help="Person to greet")] = "Deadpool"):

517 print(f"Hello {name}")

518 ```

519 """

520 ),

521 ] = None,

522 hidden: Annotated[

523 bool,

524 Doc(

525 """

526 Hide this CLI Option from [help outputs](https://typer.tiangolo.com/tutorial/options/help). `False` by default.

527

528 **Example**

529

530 ```python

531 @app.command()

532 def greet(name: Annotated[str, typer.Option(hidden=True)] = "Deadpool"):

533 print(f"Hello {name}")

534 ```

535 """

536 ),

537 ] = False,

538 show_choices: Annotated[

539 bool,

540 Doc(

541 """

542 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

543

544 ---

545

546 When set to `False`, this suppresses choices from being displayed inline when `prompt` is used.

547 """

548 ),

549 ] = True,

550 show_envvar: Annotated[

551 bool,

552 Doc(

553 """

554 When an ["envvar"](https://typer.tiangolo.com/tutorial/arguments/envvar) is defined, prevent it from showing up in the help text:

555

556 **Example**

557

558 ```python

559 @app.command()

560 def main(user: Annotated[str, typer.Option(envvar="ME", show_envvar=False)]):

561 print(f"Hello {user}")

562 ```

563 """

564 ),

565 ] = True,

566 # Choice

567 case_sensitive: Annotated[

568 bool,

569 Doc(

570 """

571 For a CLI Option representing an [Enum (choice)](https://typer.tiangolo.com/tutorial/parameter-types/enum),

572 you can allow case-insensitive matching with this parameter:

573

574 **Example**

575

576 ```python

577 from enum import Enum

578

579 class NeuralNetwork(str, Enum):

580 simple = "simple"

581 conv = "conv"

582 lstm = "lstm"

583

584 @app.command()

585 def main(

586 network: Annotated[NeuralNetwork, typer.Option(case_sensitive=False)]):

587 print(f"Training neural network of type: {network.value}")

588 ```

589

590 With this setting, "LSTM" or "lstm" will both be valid values that will be resolved to `NeuralNetwork.lstm`.

591 """

592 ),

593 ] = True,

594 # Numbers

595 min: Annotated[

596 int | float | None,

597 Doc(

598 """

599 For a CLI Option representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),

600 you can define numeric validations with `min` and `max` values:

601

602 **Example**

603

604 ```python

605 @app.command()

606 def main(

607 user: Annotated[str, typer.Argument()],

608 user_id: Annotated[int, typer.Option(min=1, max=1000)],

609 ):

610 print(f"ID for {user} is {user_id}")

611 ```

612

613 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.

614 """

615 ),

616 ] = None,

617 max: Annotated[

618 int | float | None,

619 Doc(

620 """

621 For a CLI Option representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),

622 you can define numeric validations with `min` and `max` values:

623

624 **Example**

625

626 ```python

627 @app.command()

628 def main(

629 user: Annotated[str, typer.Argument()],

630 user_id: Annotated[int, typer.Option(min=1, max=1000)],

631 ):

632 print(f"ID for {user} is {user_id}")

633 ```

634

635 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.

636 """

637 ),

638 ] = None,

639 clamp: Annotated[

640 bool,

641 Doc(

642 """

643 For a CLI Option representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) and that is bounded by using `min` and/or `max`,

644 you can opt to use the closest minimum or maximum value instead of raising an error when the value is out of bounds. This is done by setting `clamp` to `True`.

645

646 **Example**

647

648 ```python

649 @app.command()

650 def main(

651 user: Annotated[str, typer.Argument()],

652 user_id: Annotated[int, typer.Option(min=1, max=1000, clamp=True)],

653 ):

654 print(f"ID for {user} is {user_id}")

655 ```

656

657 If the user attempts to input 3420 for `user_id`, this will internally be converted to `1000`.

658 """

659 ),

660 ] = False,

661 # DateTime

662 formats: Annotated[

663 list[str] | None,

664 Doc(

665 """

666 For a CLI Option representing a [DateTime object](https://typer.tiangolo.com/tutorial/parameter-types/datetime),

667 you can customize the formats that can be parsed automatically:

668

669 **Example**

670

671 ```python

672 from datetime import datetime

673

674 @app.command()

675 def main(

676 birthday: Annotated[

677 datetime,

678 typer.Option(

679 formats=["%Y-%m-%d", "%Y-%m-%d %H:%M:%S", "%m/%d/%Y"]

680 ),

681 ],

682 ):

683 print(f"Birthday defined at: {birthday}")

684 ```

685 """

686 ),

687 ] = None,

688 # File

689 mode: Annotated[

690 str | None,

691 Doc(

692 """

693 For a CLI Option representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),

694 you can customize the mode to open the file with. If unset, Typer will set a [sensible value by default](https://typer.tiangolo.com/tutorial/parameter-types/file/#advanced-mode).

695

696 **Example**

697

698 ```python

699 @app.command()

700 def main(config: Annotated[typer.FileText, typer.Option(mode="a")]):

701 config.write("This is a single line\\n")

702 print("Config line written")

703 ```

704 """

705 ),

706 ] = None,

707 encoding: Annotated[

708 str | None,

709 Doc(

710 """

711 Customize the encoding of this CLI Option represented by a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/).

712

713 **Example**

714

715 ```python

716 @app.command()

717 def main(config: Annotated[typer.FileText, typer.Option(encoding="utf-8")]):

718 config.write("All the text gets written\\n")

719 ```

720 """

721 ),

722 ] = None,

723 errors: Annotated[

724 str | None,

725 Doc(

726 """

727 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

728

729 ---

730

731 The error handling mode.

732 """

733 ),

734 ] = "strict",

735 lazy: Annotated[

736 bool | None,

737 Doc(

738 """

739 For a CLI Option representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),

740 by default the file will not be created until you actually start writing to it.

741 You can change this behaviour by setting this parameter.

742 By default, it's set to `True` for writing and to `False` for reading.

743

744 **Example**

745

746 ```python

747 @app.command()

748 def main(config: Annotated[typer.FileText, typer.Option(mode="a", lazy=False)]):

749 config.write("This is a single line\\n")

750 print("Config line written")

751 ```

752 """

753 ),

754 ] = None,

755 atomic: Annotated[

756 bool,

757 Doc(

758 """

759 For a CLI Option representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),

760 you can ensure that all write instructions first go into a temporal file, and are only moved to the final destination after completing

761 by setting `atomic` to `True`. This can be useful for files with potential concurrent access.

762

763 **Example**

764

765 ```python

766 @app.command()

767 def main(config: Annotated[typer.FileText, typer.Option(mode="a", atomic=True)]):

768 config.write("All the text")

769 ```

770 """

771 ),

772 ] = False,

773 # Path

774 exists: Annotated[

775 bool,

776 Doc(

777 """

778 When set to `True` for a [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/),

779 additional validation is performed to check that the file or directory exists. If not, the value will be invalid.

780

781 **Example**

782

783 ```python

784 from pathlib import Path

785

786 @app.command()

787 def main(config: Annotated[Path, typer.Option(exists=True)]):

788 text = config.read_text()

789 print(f"Config file contents: {text}")

790 ```

791 """

792 ),

793 ] = False,

794 file_okay: Annotated[

795 bool,

796 Doc(

797 """

798 Determine whether or not a [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/)

799 is allowed to refer to a file. When this is set to `False`, the application will raise a validation error when a path to a file is given.

800

801 **Example**

802

803 ```python

804 from pathlib import Path

805

806 @app.command()

807 def main(config: Annotated[Path, typer.Option(exists=True, file_okay=False)]):

808 print(f"Directory listing: {[x.name for x in config.iterdir()]}")

809 ```

810 """

811 ),

812 ] = True,

813 dir_okay: Annotated[

814 bool,

815 Doc(

816 """

817 Determine whether or not a [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/)

818 is allowed to refer to a directory. When this is set to `False`, the application will raise a validation error when a path to a directory is given.

819

820 **Example**

821

822 ```python

823 from pathlib import Path

824

825 @app.command()

826 def main(config: Annotated[Path, typer.Argument(exists=True, dir_okay=False)]):

827 text = config.read_text()

828 print(f"Config file contents: {text}")

829 ```

830 """

831 ),

832 ] = True,

833 writable: Annotated[

834 bool,

835 Doc(

836 """

837 Whether or not to perform a writable check for this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/).

838

839 **Example**

840

841 ```python

842 from pathlib import Path

843

844 @app.command()

845 def main(config: Annotated[Path, typer.Option(writable=True)]):

846 config.write_text("All the text")

847 ```

848 """

849 ),

850 ] = False,

851 readable: Annotated[

852 bool,

853 Doc(

854 """

855 Whether or not to perform a readable check for this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/).

856

857 **Example**

858

859 ```python

860 from pathlib import Path

861

862 @app.command()

863 def main(config: Annotated[Path, typer.Option(readable=True)]):

864 config.read_text("All the text")

865 ```

866 """

867 ),

868 ] = True,

869 resolve_path: Annotated[

870 bool,

871 Doc(

872 """

873 Whether or not to fully resolve the path of this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/),

874 meaning that the path becomes absolute and symlinks are resolved.

875

876 **Example**

877

878 ```python

879 from pathlib import Path

880

881 @app.command()

882 def main(config: Annotated[Path, typer.Option(resolve_path=True)]):

883 config.read_text("All the text")

884 ```

885 """

886 ),

887 ] = False,

888 allow_dash: Annotated[

889 bool,

890 Doc(

891 """

892 When set to `True`, a single dash for this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/)

893 would be a valid value, indicating standard streams. This is a more advanced use-case.

894 """

895 ),

896 ] = False,

897 path_type: Annotated[

898 None | type[str] | type[bytes],

899 Doc(

900 """

901 A string type that will be used to represent this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).

902 The default is `None` which means the return value will be either bytes or unicode, depending on what makes most sense given the input data.

903 This is a more advanced use-case.

904 """

905 ),

906 ] = None,

907 # Rich settings

908 rich_help_panel: Annotated[

909 str | None,

910 Doc(

911 """

912 Set the panel name where you want this CLI Option to be shown in the [help text](https://typer.tiangolo.com/tutorial/arguments/help).

913

914 **Example**

915

916 ```python

917 @app.command()

918 def main(

919 name: Annotated[str, typer.Argument(help="Who to greet")],

920 age: Annotated[str, typer.Option(help="Their age", rich_help_panel="Data")],

921 ):

922 print(f"Hello {name} of age {age}")

923 ```

924 """

925 ),

926 ] = None,

927) -> Any:

928 """

929 A [CLI Option](https://typer.tiangolo.com/tutorial/options) is a parameter to your command line application that is called with a single or double dash, something like `--verbose` or `-v`.

930

931 Often, CLI Options are optional, meaning that users can omit them from the command. However, you can set them to be required by using `Annotated`

932 and omitting a default value.

933

934 ## Example

935

936 ```python

937 @app.command()

938 def register(

939 user: Annotated[str, typer.Argument()],

940 age: Annotated[int, typer.Option(min=18)],

941 ):

942 print(f"User is {user}")

943 print(f"--age is {age}")

944 ```

945

946 Note how in this example, `--age` is a required CLI Option.

947 """

948 return OptionInfo( 7 ctx1aebfcdg

949 # Parameter

950 default=default,

951 param_decls=param_decls,

952 callback=callback,

953 metavar=metavar,

954 expose_value=expose_value,

955 is_eager=is_eager,

956 envvar=envvar,

957 shell_complete=shell_complete,

958 autocompletion=autocompletion,

959 default_factory=default_factory,

960 # Custom type

961 parser=parser,

962 click_type=click_type,

963 # Option

964 show_default=show_default,

965 prompt=prompt,

966 confirmation_prompt=confirmation_prompt,

967 prompt_required=prompt_required,

968 hide_input=hide_input,

969 is_flag=is_flag,

970 flag_value=flag_value,

971 count=count,

972 allow_from_autoenv=allow_from_autoenv,

973 help=help,

974 hidden=hidden,

975 show_choices=show_choices,

976 show_envvar=show_envvar,

977 # Choice

978 case_sensitive=case_sensitive,

979 # Numbers

980 min=min,

981 max=max,

982 clamp=clamp,

983 # DateTime

984 formats=formats,

985 # File

986 mode=mode,

987 encoding=encoding,

988 errors=errors,

989 lazy=lazy,

990 atomic=atomic,

991 # Path

992 exists=exists,

993 file_okay=file_okay,

994 dir_okay=dir_okay,

995 writable=writable,

996 readable=readable,

997 resolve_path=resolve_path,

998 allow_dash=allow_dash,

999 path_type=path_type,

1000 # Rich settings

1001 rich_help_panel=rich_help_panel,

1002 )

1003

1004

1005# Overload for Argument created with custom type 'parser'

1006@overload 7 ctx1aebfcdg

1007def Argument( 7 ctx1aebfcdg

1008 # Parameter

1009 default: Any | None = ..., 4 ctx1abcd

1010 *,

1011 callback: Callable[..., Any] | None = None, 7 ctx1aebfcdg

1012 metavar: str | None = None, 7 ctx1aebfcdg

1013 expose_value: bool = True, 7 ctx1aebfcdg

1014 is_eager: bool = False, 7 ctx1aebfcdg

1015 envvar: str | list[str] | None = None, 7 ctx1aebfcdg

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

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

1018 shell_complete: Callable[ 4 ctx1abcd

1019 [_click.Context, _click.Parameter, str], 4 ctx1abcd

1020 list["CompletionItem"] | list[str], 4 ctx1abcd

1021 ]

1022 | None = None, 7 ctx1aebfcdg

1023 autocompletion: Callable[..., Any] | None = None, 7 ctx1aebfcdg

1024 default_factory: Callable[[], Any] | None = None, 7 ctx1aebfcdg

1025 # Custom type

1026 parser: Callable[[str], Any] | None = None, 7 ctx1aebfcdg

1027 # TyperArgument

1028 show_default: bool | str = True, 7 ctx1aebfcdg

1029 show_choices: bool = True, 7 ctx1aebfcdg

1030 show_envvar: bool = True, 7 ctx1aebfcdg

1031 help: str | None = None, 7 ctx1aebfcdg

1032 hidden: bool = False, 7 ctx1aebfcdg

1033 # Choice

1034 case_sensitive: bool = True, 7 ctx1aebfcdg

1035 # Numbers

1036 min: int | float | None = None, 7 ctx1aebfcdg

1037 max: int | float | None = None, 7 ctx1aebfcdg

1038 clamp: bool = False, 7 ctx1aebfcdg

1039 # DateTime

1040 formats: list[str] | None = None, 7 ctx1aebfcdg

1041 # File

1042 mode: str | None = None, 7 ctx1aebfcdg

1043 encoding: str | None = None, 7 ctx1aebfcdg

1044 errors: str | None = "strict", 7 ctx1aebfcdg

1045 lazy: bool | None = None, 7 ctx1aebfcdg

1046 atomic: bool = False, 7 ctx1aebfcdg

1047 # Path

1048 exists: bool = False, 7 ctx1aebfcdg

1049 file_okay: bool = True, 7 ctx1aebfcdg

1050 dir_okay: bool = True, 7 ctx1aebfcdg

1051 writable: bool = False, 7 ctx1aebfcdg

1052 readable: bool = True, 7 ctx1aebfcdg

1053 resolve_path: bool = False, 7 ctx1aebfcdg

1054 allow_dash: bool = False, 7 ctx1aebfcdg

1055 path_type: None | type[str] | type[bytes] = None, 7 ctx1aebfcdg

1056 # Rich settings

1057 rich_help_panel: str | None = None, 7 ctx1aebfcdg

1058) -> Any: ... 4 ctx1abcd

1059

1060

1061# Overload for Argument created with custom type 'click_type'

1062@overload 7 ctx1aebfcdg

1063def Argument( 7 ctx1aebfcdg

1064 # Parameter

1065 default: Any | None = ..., 4 ctx1abcd

1066 *,

1067 callback: Callable[..., Any] | None = None, 7 ctx1aebfcdg

1068 metavar: str | None = None, 7 ctx1aebfcdg

1069 expose_value: bool = True, 7 ctx1aebfcdg

1070 is_eager: bool = False, 7 ctx1aebfcdg

1071 envvar: str | list[str] | None = None, 7 ctx1aebfcdg

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

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

1074 shell_complete: Callable[ 4 ctx1abcd

1075 [_click.Context, _click.Parameter, str], 4 ctx1abcd

1076 list["CompletionItem"] | list[str], 4 ctx1abcd

1077 ]

1078 | None = None, 7 ctx1aebfcdg

1079 autocompletion: Callable[..., Any] | None = None, 7 ctx1aebfcdg

1080 default_factory: Callable[[], Any] | None = None, 7 ctx1aebfcdg

1081 # Custom type

1082 click_type: types.ParamType | None = None, 7 ctx1aebfcdg

1083 # TyperArgument

1084 show_default: bool | str = True, 7 ctx1aebfcdg

1085 show_choices: bool = True, 7 ctx1aebfcdg

1086 show_envvar: bool = True, 7 ctx1aebfcdg

1087 help: str | None = None, 7 ctx1aebfcdg

1088 hidden: bool = False, 7 ctx1aebfcdg

1089 # Choice

1090 case_sensitive: bool = True, 7 ctx1aebfcdg

1091 # Numbers

1092 min: int | float | None = None, 7 ctx1aebfcdg

1093 max: int | float | None = None, 7 ctx1aebfcdg

1094 clamp: bool = False, 7 ctx1aebfcdg

1095 # DateTime

1096 formats: list[str] | None = None, 7 ctx1aebfcdg

1097 # File

1098 mode: str | None = None, 7 ctx1aebfcdg

1099 encoding: str | None = None, 7 ctx1aebfcdg

1100 errors: str | None = "strict", 7 ctx1aebfcdg

1101 lazy: bool | None = None, 7 ctx1aebfcdg

1102 atomic: bool = False, 7 ctx1aebfcdg

1103 # Path

1104 exists: bool = False, 7 ctx1aebfcdg

1105 file_okay: bool = True, 7 ctx1aebfcdg

1106 dir_okay: bool = True, 7 ctx1aebfcdg

1107 writable: bool = False, 7 ctx1aebfcdg

1108 readable: bool = True, 7 ctx1aebfcdg

1109 resolve_path: bool = False, 7 ctx1aebfcdg

1110 allow_dash: bool = False, 7 ctx1aebfcdg

1111 path_type: None | type[str] | type[bytes] = None, 7 ctx1aebfcdg

1112 # Rich settings

1113 rich_help_panel: str | None = None, 7 ctx1aebfcdg

1114) -> Any: ... 4 ctx1abcd

1115

1116

1117def Argument( 7 ctx1aebfcdg

1118 # Parameter

1119 default: Annotated[

1120 Any | None,

1121 Doc(

1122 """

1123 By default, CLI arguments are required. However, by giving them a default value they become [optional](https://typer.tiangolo.com/tutorial/arguments/optional):

1124

1125 **Example**

1126

1127 ```python

1128 @app.command()

1129 def main(name: str = typer.Argument("World")):

1130 print(f"Hello {name}!")

1131 ```

1132

1133 Note that this usage is deprecated, and we recommend to use `Annotated` instead:

1134 ```python

1135 @app.command()

1136 def main(name: Annotated[str, typer.Argument()] = "World"):

1137 print(f"Hello {name}!")

1138 ```

1139 """

1140 ),

1141 ] = ...,

1142 *,

1143 callback: Annotated[

1144 Callable[..., Any] | None,

1145 Doc(

1146 """

1147 Add a callback to this CLI Argument, to execute additional logic with the value received from the terminal.

1148 See [the tutorial about callbacks](https://typer.tiangolo.com/tutorial/options/callback-and-context/) for more details.

1149

1150 **Example**

1151

1152 ```python

1153 def name_callback(value: str):

1154 if value != "Deadpool":

1155 raise typer.BadParameter("Only Deadpool is allowed")

1156 return value

1157

1158 @app.command()

1159 def main(name: Annotated[str, typer.Argument(callback=name_callback)]):

1160 print(f"Hello {name}")

1161 ```

1162 """

1163 ),

1164 ] = None,

1165 metavar: Annotated[

1166 str | None,

1167 Doc(

1168 """

1169 Customize the name displayed in the help text to represent this CLI Argument.

1170 By default, it will be the same name you declared, in uppercase.

1171 See [the tutorial about CLI Arguments with Help](https://typer.tiangolo.com/tutorial/arguments/help/#custom-help-name-metavar) for more details.

1172

1173 **Example**

1174

1175 ```python

1176 @app.command()

1177 def main(name: Annotated[str, typer.Argument(metavar="✨username✨")]):

1178 print(f"Hello {name}")

1179 ```

1180 """

1181 ),

1182 ] = None,

1183 expose_value: Annotated[

1184 bool,

1185 Doc(

1186 """

1187 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

1188

1189 ---

1190

1191 If this is `True` then the value is passed onwards to the command callback and stored on the context, otherwise it’s skipped.

1192 """

1193 ),

1194 ] = True,

1195 is_eager: Annotated[

1196 bool,

1197 Doc(

1198 """

1199 Set an argument to "eager" to ensure it gets processed before other CLI parameters. This could be relevant when there are other parameters with callbacks that could exit the program early.

1200 For more information and an extended example, see the documentation [here](https://typer.tiangolo.com/tutorial/options/version/#fix-with-is_eager).

1201 """

1202 ),

1203 ] = False,

1204 envvar: Annotated[

1205 str | list[str] | None,

1206 Doc(

1207 """

1208 Configure an argument to read a value from an environment variable if it is not provided in the command line as a CLI argument.

1209 For more information, see the [documentation on Environment Variables](https://typer.tiangolo.com/tutorial/arguments/envvar/).

1210

1211 **Example**

1212

1213 ```python

1214 @app.command()

1215 def main(name: Annotated[str, typer.Argument(envvar="ME")]):

1216 print(f"Hello Mr. {name}")

1217 ```

1218 """

1219 ),

1220 ] = None,

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

1222 shell_complete: Annotated[

1223 Callable[

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

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

1226 ]

1227 | None,

1228 Doc(

1229 """

1230 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

1231 It is however not fully functional, and will likely be removed in future versions.

1232 """

1233 ),

1234 ] = None,

1235 autocompletion: Annotated[

1236 Callable[..., Any] | None,

1237 Doc(

1238 """

1239 Provide a custom function that helps to autocomplete the values of this CLI Argument.

1240 See [the tutorial on parameter autocompletion](https://typer.tiangolo.com/tutorial/options-autocompletion) for more details.

1241

1242 **Example**

1243

1244 ```python

1245 def complete():

1246 return ["Me", "Myself", "I"]

1247

1248 @app.command()

1249 def main(name: Annotated[str, typer.Argument(autocompletion=complete)]):

1250 print(f"Hello {name}")

1251 ```

1252 """

1253 ),

1254 ] = None,

1255 default_factory: Annotated[

1256 Callable[[], Any] | None,

1257 Doc(

1258 """

1259 Provide a custom function that dynamically generates a [default](https://typer.tiangolo.com/tutorial/arguments/default) for this CLI Argument.

1260

1261 **Example**

1262

1263 ```python

1264 def get_name():

1265 return random.choice(["Me", "Myself", "I"])

1266

1267 @app.command()

1268 def main(name: Annotated[str, typer.Argument(default_factory=get_name)]):

1269 print(f"Hello {name}")

1270 ```

1271 """

1272 ),

1273 ] = None,

1274 # Custom type

1275 parser: Annotated[

1276 Callable[[str], Any] | None,

1277 Doc(

1278 """

1279 Use your own custom types in Typer applications by defining a `parser` function that parses input into your own types:

1280

1281 **Example**

1282

1283 ```python

1284 class CustomClass:

1285 def __init__(self, value: str):

1286 self.value = value

1287

1288 def __str__(self):

1289 return f"<CustomClass: value={self.value}>"

1290

1291 def my_parser(value: str):

1292 return CustomClass(value * 2)

1293

1294 @app.command()

1295 def main(arg: Annotated[CustomClass, typer.Argument(parser=my_parser):

1296 print(f"arg is {arg}")

1297 ```

1298 """

1299 ),

1300 ] = None,

1301 click_type: Annotated[

1302 types.ParamType | None,

1303 Doc(

1304 """

1305 Define this parameter to use a [custom Click type](https://click.palletsprojects.com/en/stable/parameters/#implementing-custom-types) in your Typer applications.

1306

1307 **Example**

1308

1309 ```python

1310 class MyClass:

1311 def __init__(self, value: str):

1312 self.value = value

1313

1314 def __str__(self):

1315 return f"<MyClass: value={self.value}>"

1316

1317 class MyParser(click.ParamType):

1318 name = "MyClass"

1319

1320 def convert(self, value, param, ctx):

1321 return MyClass(value * 3)

1322

1323 @app.command()

1324 def main(arg: Annotated[MyClass, typer.Argument(click_type=MyParser())]):

1325 print(f"arg is {arg}")

1326 ```

1327 """

1328 ),

1329 ] = None,

1330 # TyperArgument

1331 show_default: Annotated[

1332 bool | str,

1333 Doc(

1334 """

1335 When set to `False`, don't show the default value of this CLI Argument in the [help text](https://typer.tiangolo.com/tutorial/arguments/help/).

1336

1337 **Example**

1338

1339 ```python

1340 @app.command()

1341 def main(name: Annotated[str, typer.Argument(show_default=False)] = "Rick"):

1342 print(f"Hello {name}")

1343 ```

1344 """

1345 ),

1346 ] = True,

1347 show_choices: Annotated[

1348 bool,

1349 Doc(

1350 """

1351 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

1352

1353 ---

1354

1355 When set to `False`, this suppresses choices from being displayed inline when `prompt` is used.

1356 """

1357 ),

1358 ] = True,

1359 show_envvar: Annotated[

1360 bool,

1361 Doc(

1362 """

1363 When an ["envvar"](https://typer.tiangolo.com/tutorial/arguments/envvar) is defined, prevent it from showing up in the help text:

1364

1365 **Example**

1366

1367 ```python

1368 @app.command()

1369 def main(name: Annotated[str, typer.Argument(envvar="ME", show_envvar=False)]):

1370 print(f"Hello Mr. {name}")

1371 ```

1372 """

1373 ),

1374 ] = True,

1375 help: Annotated[

1376 str | None,

1377 Doc(

1378 """

1379 Help text for this CLI Argument.

1380 See [the tutorial about CLI Arguments with help](https://typer.tiangolo.com/tutorial/arguments/help/) for more dedails.

1381

1382 **Example**

1383

1384 ```python

1385 @app.command()

1386 def greet(name: Annotated[str, typer.Argument(help="Person to greet")]):

1387 print(f"Hello {name}")

1388 ```

1389 """

1390 ),

1391 ] = None,

1392 hidden: Annotated[

1393 bool,

1394 Doc(

1395 """

1396 Hide this CLI Argument from [help outputs](https://typer.tiangolo.com/tutorial/arguments/help). `False` by default.

1397

1398 **Example**

1399

1400 ```python

1401 @app.command()

1402 def main(name: Annotated[str, typer.Argument(hidden=True)] = "World"):

1403 print(f"Hello {name}")

1404 ```

1405 """

1406 ),

1407 ] = False,

1408 # Choice

1409 case_sensitive: Annotated[

1410 bool,

1411 Doc(

1412 """

1413 For a CLI Argument representing an [Enum (choice)](https://typer.tiangolo.com/tutorial/parameter-types/enum),

1414 you can allow case-insensitive matching with this parameter:

1415

1416 **Example**

1417

1418 ```python

1419 from enum import Enum

1420

1421 class NeuralNetwork(str, Enum):

1422 simple = "simple"

1423 conv = "conv"

1424 lstm = "lstm"

1425

1426 @app.command()

1427 def main(

1428 network: Annotated[NeuralNetwork, typer.Argument(case_sensitive=False)]):

1429 print(f"Training neural network of type: {network.value}")

1430 ```

1431

1432 With this setting, "LSTM" or "lstm" will both be valid values that will be resolved to `NeuralNetwork.lstm`.

1433 """

1434 ),

1435 ] = True,

1436 # Numbers

1437 min: Annotated[

1438 int | float | None,

1439 Doc(

1440 """

1441 For a CLI Argument representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),

1442 you can define numeric validations with `min` and `max` values:

1443

1444 **Example**

1445

1446 ```python

1447 @app.command()

1448 def main(

1449 user: Annotated[str, typer.Argument()],

1450 user_id: Annotated[int, typer.Argument(min=1, max=1000)],

1451 ):

1452 print(f"ID for {user} is {user_id}")

1453 ```

1454

1455 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.

1456 """

1457 ),

1458 ] = None,

1459 max: Annotated[

1460 int | float | None,

1461 Doc(

1462 """

1463 For a CLI Argument representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),

1464 you can define numeric validations with `min` and `max` values:

1465

1466 **Example**

1467

1468 ```python

1469 @app.command()

1470 def main(

1471 user: Annotated[str, typer.Argument()],

1472 user_id: Annotated[int, typer.Argument(min=1, max=1000)],

1473 ):

1474 print(f"ID for {user} is {user_id}")

1475 ```

1476

1477 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.

1478 """

1479 ),

1480 ] = None,

1481 clamp: Annotated[

1482 bool,

1483 Doc(

1484 """

1485 For a CLI Argument representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) and that is bounded by using `min` and/or `max`,

1486 you can opt to use the closest minimum or maximum value instead of raising an error. This is done by setting `clamp` to `True`.

1487

1488 **Example**

1489

1490 ```python

1491 @app.command()

1492 def main(

1493 user: Annotated[str, typer.Argument()],

1494 user_id: Annotated[int, typer.Argument(min=1, max=1000, clamp=True)],

1495 ):

1496 print(f"ID for {user} is {user_id}")

1497 ```

1498

1499 If the user attempts to input 3420 for `user_id`, this will internally be converted to `1000`.

1500 """

1501 ),

1502 ] = False,

1503 # DateTime

1504 formats: Annotated[

1505 list[str] | None,

1506 Doc(

1507 """

1508 For a CLI Argument representing a [DateTime object](https://typer.tiangolo.com/tutorial/parameter-types/datetime),

1509 you can customize the formats that can be parsed automatically:

1510

1511 **Example**

1512

1513 ```python

1514 from datetime import datetime

1515

1516 @app.command()

1517 def main(

1518 birthday: Annotated[

1519 datetime,

1520 typer.Argument(

1521 formats=["%Y-%m-%d", "%Y-%m-%d %H:%M:%S", "%m/%d/%Y"]

1522 ),

1523 ],

1524 ):

1525 print(f"Birthday defined at: {birthday}")

1526 ```

1527 """

1528 ),

1529 ] = None,

1530 # File

1531 mode: Annotated[

1532 str | None,

1533 Doc(

1534 """

1535 For a CLI Argument representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),

1536 you can customize the mode to open the file with. If unset, Typer will set a [sensible value by default](https://typer.tiangolo.com/tutorial/parameter-types/file/#advanced-mode).

1537

1538 **Example**

1539

1540 ```python

1541 @app.command()

1542 def main(config: Annotated[typer.FileText, typer.Argument(mode="a")]):

1543 config.write("This is a single line\\n")

1544 print("Config line written")

1545 ```

1546 """

1547 ),

1548 ] = None,

1549 encoding: Annotated[

1550 str | None,

1551 Doc(

1552 """

1553 Customize the encoding of this CLI Argument represented by a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/).

1554

1555 **Example**

1556

1557 ```python

1558 @app.command()

1559 def main(config: Annotated[typer.FileText, typer.Argument(encoding="utf-8")]):

1560 config.write("All the text gets written\\n")

1561 ```

1562 """

1563 ),

1564 ] = None,

1565 errors: Annotated[

1566 str | None,

1567 Doc(

1568 """

1569 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.

1570

1571 ---

1572

1573 The error handling mode.

1574 """

1575 ),

1576 ] = "strict",

1577 lazy: Annotated[

1578 bool | None,

1579 Doc(

1580 """

1581 For a CLI Argument representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),

1582 by default the file will not be created until you actually start writing to it.

1583 You can change this behaviour by setting this parameter.

1584 By default, it's set to `True` for writing and to `False` for reading.

1585

1586 **Example**

1587

1588 ```python

1589 @app.command()

1590 def main(config: Annotated[typer.FileText, typer.Argument(mode="a", lazy=False)]):

1591 config.write("This is a single line\\n")

1592 print("Config line written")

1593 ```

1594 """

1595 ),

1596 ] = None,

1597 atomic: Annotated[

1598 bool,

1599 Doc(

1600 """

1601 For a CLI Argument representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),

1602 you can ensure that all write instructions first go into a temporal file, and are only moved to the final destination after completing

1603 by setting `atomic` to `True`. This can be useful for files with potential concurrent access.

1604

1605 **Example**

1606

1607 ```python

1608 @app.command()

1609 def main(config: Annotated[typer.FileText, typer.Argument(mode="a", atomic=True)]):

1610 config.write("All the text")

1611 ```

1612 """

1613 ),

1614 ] = False,

1615 # Path

1616 exists: Annotated[

1617 bool,

1618 Doc(

1619 """

1620 When set to `True` for a [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/),

1621 additional validation is performed to check that the file or directory exists. If not, the value will be invalid.

1622

1623 **Example**

1624

1625 ```python

1626 from pathlib import Path

1627

1628 @app.command()

1629 def main(config: Annotated[Path, typer.Argument(exists=True)]):

1630 text = config.read_text()

1631 print(f"Config file contents: {text}")

1632 ```

1633 """

1634 ),

1635 ] = False,

1636 file_okay: Annotated[

1637 bool,

1638 Doc(

1639 """

1640 Determine whether or not a [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/)

1641 is allowed to refer to a file. When this is set to `False`, the application will raise a validation error when a path to a file is given.

1642

1643 **Example**

1644

1645 ```python

1646 from pathlib import Path

1647

1648 @app.command()

1649 def main(config: Annotated[Path, typer.Argument(exists=True, file_okay=False)]):

1650 print(f"Directory listing: {[x.name for x in config.iterdir()]}")

1651 ```

1652 """

1653 ),

1654 ] = True,

1655 dir_okay: Annotated[

1656 bool,

1657 Doc(

1658 """

1659 Determine whether or not a [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/)

1660 is allowed to refer to a directory. When this is set to `False`, the application will raise a validation error when a path to a directory is given.

1661

1662 **Example**

1663

1664 ```python

1665 from pathlib import Path

1666

1667 @app.command()

1668 def main(config: Annotated[Path, typer.Argument(exists=True, dir_okay=False)]):

1669 text = config.read_text()

1670 print(f"Config file contents: {text}")

1671 ```

1672 """

1673 ),

1674 ] = True,

1675 writable: Annotated[

1676 bool,

1677 Doc(

1678 """

1679 Whether or not to perform a writable check for this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).

1680

1681 **Example**

1682

1683 ```python

1684 from pathlib import Path

1685

1686 @app.command()

1687 def main(config: Annotated[Path, typer.Argument(writable=True)]):

1688 config.write_text("All the text")

1689 ```

1690 """

1691 ),

1692 ] = False,

1693 readable: Annotated[

1694 bool,

1695 Doc(

1696 """

1697 Whether or not to perform a readable check for this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).

1698

1699 **Example**

1700

1701 ```python

1702 from pathlib import Path

1703

1704 @app.command()

1705 def main(config: Annotated[Path, typer.Argument(readable=True)]):

1706 config.read_text("All the text")

1707 ```

1708 """

1709 ),

1710 ] = True,

1711 resolve_path: Annotated[

1712 bool,

1713 Doc(

1714 """

1715 Whether or not to fully resolve the path of this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/),

1716 meaning that the path becomes absolute and symlinks are resolved.

1717

1718 **Example**

1719

1720 ```python

1721 from pathlib import Path

1722

1723 @app.command()

1724 def main(config: Annotated[Path, typer.Argument(resolve_path=True)]):

1725 config.read_text("All the text")

1726 ```

1727 """

1728 ),

1729 ] = False,

1730 allow_dash: Annotated[

1731 bool,

1732 Doc(

1733 """

1734 When set to `True`, a single dash for this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/)

1735 would be a valid value, indicating standard streams. This is a more advanced use-case.

1736 """

1737 ),

1738 ] = False,

1739 path_type: Annotated[

1740 None | type[str] | type[bytes],

1741 Doc(

1742 """

1743 A string type that will be used to represent this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).

1744 The default is `None` which means the return value will be either bytes or unicode, depending on what makes most sense given the input data.

1745 This is a more advanced use-case.

1746 """

1747 ),

1748 ] = None,

1749 # Rich settings

1750 rich_help_panel: Annotated[

1751 str | None,

1752 Doc(

1753 """

1754 Set the panel name where you want this CLI Argument to be shown in the [help text](https://typer.tiangolo.com/tutorial/arguments/help).

1755

1756 **Example**

1757

1758 ```python

1759 @app.command()

1760 def main(

1761 name: Annotated[str, typer.Argument(help="Who to greet")],

1762 age: Annotated[str, typer.Option(help="Their age", rich_help_panel="Data")],

1763 ):

1764 print(f"Hello {name} of age {age}")

1765 ```

1766 """

1767 ),

1768 ] = None,

1769) -> Any:

1770 """

1771 A [CLI Argument](https://typer.tiangolo.com/tutorial/arguments) is a positional parameter to your command line application.

1772

1773 Often, CLI Arguments are required, meaning that users have to specify them. However, you can set them to be optional by defining a default value:

1774

1775 ## Example

1776

1777 ```python

1778 @app.command()

1779 def main(name: Annotated[str, typer.Argument()] = "World"):

1780 print(f"Hello {name}!")

1781 ```

1782

1783 Note how in this example, if `name` is not specified on the command line, the application will still execute normally and print "Hello World!".

1784 """

1785 return ArgumentInfo( 7 ctx1aebfcdg

1786 # Parameter

1787 default=default,

1788 # Arguments can only have one param declaration

1789 # it will be generated from the param name

1790 param_decls=None,

1791 callback=callback,

1792 metavar=metavar,

1793 expose_value=expose_value,

1794 is_eager=is_eager,

1795 envvar=envvar,

1796 shell_complete=shell_complete,

1797 autocompletion=autocompletion,

1798 default_factory=default_factory,

1799 # Custom type

1800 parser=parser,

1801 click_type=click_type,

1802 # TyperArgument

1803 show_default=show_default,

1804 show_choices=show_choices,

1805 show_envvar=show_envvar,

1806 help=help,

1807 hidden=hidden,

1808 # Choice

1809 case_sensitive=case_sensitive,

1810 # Numbers

1811 min=min,

1812 max=max,

1813 clamp=clamp,

1814 # DateTime

1815 formats=formats,

1816 # File

1817 mode=mode,

1818 encoding=encoding,

1819 errors=errors,

1820 lazy=lazy,

1821 atomic=atomic,

1822 # Path

1823 exists=exists,

1824 file_okay=file_okay,

1825 dir_okay=dir_okay,

1826 writable=writable,

1827 readable=readable,

1828 resolve_path=resolve_path,

1829 allow_dash=allow_dash,

1830 path_type=path_type,

1831 # Rich settings

1832 rich_help_panel=rich_help_panel,

1833 )

Coverage for typer / params.py: 100%

11 statements