Coverage for typer/params.py: 100%

1from collections.abc import Callable 7 ctx1abecfdg

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

4import click 7 ctx1abecfdg

5from annotated_doc import Doc 7 ctx1abecfdg

7from .models import ArgumentInfo, OptionInfo 7 ctx1abecfdg

9if TYPE_CHECKING: # pragma: no cover 7 ctx1abecfdg

10 import click.shell_completion

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

14@overload 7 ctx1abecfdg

15def Option( 7 ctx1abecfdg

16 # Parameter

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

18 *param_decls: str, 4 ctx1abcd

19 callback: Callable[..., Any] | None = None, 7 ctx1abecfdg

20 metavar: str | None = None, 7 ctx1abecfdg

21 expose_value: bool = True, 7 ctx1abecfdg

22 is_eager: bool = False, 7 ctx1abecfdg

23 envvar: str | list[str] | None = None, 7 ctx1abecfdg

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

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

26 shell_complete: Callable[ 4 ctx1abcd

27 [click.Context, click.Parameter, str], 4 ctx1abcd

28 list["click.shell_completion.CompletionItem"] | list[str], 4 ctx1abcd

29 ]

30 | None = None, 7 ctx1abecfdg

31 autocompletion: Callable[..., Any] | None = None, 7 ctx1abecfdg

32 default_factory: Callable[[], Any] | None = None, 7 ctx1abecfdg

33 # Custom type

34 parser: Callable[[str], Any] | None = None, 7 ctx1abecfdg

35 # Option

36 show_default: bool | str = True, 7 ctx1abecfdg

37 prompt: bool | str = False, 7 ctx1abecfdg

38 confirmation_prompt: bool = False, 7 ctx1abecfdg

39 prompt_required: bool = True, 7 ctx1abecfdg

40 hide_input: bool = False, 7 ctx1abecfdg

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

42 is_flag: bool | None = None, 7 ctx1abecfdg

43 flag_value: Any | None = None, 7 ctx1abecfdg

44 count: bool = False, 7 ctx1abecfdg

45 allow_from_autoenv: bool = True, 7 ctx1abecfdg

46 help: str | None = None, 7 ctx1abecfdg

47 hidden: bool = False, 7 ctx1abecfdg

48 show_choices: bool = True, 7 ctx1abecfdg

49 show_envvar: bool = True, 7 ctx1abecfdg

50 # Choice

51 case_sensitive: bool = True, 7 ctx1abecfdg

52 # Numbers

53 min: int | float | None = None, 7 ctx1abecfdg

54 max: int | float | None = None, 7 ctx1abecfdg

55 clamp: bool = False, 7 ctx1abecfdg

56 # DateTime

57 formats: list[str] | None = None, 7 ctx1abecfdg

58 # File

59 mode: str | None = None, 7 ctx1abecfdg

60 encoding: str | None = None, 7 ctx1abecfdg

61 errors: str | None = "strict", 7 ctx1abecfdg

62 lazy: bool | None = None, 7 ctx1abecfdg

63 atomic: bool = False, 7 ctx1abecfdg

64 # Path

65 exists: bool = False, 7 ctx1abecfdg

66 file_okay: bool = True, 7 ctx1abecfdg

67 dir_okay: bool = True, 7 ctx1abecfdg

68 writable: bool = False, 7 ctx1abecfdg

69 readable: bool = True, 7 ctx1abecfdg

70 resolve_path: bool = False, 7 ctx1abecfdg

71 allow_dash: bool = False, 7 ctx1abecfdg

72 path_type: None | type[str] | type[bytes] = None, 7 ctx1abecfdg

73 # Rich settings

74 rich_help_panel: str | None = None, 7 ctx1abecfdg

75) -> Any: ... 4 ctx1abcd

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

79@overload 7 ctx1abecfdg

80def Option( 7 ctx1abecfdg

81 # Parameter

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

83 *param_decls: str, 4 ctx1abcd

84 callback: Callable[..., Any] | None = None, 7 ctx1abecfdg

85 metavar: str | None = None, 7 ctx1abecfdg

86 expose_value: bool = True, 7 ctx1abecfdg

87 is_eager: bool = False, 7 ctx1abecfdg

88 envvar: str | list[str] | None = None, 7 ctx1abecfdg

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

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

91 shell_complete: Callable[ 4 ctx1abcd

92 [click.Context, click.Parameter, str], 4 ctx1abcd

93 list["click.shell_completion.CompletionItem"] | list[str], 4 ctx1abcd

94 ]

95 | None = None, 7 ctx1abecfdg

96 autocompletion: Callable[..., Any] | None = None, 7 ctx1abecfdg

97 default_factory: Callable[[], Any] | None = None, 7 ctx1abecfdg

98 # Custom type

99 click_type: click.ParamType | None = None, 7 ctx1abecfdg

100 # Option

101 show_default: bool | str = True, 7 ctx1abecfdg

102 prompt: bool | str = False, 7 ctx1abecfdg

103 confirmation_prompt: bool = False, 7 ctx1abecfdg

104 prompt_required: bool = True, 7 ctx1abecfdg

105 hide_input: bool = False, 7 ctx1abecfdg

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

107 is_flag: bool | None = None, 7 ctx1abecfdg

108 flag_value: Any | None = None, 7 ctx1abecfdg

109 count: bool = False, 7 ctx1abecfdg

110 allow_from_autoenv: bool = True, 7 ctx1abecfdg

111 help: str | None = None, 7 ctx1abecfdg

112 hidden: bool = False, 7 ctx1abecfdg

113 show_choices: bool = True, 7 ctx1abecfdg

114 show_envvar: bool = True, 7 ctx1abecfdg

115 # Choice

116 case_sensitive: bool = True, 7 ctx1abecfdg

117 # Numbers

118 min: int | float | None = None, 7 ctx1abecfdg

119 max: int | float | None = None, 7 ctx1abecfdg

120 clamp: bool = False, 7 ctx1abecfdg

121 # DateTime

122 formats: list[str] | None = None, 7 ctx1abecfdg

123 # File

124 mode: str | None = None, 7 ctx1abecfdg

125 encoding: str | None = None, 7 ctx1abecfdg

126 errors: str | None = "strict", 7 ctx1abecfdg

127 lazy: bool | None = None, 7 ctx1abecfdg

128 atomic: bool = False, 7 ctx1abecfdg

129 # Path

130 exists: bool = False, 7 ctx1abecfdg

131 file_okay: bool = True, 7 ctx1abecfdg

132 dir_okay: bool = True, 7 ctx1abecfdg

133 writable: bool = False, 7 ctx1abecfdg

134 readable: bool = True, 7 ctx1abecfdg

135 resolve_path: bool = False, 7 ctx1abecfdg

136 allow_dash: bool = False, 7 ctx1abecfdg

137 path_type: None | type[str] | type[bytes] = None, 7 ctx1abecfdg

138 # Rich settings

139 rich_help_panel: str | None = None, 7 ctx1abecfdg

140) -> Any: ... 4 ctx1abcd

141

142

143def Option( 7 ctx1abecfdg

144 # Parameter

145 default: Annotated[

146 Any | None,

147 Doc(

148 """

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

150

151 **Example**

152

153 ```python

154 @app.command()

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

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

157 ```

158

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

160 ```

161 @app.command()

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

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

164 ```

165

166 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.

167 """

168 ),

169 ] = ...,

170 *param_decls: Annotated[

171 str,

172 Doc(

173 """

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

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

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

177

178 **Example**

179

180 ```python

181 @app.command()

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

183 print(f"Hello {user_name}")

184 ```

185 """

186 ),

187 ],

188 callback: Annotated[

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

190 Doc(

191 """

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

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

194

195 **Example**

196

197 ```python

198 def name_callback(value: str):

199 if value != "Deadpool":

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

201 return value

202

203 @app.command()

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

205 print(f"Hello {name}")

206 ```

207 """

208 ),

209 ] = None,

210 metavar: Annotated[

211 str | None,

212 Doc(

213 """

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

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

216

217 **Example**

218

219 ```python

220 @app.command()

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

222 print(f"Hello {user}")

223 ```

224 """

225 ),

226 ] = None,

227 expose_value: Annotated[

228 bool,

229 Doc(

230 """

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

232

233 ---

234

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

236 """

237 ),

238 ] = True,

239 is_eager: Annotated[

240 bool,

241 Doc(

242 """

243 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.

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

245 """

246 ),

247 ] = False,

248 envvar: Annotated[

249 str | list[str] | None,

250 Doc(

251 """

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

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

254

255 **Example**

256

257 ```python

258 @app.command()

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

260 print(f"Hello {user}")

261 ```

262 """

263 ),

264 ] = None,

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

266 shell_complete: Annotated[

267 Callable[

268 [click.Context, click.Parameter, str],

269 list["click.shell_completion.CompletionItem"] | list[str],

270 ]

271 | None,

272 Doc(

273 """

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

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

276 """

277 ),

278 ] = None,

279 autocompletion: Annotated[

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

281 Doc(

282 """

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

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

285

286 **Example**

287

288 ```python

289 def complete():

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

291

292 @app.command()

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

294 print(f"Hello {name}")

295 ```

296 """

297 ),

298 ] = None,

299 default_factory: Annotated[

300 Callable[[], Any] | None,

301 Doc(

302 """

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

304

305 **Example**

306

307 ```python

308 def get_name():

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

310

311 @app.command()

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

313 print(f"Hello {name}")

314 ```

315 """

316 ),

317 ] = None,

318 # Custom type

319 parser: Annotated[

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

321 Doc(

322 """

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

324

325 **Example**

326

327 ```python

328 class CustomClass:

329 def __init__(self, value: str):

330 self.value = value

331

332 def __str__(self):

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

334

335 def my_parser(value: str):

336 return CustomClass(value * 2)

337

338 @app.command()

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

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

341 ```

342 """

343 ),

344 ] = None,

345 click_type: Annotated[

346 click.ParamType | None,

347 Doc(

348 """

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

350

351 **Example**

352

353 ```python

354 class MyClass:

355 def __init__(self, value: str):

356 self.value = value

357

358 def __str__(self):

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

360

361 class MyParser(click.ParamType):

362 name = "MyClass"

363

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

365 return MyClass(value * 3)

366

367 @app.command()

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

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

370 ```

371 """

372 ),

373 ] = None,

374 # Option

375 show_default: Annotated[

376 bool | str,

377 Doc(

378 """

379 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/).

380

381 **Example**

382

383 ```python

384 @app.command()

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

386 print(f"Hello {name}")

387 ```

388 """

389 ),

390 ] = True,

391 prompt: Annotated[

392 bool | str,

393 Doc(

394 """

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

396

397 **Example**

398

399 ```python

400 @app.command()

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

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

403 ```

404 """

405 ),

406 ] = False,

407 confirmation_prompt: Annotated[

408 bool,

409 Doc(

410 """

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

412

413 **Example**

414

415 ```python

416 @app.command()

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

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

419 ```

420 """

421 ),

422 ] = False,

423 prompt_required: Annotated[

424 bool,

425 Doc(

426 """

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

428

429 ---

430

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

432 """

433 ),

434 ] = True,

435 hide_input: Annotated[

436 bool,

437 Doc(

438 """

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

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

441

442 **Example**

443

444 ```python

445 @app.command()

446 def login(

447 name: str,

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

449 ):

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

451 ```

452 """

453 ),

454 ] = False,

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

456 is_flag: Annotated[

457 bool | None,

458 Doc(

459 """

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

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

462 """

463 ),

464 ] = None,

465 flag_value: Annotated[

466 Any | None,

467 Doc(

468 """

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

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

471 """

472 ),

473 ] = None,

474 count: Annotated[

475 bool,

476 Doc(

477 """

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

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

480

481 **Example**

482

483 ```python

484 @app.command()

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

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

487 ```

488 """

489 ),

490 ] = False,

491 allow_from_autoenv: Annotated[

492 bool,

493 Doc(

494 """

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

496

497 ---

498

499 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.

500 """

501 ),

502 ] = True,

503 help: Annotated[

504 str | None,

505 Doc(

506 """

507 Help text for this CLI Option.

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

509

510 **Example**

511

512 ```python

513 @app.command()

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

515 print(f"Hello {name}")

516 ```

517 """

518 ),

519 ] = None,

520 hidden: Annotated[

521 bool,

522 Doc(

523 """

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

525

526 **Example**

527

528 ```python

529 @app.command()

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

531 print(f"Hello {name}")

532 ```

533 """

534 ),

535 ] = False,

536 show_choices: Annotated[

537 bool,

538 Doc(

539 """

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

541

542 ---

543

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

545 """

546 ),

547 ] = True,

548 show_envvar: Annotated[

549 bool,

550 Doc(

551 """

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

553

554 **Example**

555

556 ```python

557 @app.command()

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

559 print(f"Hello {user}")

560 ```

561 """

562 ),

563 ] = True,

564 # Choice

565 case_sensitive: Annotated[

566 bool,

567 Doc(

568 """

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

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

571

572 **Example**

573

574 ```python

575 from enum import Enum

576

577 class NeuralNetwork(str, Enum):

578 simple = "simple"

579 conv = "conv"

580 lstm = "lstm"

581

582 @app.command()

583 def main(

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

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

586 ```

587

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

589 """

590 ),

591 ] = True,

592 # Numbers

593 min: Annotated[

594 int | float | None,

595 Doc(

596 """

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

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

599

600 **Example**

601

602 ```python

603 @app.command()

604 def main(

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

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

607 ):

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

609 ```

610

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

612 """

613 ),

614 ] = None,

615 max: Annotated[

616 int | float | None,

617 Doc(

618 """

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

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

621

622 **Example**

623

624 ```python

625 @app.command()

626 def main(

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

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

629 ):

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

631 ```

632

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

634 """

635 ),

636 ] = None,

637 clamp: Annotated[

638 bool,

639 Doc(

640 """

641 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`,

642 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`.

643

644 **Example**

645

646 ```python

647 @app.command()

648 def main(

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

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

651 ):

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

653 ```

654

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

656 """

657 ),

658 ] = False,

659 # DateTime

660 formats: Annotated[

661 list[str] | None,

662 Doc(

663 """

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

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

666

667 **Example**

668

669 ```python

670 from datetime import datetime

671

672 @app.command()

673 def main(

674 birthday: Annotated[

675 datetime,

676 typer.Option(

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

678 ),

679 ],

680 ):

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

682 ```

683 """

684 ),

685 ] = None,

686 # File

687 mode: Annotated[

688 str | None,

689 Doc(

690 """

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

692 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).

693

694 **Example**

695

696 ```python

697 @app.command()

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

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

700 print("Config line written")

701 ```

702 """

703 ),

704 ] = None,

705 encoding: Annotated[

706 str | None,

707 Doc(

708 """

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

710

711 **Example**

712

713 ```python

714 @app.command()

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

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

717 ```

718 """

719 ),

720 ] = None,

721 errors: Annotated[

722 str | None,

723 Doc(

724 """

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

726

727 ---

728

729 The error handling mode.

730 """

731 ),

732 ] = "strict",

733 lazy: Annotated[

734 bool | None,

735 Doc(

736 """

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

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

739 You can change this behaviour by setting this parameter.

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

741

742 **Example**

743

744 ```python

745 @app.command()

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

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

748 print("Config line written")

749 ```

750 """

751 ),

752 ] = None,

753 atomic: Annotated[

754 bool,

755 Doc(

756 """

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

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

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

760

761 **Example**

762

763 ```python

764 @app.command()

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

766 config.write("All the text")

767 ```

768 """

769 ),

770 ] = False,

771 # Path

772 exists: Annotated[

773 bool,

774 Doc(

775 """

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

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

778

779 **Example**

780

781 ```python

782 from pathlib import Path

783

784 @app.command()

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

786 text = config.read_text()

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

788 ```

789 """

790 ),

791 ] = False,

792 file_okay: Annotated[

793 bool,

794 Doc(

795 """

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

797 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.

798

799 **Example**

800

801 ```python

802 from pathlib import Path

803

804 @app.command()

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

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

807 ```

808 """

809 ),

810 ] = True,

811 dir_okay: Annotated[

812 bool,

813 Doc(

814 """

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

816 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.

817

818 **Example**

819

820 ```python

821 from pathlib import Path

822

823 @app.command()

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

825 text = config.read_text()

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

827 ```

828 """

829 ),

830 ] = True,

831 writable: Annotated[

832 bool,

833 Doc(

834 """

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

836

837 **Example**

838

839 ```python

840 from pathlib import Path

841

842 @app.command()

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

844 config.write_text("All the text")

845 ```

846 """

847 ),

848 ] = False,

849 readable: Annotated[

850 bool,

851 Doc(

852 """

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

854

855 **Example**

856

857 ```python

858 from pathlib import Path

859

860 @app.command()

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

862 config.read_text("All the text")

863 ```

864 """

865 ),

866 ] = True,

867 resolve_path: Annotated[

868 bool,

869 Doc(

870 """

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

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

873

874 **Example**

875

876 ```python

877 from pathlib import Path

878

879 @app.command()

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

881 config.read_text("All the text")

882 ```

883 """

884 ),

885 ] = False,

886 allow_dash: Annotated[

887 bool,

888 Doc(

889 """

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

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

892 """

893 ),

894 ] = False,

895 path_type: Annotated[

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

897 Doc(

898 """

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

900 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.

901 This is a more advanced use-case.

902 """

903 ),

904 ] = None,

905 # Rich settings

906 rich_help_panel: Annotated[

907 str | None,

908 Doc(

909 """

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

911

912 **Example**

913

914 ```python

915 @app.command()

916 def main(

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

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

919 ):

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

921 ```

922 """

923 ),

924 ] = None,

925) -> Any:

926 """

927 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`.

928

929 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`

930 and omitting a default value.

931

932 ## Example

933

934 ```python

935 @app.command()

936 def register(

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

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

939 ):

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

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

942 ```

943

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

945 """

946 return OptionInfo( 7 ctx1abecfdg

947 # Parameter

948 default=default,

949 param_decls=param_decls,

950 callback=callback,

951 metavar=metavar,

952 expose_value=expose_value,

953 is_eager=is_eager,

954 envvar=envvar,

955 shell_complete=shell_complete,

956 autocompletion=autocompletion,

957 default_factory=default_factory,

958 # Custom type

959 parser=parser,

960 click_type=click_type,

961 # Option

962 show_default=show_default,

963 prompt=prompt,

964 confirmation_prompt=confirmation_prompt,

965 prompt_required=prompt_required,

966 hide_input=hide_input,

967 is_flag=is_flag,

968 flag_value=flag_value,

969 count=count,

970 allow_from_autoenv=allow_from_autoenv,

971 help=help,

972 hidden=hidden,

973 show_choices=show_choices,

974 show_envvar=show_envvar,

975 # Choice

976 case_sensitive=case_sensitive,

977 # Numbers

978 min=min,

979 max=max,

980 clamp=clamp,

981 # DateTime

982 formats=formats,

983 # File

984 mode=mode,

985 encoding=encoding,

986 errors=errors,

987 lazy=lazy,

988 atomic=atomic,

989 # Path

990 exists=exists,

991 file_okay=file_okay,

992 dir_okay=dir_okay,

993 writable=writable,

994 readable=readable,

995 resolve_path=resolve_path,

996 allow_dash=allow_dash,

997 path_type=path_type,

998 # Rich settings

999 rich_help_panel=rich_help_panel,

1000 )

1001

1002

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

1004@overload 7 ctx1abecfdg

1005def Argument( 7 ctx1abecfdg

1006 # Parameter

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

1008 *,

1009 callback: Callable[..., Any] | None = None, 7 ctx1abecfdg

1010 metavar: str | None = None, 7 ctx1abecfdg

1011 expose_value: bool = True, 7 ctx1abecfdg

1012 is_eager: bool = False, 7 ctx1abecfdg

1013 envvar: str | list[str] | None = None, 7 ctx1abecfdg

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

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

1016 shell_complete: Callable[ 4 ctx1abcd

1017 [click.Context, click.Parameter, str], 4 ctx1abcd

1018 list["click.shell_completion.CompletionItem"] | list[str], 4 ctx1abcd

1019 ]

1020 | None = None, 7 ctx1abecfdg

1021 autocompletion: Callable[..., Any] | None = None, 7 ctx1abecfdg

1022 default_factory: Callable[[], Any] | None = None, 7 ctx1abecfdg

1023 # Custom type

1024 parser: Callable[[str], Any] | None = None, 7 ctx1abecfdg

1025 # TyperArgument

1026 show_default: bool | str = True, 7 ctx1abecfdg

1027 show_choices: bool = True, 7 ctx1abecfdg

1028 show_envvar: bool = True, 7 ctx1abecfdg

1029 help: str | None = None, 7 ctx1abecfdg

1030 hidden: bool = False, 7 ctx1abecfdg

1031 # Choice

1032 case_sensitive: bool = True, 7 ctx1abecfdg

1033 # Numbers

1034 min: int | float | None = None, 7 ctx1abecfdg

1035 max: int | float | None = None, 7 ctx1abecfdg

1036 clamp: bool = False, 7 ctx1abecfdg

1037 # DateTime

1038 formats: list[str] | None = None, 7 ctx1abecfdg

1039 # File

1040 mode: str | None = None, 7 ctx1abecfdg

1041 encoding: str | None = None, 7 ctx1abecfdg

1042 errors: str | None = "strict", 7 ctx1abecfdg

1043 lazy: bool | None = None, 7 ctx1abecfdg

1044 atomic: bool = False, 7 ctx1abecfdg

1045 # Path

1046 exists: bool = False, 7 ctx1abecfdg

1047 file_okay: bool = True, 7 ctx1abecfdg

1048 dir_okay: bool = True, 7 ctx1abecfdg

1049 writable: bool = False, 7 ctx1abecfdg

1050 readable: bool = True, 7 ctx1abecfdg

1051 resolve_path: bool = False, 7 ctx1abecfdg

1052 allow_dash: bool = False, 7 ctx1abecfdg

1053 path_type: None | type[str] | type[bytes] = None, 7 ctx1abecfdg

1054 # Rich settings

1055 rich_help_panel: str | None = None, 7 ctx1abecfdg

1056) -> Any: ... 4 ctx1abcd

1057

1058

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

1060@overload 7 ctx1abecfdg

1061def Argument( 7 ctx1abecfdg

1062 # Parameter

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

1064 *,

1065 callback: Callable[..., Any] | None = None, 7 ctx1abecfdg

1066 metavar: str | None = None, 7 ctx1abecfdg

1067 expose_value: bool = True, 7 ctx1abecfdg

1068 is_eager: bool = False, 7 ctx1abecfdg

1069 envvar: str | list[str] | None = None, 7 ctx1abecfdg

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

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

1072 shell_complete: Callable[ 4 ctx1abcd

1073 [click.Context, click.Parameter, str], 4 ctx1abcd

1074 list["click.shell_completion.CompletionItem"] | list[str], 4 ctx1abcd

1075 ]

1076 | None = None, 7 ctx1abecfdg

1077 autocompletion: Callable[..., Any] | None = None, 7 ctx1abecfdg

1078 default_factory: Callable[[], Any] | None = None, 7 ctx1abecfdg

1079 # Custom type

1080 click_type: click.ParamType | None = None, 7 ctx1abecfdg

1081 # TyperArgument

1082 show_default: bool | str = True, 7 ctx1abecfdg

1083 show_choices: bool = True, 7 ctx1abecfdg

1084 show_envvar: bool = True, 7 ctx1abecfdg

1085 help: str | None = None, 7 ctx1abecfdg

1086 hidden: bool = False, 7 ctx1abecfdg

1087 # Choice

1088 case_sensitive: bool = True, 7 ctx1abecfdg

1089 # Numbers

1090 min: int | float | None = None, 7 ctx1abecfdg

1091 max: int | float | None = None, 7 ctx1abecfdg

1092 clamp: bool = False, 7 ctx1abecfdg

1093 # DateTime

1094 formats: list[str] | None = None, 7 ctx1abecfdg

1095 # File

1096 mode: str | None = None, 7 ctx1abecfdg

1097 encoding: str | None = None, 7 ctx1abecfdg

1098 errors: str | None = "strict", 7 ctx1abecfdg

1099 lazy: bool | None = None, 7 ctx1abecfdg

1100 atomic: bool = False, 7 ctx1abecfdg

1101 # Path

1102 exists: bool = False, 7 ctx1abecfdg

1103 file_okay: bool = True, 7 ctx1abecfdg

1104 dir_okay: bool = True, 7 ctx1abecfdg

1105 writable: bool = False, 7 ctx1abecfdg

1106 readable: bool = True, 7 ctx1abecfdg

1107 resolve_path: bool = False, 7 ctx1abecfdg

1108 allow_dash: bool = False, 7 ctx1abecfdg

1109 path_type: None | type[str] | type[bytes] = None, 7 ctx1abecfdg

1110 # Rich settings

1111 rich_help_panel: str | None = None, 7 ctx1abecfdg

1112) -> Any: ... 4 ctx1abcd

1113

1114

1115def Argument( 7 ctx1abecfdg

1116 # Parameter

1117 default: Annotated[

1118 Any | None,

1119 Doc(

1120 """

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

1122

1123 **Example**

1124

1125 ```python

1126 @app.command()

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

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

1129 ```

1130

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

1132 ```python

1133 @app.command()

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

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

1136 ```

1137 """

1138 ),

1139 ] = ...,

1140 *,

1141 callback: Annotated[

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

1143 Doc(

1144 """

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

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

1147

1148 **Example**

1149

1150 ```python

1151 def name_callback(value: str):

1152 if value != "Deadpool":

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

1154 return value

1155

1156 @app.command()

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

1158 print(f"Hello {name}")

1159 ```

1160 """

1161 ),

1162 ] = None,

1163 metavar: Annotated[

1164 str | None,

1165 Doc(

1166 """

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

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

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

1170

1171 **Example**

1172

1173 ```python

1174 @app.command()

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

1176 print(f"Hello {name}")

1177 ```

1178 """

1179 ),

1180 ] = None,

1181 expose_value: Annotated[

1182 bool,

1183 Doc(

1184 """

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

1186

1187 ---

1188

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

1190 """

1191 ),

1192 ] = True,

1193 is_eager: Annotated[

1194 bool,

1195 Doc(

1196 """

1197 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.

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

1199 """

1200 ),

1201 ] = False,

1202 envvar: Annotated[

1203 str | list[str] | None,

1204 Doc(

1205 """

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

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

1208

1209 **Example**

1210

1211 ```python

1212 @app.command()

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

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

1215 ```

1216 """

1217 ),

1218 ] = None,

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

1220 shell_complete: Annotated[

1221 Callable[

1222 [click.Context, click.Parameter, str],

1223 list["click.shell_completion.CompletionItem"] | list[str],

1224 ]

1225 | None,

1226 Doc(

1227 """

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

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

1230 """

1231 ),

1232 ] = None,

1233 autocompletion: Annotated[

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

1235 Doc(

1236 """

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

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

1239

1240 **Example**

1241

1242 ```python

1243 def complete():

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

1245

1246 @app.command()

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

1248 print(f"Hello {name}")

1249 ```

1250 """

1251 ),

1252 ] = None,

1253 default_factory: Annotated[

1254 Callable[[], Any] | None,

1255 Doc(

1256 """

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

1258

1259 **Example**

1260

1261 ```python

1262 def get_name():

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

1264

1265 @app.command()

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

1267 print(f"Hello {name}")

1268 ```

1269 """

1270 ),

1271 ] = None,

1272 # Custom type

1273 parser: Annotated[

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

1275 Doc(

1276 """

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

1278

1279 **Example**

1280

1281 ```python

1282 class CustomClass:

1283 def __init__(self, value: str):

1284 self.value = value

1285

1286 def __str__(self):

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

1288

1289 def my_parser(value: str):

1290 return CustomClass(value * 2)

1291

1292 @app.command()

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

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

1295 ```

1296 """

1297 ),

1298 ] = None,

1299 click_type: Annotated[

1300 click.ParamType | None,

1301 Doc(

1302 """

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

1304

1305 **Example**

1306

1307 ```python

1308 class MyClass:

1309 def __init__(self, value: str):

1310 self.value = value

1311

1312 def __str__(self):

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

1314

1315 class MyParser(click.ParamType):

1316 name = "MyClass"

1317

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

1319 return MyClass(value * 3)

1320

1321 @app.command()

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

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

1324 ```

1325 """

1326 ),

1327 ] = None,

1328 # TyperArgument

1329 show_default: Annotated[

1330 bool | str,

1331 Doc(

1332 """

1333 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/).

1334

1335 **Example**

1336

1337 ```python

1338 @app.command()

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

1340 print(f"Hello {name}")

1341 ```

1342 """

1343 ),

1344 ] = True,

1345 show_choices: Annotated[

1346 bool,

1347 Doc(

1348 """

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

1350

1351 ---

1352

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

1354 """

1355 ),

1356 ] = True,

1357 show_envvar: Annotated[

1358 bool,

1359 Doc(

1360 """

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

1362

1363 **Example**

1364

1365 ```python

1366 @app.command()

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

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

1369 ```

1370 """

1371 ),

1372 ] = True,

1373 help: Annotated[

1374 str | None,

1375 Doc(

1376 """

1377 Help text for this CLI Argument.

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

1379

1380 **Example**

1381

1382 ```python

1383 @app.command()

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

1385 print(f"Hello {name}")

1386 ```

1387 """

1388 ),

1389 ] = None,

1390 hidden: Annotated[

1391 bool,

1392 Doc(

1393 """

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

1395

1396 **Example**

1397

1398 ```python

1399 @app.command()

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

1401 print(f"Hello {name}")

1402 ```

1403 """

1404 ),

1405 ] = False,

1406 # Choice

1407 case_sensitive: Annotated[

1408 bool,

1409 Doc(

1410 """

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

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

1413

1414 **Example**

1415

1416 ```python

1417 from enum import Enum

1418

1419 class NeuralNetwork(str, Enum):

1420 simple = "simple"

1421 conv = "conv"

1422 lstm = "lstm"

1423

1424 @app.command()

1425 def main(

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

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

1428 ```

1429

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

1431 """

1432 ),

1433 ] = True,

1434 # Numbers

1435 min: Annotated[

1436 int | float | None,

1437 Doc(

1438 """

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

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

1441

1442 **Example**

1443

1444 ```python

1445 @app.command()

1446 def main(

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

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

1449 ):

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

1451 ```

1452

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

1454 """

1455 ),

1456 ] = None,

1457 max: Annotated[

1458 int | float | None,

1459 Doc(

1460 """

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

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

1463

1464 **Example**

1465

1466 ```python

1467 @app.command()

1468 def main(

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

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

1471 ):

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

1473 ```

1474

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

1476 """

1477 ),

1478 ] = None,

1479 clamp: Annotated[

1480 bool,

1481 Doc(

1482 """

1483 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`,

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

1485

1486 **Example**

1487

1488 ```python

1489 @app.command()

1490 def main(

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

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

1493 ):

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

1495 ```

1496

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

1498 """

1499 ),

1500 ] = False,

1501 # DateTime

1502 formats: Annotated[

1503 list[str] | None,

1504 Doc(

1505 """

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

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

1508

1509 **Example**

1510

1511 ```python

1512 from datetime import datetime

1513

1514 @app.command()

1515 def main(

1516 birthday: Annotated[

1517 datetime,

1518 typer.Argument(

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

1520 ),

1521 ],

1522 ):

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

1524 ```

1525 """

1526 ),

1527 ] = None,

1528 # File

1529 mode: Annotated[

1530 str | None,

1531 Doc(

1532 """

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

1534 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).

1535

1536 **Example**

1537

1538 ```python

1539 @app.command()

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

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

1542 print("Config line written")

1543 ```

1544 """

1545 ),

1546 ] = None,

1547 encoding: Annotated[

1548 str | None,

1549 Doc(

1550 """

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

1552

1553 **Example**

1554

1555 ```python

1556 @app.command()

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

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

1559 ```

1560 """

1561 ),

1562 ] = None,

1563 errors: Annotated[

1564 str | None,

1565 Doc(

1566 """

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

1568

1569 ---

1570

1571 The error handling mode.

1572 """

1573 ),

1574 ] = "strict",

1575 lazy: Annotated[

1576 bool | None,

1577 Doc(

1578 """

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

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

1581 You can change this behaviour by setting this parameter.

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

1583

1584 **Example**

1585

1586 ```python

1587 @app.command()

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

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

1590 print("Config line written")

1591 ```

1592 """

1593 ),

1594 ] = None,

1595 atomic: Annotated[

1596 bool,

1597 Doc(

1598 """

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

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

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

1602

1603 **Example**

1604

1605 ```python

1606 @app.command()

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

1608 config.write("All the text")

1609 ```

1610 """

1611 ),

1612 ] = False,

1613 # Path

1614 exists: Annotated[

1615 bool,

1616 Doc(

1617 """

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

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

1620

1621 **Example**

1622

1623 ```python

1624 from pathlib import Path

1625

1626 @app.command()

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

1628 text = config.read_text()

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

1630 ```

1631 """

1632 ),

1633 ] = False,

1634 file_okay: Annotated[

1635 bool,

1636 Doc(

1637 """

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

1639 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.

1640

1641 **Example**

1642

1643 ```python

1644 from pathlib import Path

1645

1646 @app.command()

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

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

1649 ```

1650 """

1651 ),

1652 ] = True,

1653 dir_okay: Annotated[

1654 bool,

1655 Doc(

1656 """

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

1658 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.

1659

1660 **Example**

1661

1662 ```python

1663 from pathlib import Path

1664

1665 @app.command()

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

1667 text = config.read_text()

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

1669 ```

1670 """

1671 ),

1672 ] = True,

1673 writable: Annotated[

1674 bool,

1675 Doc(

1676 """

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

1678

1679 **Example**

1680

1681 ```python

1682 from pathlib import Path

1683

1684 @app.command()

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

1686 config.write_text("All the text")

1687 ```

1688 """

1689 ),

1690 ] = False,

1691 readable: Annotated[

1692 bool,

1693 Doc(

1694 """

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

1696

1697 **Example**

1698

1699 ```python

1700 from pathlib import Path

1701

1702 @app.command()

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

1704 config.read_text("All the text")

1705 ```

1706 """

1707 ),

1708 ] = True,

1709 resolve_path: Annotated[

1710 bool,

1711 Doc(

1712 """

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

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

1715

1716 **Example**

1717

1718 ```python

1719 from pathlib import Path

1720

1721 @app.command()

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

1723 config.read_text("All the text")

1724 ```

1725 """

1726 ),

1727 ] = False,

1728 allow_dash: Annotated[

1729 bool,

1730 Doc(

1731 """

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

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

1734 """

1735 ),

1736 ] = False,

1737 path_type: Annotated[

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

1739 Doc(

1740 """

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

1742 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.

1743 This is a more advanced use-case.

1744 """

1745 ),

1746 ] = None,

1747 # Rich settings

1748 rich_help_panel: Annotated[

1749 str | None,

1750 Doc(

1751 """

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

1753

1754 **Example**

1755

1756 ```python

1757 @app.command()

1758 def main(

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

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

1761 ):

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

1763 ```

1764 """

1765 ),

1766 ] = None,

1767) -> Any:

1768 """

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

1770

1771 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:

1772

1773 ## Example

1774

1775 ```python

1776 @app.command()

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

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

1779 ```

1780

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

1782 """

1783 return ArgumentInfo( 7 ctx1abecfdg

1784 # Parameter

1785 default=default,

1786 # Arguments can only have one param declaration

1787 # it will be generated from the param name

1788 param_decls=None,

1789 callback=callback,

1790 metavar=metavar,

1791 expose_value=expose_value,

1792 is_eager=is_eager,

1793 envvar=envvar,

1794 shell_complete=shell_complete,

1795 autocompletion=autocompletion,

1796 default_factory=default_factory,

1797 # Custom type

1798 parser=parser,

1799 click_type=click_type,

1800 # TyperArgument

1801 show_default=show_default,

1802 show_choices=show_choices,

1803 show_envvar=show_envvar,

1804 help=help,

1805 hidden=hidden,

1806 # Choice

1807 case_sensitive=case_sensitive,

1808 # Numbers

1809 min=min,

1810 max=max,

1811 clamp=clamp,

1812 # DateTime

1813 formats=formats,

1814 # File

1815 mode=mode,

1816 encoding=encoding,

1817 errors=errors,

1818 lazy=lazy,

1819 atomic=atomic,

1820 # Path

1821 exists=exists,

1822 file_okay=file_okay,

1823 dir_okay=dir_okay,

1824 writable=writable,

1825 readable=readable,

1826 resolve_path=resolve_path,

1827 allow_dash=allow_dash,

1828 path_type=path_type,

1829 # Rich settings

1830 rich_help_panel=rich_help_panel,

1831 )

Coverage for typer / params.py: 100%

9 statements