Coverage for typer / params.py: 100%
10 statements
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
« prev ^ index » next coverage.py v7.13.1, created at 2026-11-18 11:12 +0000
1from collections.abc import Callable 1abcdefghij
2from typing import TYPE_CHECKING, Annotated, Any 1abcdefghij
4from annotated_doc import Doc 1abcdefghij
6from . import _click 1abcdefghij
7from ._click.shell_completion import CompletionItem 1abcdefghij
8from .models import ArgumentInfo, OptionInfo 1abcdefghij
10if TYPE_CHECKING: # pragma: no cover 1abcdefghij
11 pass
14def Option( 1abcdefghij
15 # Parameter
16 default: Annotated[
17 Any | None,
18 Doc(
19 """
20 Usually, [CLI options](https://typer.tiangolo.com/tutorial/options/) are optional and have a default value, passed on like this:
22 **Example**
24 ```python
25 @app.command()
26 def main(network: str = typer.Option("CNN")):
27 print(f"Training neural network of type: {network}")
28 ```
30 Note that this usage is deprecated, and we recommend to use `Annotated` instead:
31 ```
32 @app.command()
33 def main(network: Annotated[str, typer.Option()] = "CNN"):
34 print(f"Hello {name}!")
35 ```
37 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.
38 """
39 ),
40 ] = ...,
41 *param_decls: Annotated[
42 str,
43 Doc(
44 """
45 Positional argument that defines how users can call this option on the command line. This may be one or multiple aliases, all strings.
46 If not defined, Typer will automatically use the function parameter as default name.
47 See [the tutorial about CLI Option Names](https://typer.tiangolo.com/tutorial/options/name/) for more details.
49 **Example**
51 ```python
52 @app.command()
53 def main(user_name: Annotated[str, typer.Option("--user", "-u", "-x")]):
54 print(f"Hello {user_name}")
55 ```
56 """
57 ),
58 ],
59 callback: Annotated[
60 Callable[..., Any] | None,
61 Doc(
62 """
63 Add a callback to this CLI Option, to execute additional logic after its value was received from the terminal.
64 See [the tutorial about callbacks](https://typer.tiangolo.com/tutorial/options/callback-and-context/) for more details.
66 **Example**
68 ```python
69 def name_callback(value: str):
70 if value != "Deadpool":
71 raise typer.BadParameter("Only Deadpool is allowed")
72 return value
74 @app.command()
75 def main(name: Annotated[str, typer.Option(callback=name_callback)]):
76 print(f"Hello {name}")
77 ```
78 """
79 ),
80 ] = None,
81 metavar: Annotated[
82 str | None,
83 Doc(
84 """
85 Customize the name displayed in the [help text](https://typer.tiangolo.com/tutorial/options/help/) to represent this CLI option.
86 Note that this doesn't influence the way the option must be called.
88 **Example**
90 ```python
91 @app.command()
92 def main(user: Annotated[str, typer.Option(metavar="User name")]):
93 print(f"Hello {user}")
94 ```
95 """
96 ),
97 ] = None,
98 expose_value: Annotated[
99 bool,
100 Doc(
101 """
102 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
104 ---
106 If this is `True` then the value is passed onwards to the command callback and stored on the context, otherwise it’s skipped.
107 """
108 ),
109 ] = True,
110 is_eager: Annotated[
111 bool,
112 Doc(
113 """
114 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.
115 For more information and an extended example, see the documentation [here](https://typer.tiangolo.com/tutorial/options/version/#fix-with-is_eager).
116 """
117 ),
118 ] = False,
119 envvar: Annotated[
120 str | list[str] | None,
121 Doc(
122 """
123 Configure a CLI Option to read its value from an environment variable if it is not provided in the command line.
124 For more information, see the [documentation on Environment Variables](https://typer.tiangolo.com/tutorial/arguments/envvar/).
126 **Example**
128 ```python
129 @app.command()
130 def main(user: Annotated[str, typer.Option(envvar="ME")]):
131 print(f"Hello {user}")
132 ```
133 """
134 ),
135 ] = None,
136 # TODO: Remove shell_complete in a future version (after 0.16.0)
137 shell_complete: Annotated[
138 Callable[
139 [_click.Context, _click.Parameter, str],
140 list["CompletionItem"] | list[str],
141 ]
142 | None,
143 Doc(
144 """
145 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
146 It is however not fully functional, and will likely be removed in future versions.
147 """
148 ),
149 ] = None,
150 autocompletion: Annotated[
151 Callable[..., Any] | None,
152 Doc(
153 """
154 Provide a custom function that helps to autocomplete the values of this CLI Option.
155 See [the tutorial on parameter autocompletion](https://typer.tiangolo.com/tutorial/options-autocompletion) for more details.
157 **Example**
159 ```python
160 def complete():
161 return ["Me", "Myself", "I"]
163 @app.command()
164 def main(name: Annotated[str, typer.Option(autocompletion=complete)]):
165 print(f"Hello {name}")
166 ```
167 """
168 ),
169 ] = None,
170 default_factory: Annotated[
171 Callable[[], Any] | None,
172 Doc(
173 """
174 Provide a custom function that dynamically generates a [default](https://typer.tiangolo.com/tutorial/arguments/default) for this CLI Option.
176 **Example**
178 ```python
179 def get_name():
180 return random.choice(["Me", "Myself", "I"])
182 @app.command()
183 def main(name: Annotated[str, typer.Option(default_factory=get_name)]):
184 print(f"Hello {name}")
185 ```
186 """
187 ),
188 ] = None,
189 # Custom type
190 parser: Annotated[
191 Callable[[str], Any] | None,
192 Doc(
193 """
194 Use your own custom types in Typer applications by defining a `parser` function that parses input into your own types:
196 **Example**
198 ```python
199 class CustomClass:
200 def __init__(self, value: str):
201 self.value = value
203 def __str__(self):
204 return f"<CustomClass: value={self.value}>"
206 def my_parser(value: str):
207 return CustomClass(value * 2)
209 @app.command()
210 def main(opt: Annotated[CustomClass, typer.Option(parser=my_parser)] = "Foo"):
211 print(f"--opt is {opt}")
212 ```
213 """
214 ),
215 ] = None,
216 # Option
217 show_default: Annotated[
218 bool | str,
219 Doc(
220 """
221 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/).
223 **Example**
225 ```python
226 @app.command()
227 def main(name: Annotated[str, typer.Option(show_default=False)] = "Rick"):
228 print(f"Hello {name}")
229 ```
230 """
231 ),
232 ] = True,
233 prompt: Annotated[
234 bool | str,
235 Doc(
236 """
237 When set to `True`, a prompt will appear to ask for the value of this CLI Option if it was not provided:
239 **Example**
241 ```python
242 @app.command()
243 def main(name: str, lastname: Annotated[str, typer.Option(prompt=True)]):
244 print(f"Hello {name} {lastname}")
245 ```
246 """
247 ),
248 ] = False,
249 confirmation_prompt: Annotated[
250 bool,
251 Doc(
252 """
253 When set to `True`, a user will need to type a prompted value twice (may be useful for passwords etc.).
255 **Example**
257 ```python
258 @app.command()
259 def main(project: Annotated[str, typer.Option(prompt=True, confirmation_prompt=True)]):
260 print(f"Deleting project {project}")
261 ```
262 """
263 ),
264 ] = False,
265 prompt_required: Annotated[
266 bool,
267 Doc(
268 """
269 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
271 ---
273 If this is `False` then a prompt is only shown if the option's flag is given without a value.
274 """
275 ),
276 ] = True,
277 hide_input: Annotated[
278 bool,
279 Doc(
280 """
281 When you've configured a prompt, for instance for [querying a password](https://typer.tiangolo.com/tutorial/options/password/),
282 don't show anything on the screen while the user is typing the value.
284 **Example**
286 ```python
287 @app.command()
288 def login(
289 name: str,
290 password: Annotated[str, typer.Option(prompt=True, hide_input=True)],
291 ):
292 print(f"Hello {name}. Doing something very secure with password.")
293 ```
294 """
295 ),
296 ] = False,
297 # TODO: remove is_flag and flag_value in a future release
298 is_flag: Annotated[
299 bool | None,
300 Doc(
301 """
302 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
303 It is however not fully functional, and will likely be removed in future versions.
304 """
305 ),
306 ] = None,
307 flag_value: Annotated[
308 Any | None,
309 Doc(
310 """
311 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
312 It is however not fully functional, and will likely be removed in future versions.
313 """
314 ),
315 ] = None,
316 count: Annotated[
317 bool,
318 Doc(
319 """
320 Make a CLI Option work as a [counter](https://typer.tiangolo.com/tutorial/parameter-types/number/#counter-cli-options).
321 The CLI option will have the `int` value representing the number of times the option was used on the command line.
323 **Example**
325 ```python
326 @app.command()
327 def main(verbose: Annotated[int, typer.Option("--verbose", "-v", count=True)] = 0):
328 print(f"Verbose level is {verbose}")
329 ```
330 """
331 ),
332 ] = False,
333 allow_from_autoenv: Annotated[
334 bool,
335 Doc(
336 """
337 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
339 ---
341 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.
342 """
343 ),
344 ] = True,
345 help: Annotated[
346 str | None,
347 Doc(
348 """
349 Help text for this CLI Option.
350 See [the tutorial about CLI Options with help](https://typer.tiangolo.com/tutorial/options/help/) for more dedails.
352 **Example**
354 ```python
355 @app.command()
356 def greet(name: Annotated[str, typer.Option(help="Person to greet")] = "Deadpool"):
357 print(f"Hello {name}")
358 ```
359 """
360 ),
361 ] = None,
362 hidden: Annotated[
363 bool,
364 Doc(
365 """
366 Hide this CLI Option from [help outputs](https://typer.tiangolo.com/tutorial/options/help). `False` by default.
368 **Example**
370 ```python
371 @app.command()
372 def greet(name: Annotated[str, typer.Option(hidden=True)] = "Deadpool"):
373 print(f"Hello {name}")
374 ```
375 """
376 ),
377 ] = False,
378 show_choices: Annotated[
379 bool,
380 Doc(
381 """
382 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
384 ---
386 When set to `False`, this suppresses choices from being displayed inline when `prompt` is used.
387 """
388 ),
389 ] = True,
390 show_envvar: Annotated[
391 bool,
392 Doc(
393 """
394 When an ["envvar"](https://typer.tiangolo.com/tutorial/arguments/envvar) is defined, prevent it from showing up in the help text:
396 **Example**
398 ```python
399 @app.command()
400 def main(user: Annotated[str, typer.Option(envvar="ME", show_envvar=False)]):
401 print(f"Hello {user}")
402 ```
403 """
404 ),
405 ] = True,
406 # Choice
407 case_sensitive: Annotated[
408 bool,
409 Doc(
410 """
411 For a CLI Option representing an [Enum (choice)](https://typer.tiangolo.com/tutorial/parameter-types/enum),
412 you can allow case-insensitive matching with this parameter:
414 **Example**
416 ```python
417 from enum import StrEnum
419 class NeuralNetwork(StrEnum):
420 simple = "simple"
421 conv = "conv"
422 lstm = "lstm"
424 @app.command()
425 def main(
426 network: Annotated[NeuralNetwork, typer.Option(case_sensitive=False)]):
427 print(f"Training neural network of type: {network}")
428 ```
430 With this setting, "LSTM" or "lstm" will both be valid values that will be resolved to `NeuralNetwork.lstm`.
431 """
432 ),
433 ] = True,
434 # Numbers
435 min: Annotated[
436 int | float | None,
437 Doc(
438 """
439 For a CLI Option representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),
440 you can define numeric validations with `min` and `max` values:
442 **Example**
444 ```python
445 @app.command()
446 def main(
447 user: Annotated[str, typer.Argument()],
448 user_id: Annotated[int, typer.Option(min=1, max=1000)],
449 ):
450 print(f"ID for {user} is {user_id}")
451 ```
453 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.
454 """
455 ),
456 ] = None,
457 max: Annotated[
458 int | float | None,
459 Doc(
460 """
461 For a CLI Option representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),
462 you can define numeric validations with `min` and `max` values:
464 **Example**
466 ```python
467 @app.command()
468 def main(
469 user: Annotated[str, typer.Argument()],
470 user_id: Annotated[int, typer.Option(min=1, max=1000)],
471 ):
472 print(f"ID for {user} is {user_id}")
473 ```
475 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.
476 """
477 ),
478 ] = None,
479 clamp: Annotated[
480 bool,
481 Doc(
482 """
483 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`,
484 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`.
486 **Example**
488 ```python
489 @app.command()
490 def main(
491 user: Annotated[str, typer.Argument()],
492 user_id: Annotated[int, typer.Option(min=1, max=1000, clamp=True)],
493 ):
494 print(f"ID for {user} is {user_id}")
495 ```
497 If the user attempts to input 3420 for `user_id`, this will internally be converted to `1000`.
498 """
499 ),
500 ] = False,
501 # DateTime
502 formats: Annotated[
503 list[str] | None,
504 Doc(
505 """
506 For a CLI Option representing a [DateTime object](https://typer.tiangolo.com/tutorial/parameter-types/datetime),
507 you can customize the formats that can be parsed automatically:
509 **Example**
511 ```python
512 from datetime import datetime
514 @app.command()
515 def main(
516 birthday: Annotated[
517 datetime,
518 typer.Option(
519 formats=["%Y-%m-%d", "%Y-%m-%d %H:%M:%S", "%m/%d/%Y"]
520 ),
521 ],
522 ):
523 print(f"Birthday defined at: {birthday}")
524 ```
525 """
526 ),
527 ] = None,
528 # File
529 mode: Annotated[
530 str | None,
531 Doc(
532 """
533 For a CLI Option representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),
534 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).
536 **Example**
538 ```python
539 @app.command()
540 def main(config: Annotated[typer.FileText, typer.Option(mode="a")]):
541 config.write("This is a single line\\n")
542 print("Config line written")
543 ```
544 """
545 ),
546 ] = None,
547 encoding: Annotated[
548 str | None,
549 Doc(
550 """
551 Customize the encoding of this CLI Option represented by a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/).
553 **Example**
555 ```python
556 @app.command()
557 def main(config: Annotated[typer.FileText, typer.Option(encoding="utf-8")]):
558 config.write("All the text gets written\\n")
559 ```
560 """
561 ),
562 ] = None,
563 errors: Annotated[
564 str | None,
565 Doc(
566 """
567 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
569 ---
571 The error handling mode.
572 """
573 ),
574 ] = "strict",
575 lazy: Annotated[
576 bool | None,
577 Doc(
578 """
579 For a CLI Option representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),
580 by default the file will not be created until you actually start writing to it.
581 You can change this behaviour by setting this parameter.
582 By default, it's set to `True` for writing and to `False` for reading.
584 **Example**
586 ```python
587 @app.command()
588 def main(config: Annotated[typer.FileText, typer.Option(mode="a", lazy=False)]):
589 config.write("This is a single line\\n")
590 print("Config line written")
591 ```
592 """
593 ),
594 ] = None,
595 atomic: Annotated[
596 bool,
597 Doc(
598 """
599 For a CLI Option representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),
600 you can ensure that all write instructions first go into a temporal file, and are only moved to the final destination after completing
601 by setting `atomic` to `True`. This can be useful for files with potential concurrent access.
603 **Example**
605 ```python
606 @app.command()
607 def main(config: Annotated[typer.FileText, typer.Option(mode="a", atomic=True)]):
608 config.write("All the text")
609 ```
610 """
611 ),
612 ] = False,
613 # Path
614 exists: Annotated[
615 bool,
616 Doc(
617 """
618 When set to `True` for a [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/),
619 additional validation is performed to check that the file or directory exists. If not, the value will be invalid.
621 **Example**
623 ```python
624 from pathlib import Path
626 @app.command()
627 def main(config: Annotated[Path, typer.Option(exists=True)]):
628 text = config.read_text()
629 print(f"Config file contents: {text}")
630 ```
631 """
632 ),
633 ] = False,
634 file_okay: Annotated[
635 bool,
636 Doc(
637 """
638 Determine whether or not a [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/)
639 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.
641 **Example**
643 ```python
644 from pathlib import Path
646 @app.command()
647 def main(config: Annotated[Path, typer.Option(exists=True, file_okay=False)]):
648 print(f"Directory listing: {[x.name for x in config.iterdir()]}")
649 ```
650 """
651 ),
652 ] = True,
653 dir_okay: Annotated[
654 bool,
655 Doc(
656 """
657 Determine whether or not a [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/)
658 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.
660 **Example**
662 ```python
663 from pathlib import Path
665 @app.command()
666 def main(config: Annotated[Path, typer.Argument(exists=True, dir_okay=False)]):
667 text = config.read_text()
668 print(f"Config file contents: {text}")
669 ```
670 """
671 ),
672 ] = True,
673 writable: Annotated[
674 bool,
675 Doc(
676 """
677 Whether or not to perform a writable check for this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/).
679 **Example**
681 ```python
682 from pathlib import Path
684 @app.command()
685 def main(config: Annotated[Path, typer.Option(writable=True)]):
686 config.write_text("All the text")
687 ```
688 """
689 ),
690 ] = False,
691 readable: Annotated[
692 bool,
693 Doc(
694 """
695 Whether or not to perform a readable check for this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/).
697 **Example**
699 ```python
700 from pathlib import Path
702 @app.command()
703 def main(config: Annotated[Path, typer.Option(readable=True)]):
704 config.read_text("All the text")
705 ```
706 """
707 ),
708 ] = True,
709 resolve_path: Annotated[
710 bool,
711 Doc(
712 """
713 Whether or not to fully resolve the path of this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/),
714 meaning that the path becomes absolute and symlinks are resolved.
716 **Example**
718 ```python
719 from pathlib import Path
721 @app.command()
722 def main(config: Annotated[Path, typer.Option(resolve_path=True)]):
723 config.read_text("All the text")
724 ```
725 """
726 ),
727 ] = False,
728 allow_dash: Annotated[
729 bool,
730 Doc(
731 """
732 When set to `True`, a single dash for this [`Path` CLI Option](https://typer.tiangolo.com/tutorial/parameter-types/path/)
733 would be a valid value, indicating standard streams. This is a more advanced use-case.
734 """
735 ),
736 ] = False,
737 path_type: Annotated[
738 None | type[str] | type[bytes],
739 Doc(
740 """
741 A string type that will be used to represent this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).
742 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.
743 This is a more advanced use-case.
744 """
745 ),
746 ] = None,
747 # Rich settings
748 rich_help_panel: Annotated[
749 str | None,
750 Doc(
751 """
752 Set the panel name where you want this CLI Option to be shown in the [help text](https://typer.tiangolo.com/tutorial/arguments/help).
754 **Example**
756 ```python
757 @app.command()
758 def main(
759 name: Annotated[str, typer.Argument(help="Who to greet")],
760 age: Annotated[str, typer.Option(help="Their age", rich_help_panel="Data")],
761 ):
762 print(f"Hello {name} of age {age}")
763 ```
764 """
765 ),
766 ] = None,
767) -> Any:
768 """
769 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`.
771 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`
772 and omitting a default value.
774 ## Example
776 ```python
777 @app.command()
778 def register(
779 user: Annotated[str, typer.Argument()],
780 age: Annotated[int, typer.Option(min=18)],
781 ):
782 print(f"User is {user}")
783 print(f"--age is {age}")
784 ```
786 Note how in this example, `--age` is a required CLI Option.
787 """
788 return OptionInfo( 1abcdefghij
789 # Parameter
790 default=default,
791 param_decls=param_decls,
792 callback=callback,
793 metavar=metavar,
794 expose_value=expose_value,
795 is_eager=is_eager,
796 envvar=envvar,
797 shell_complete=shell_complete,
798 autocompletion=autocompletion,
799 default_factory=default_factory,
800 # Custom type
801 parser=parser,
802 # Option
803 show_default=show_default,
804 prompt=prompt,
805 confirmation_prompt=confirmation_prompt,
806 prompt_required=prompt_required,
807 hide_input=hide_input,
808 is_flag=is_flag,
809 flag_value=flag_value,
810 count=count,
811 allow_from_autoenv=allow_from_autoenv,
812 help=help,
813 hidden=hidden,
814 show_choices=show_choices,
815 show_envvar=show_envvar,
816 # Choice
817 case_sensitive=case_sensitive,
818 # Numbers
819 min=min,
820 max=max,
821 clamp=clamp,
822 # DateTime
823 formats=formats,
824 # File
825 mode=mode,
826 encoding=encoding,
827 errors=errors,
828 lazy=lazy,
829 atomic=atomic,
830 # Path
831 exists=exists,
832 file_okay=file_okay,
833 dir_okay=dir_okay,
834 writable=writable,
835 readable=readable,
836 resolve_path=resolve_path,
837 allow_dash=allow_dash,
838 path_type=path_type,
839 # Rich settings
840 rich_help_panel=rich_help_panel,
841 )
844def Argument( 1abcdefghij
845 # Parameter
846 default: Annotated[
847 Any | None,
848 Doc(
849 """
850 By default, CLI arguments are required. However, by giving them a default value they become [optional](https://typer.tiangolo.com/tutorial/arguments/optional):
852 **Example**
854 ```python
855 @app.command()
856 def main(name: str = typer.Argument("World")):
857 print(f"Hello {name}!")
858 ```
860 Note that this usage is deprecated, and we recommend to use `Annotated` instead:
861 ```python
862 @app.command()
863 def main(name: Annotated[str, typer.Argument()] = "World"):
864 print(f"Hello {name}!")
865 ```
866 """
867 ),
868 ] = ...,
869 *,
870 callback: Annotated[
871 Callable[..., Any] | None,
872 Doc(
873 """
874 Add a callback to this CLI Argument, to execute additional logic with the value received from the terminal.
875 See [the tutorial about callbacks](https://typer.tiangolo.com/tutorial/options/callback-and-context/) for more details.
877 **Example**
879 ```python
880 def name_callback(value: str):
881 if value != "Deadpool":
882 raise typer.BadParameter("Only Deadpool is allowed")
883 return value
885 @app.command()
886 def main(name: Annotated[str, typer.Argument(callback=name_callback)]):
887 print(f"Hello {name}")
888 ```
889 """
890 ),
891 ] = None,
892 metavar: Annotated[
893 str | None,
894 Doc(
895 """
896 Customize the name displayed in the help text to represent this CLI Argument.
897 By default, it will be the same name you declared, in uppercase.
898 See [the tutorial about CLI Arguments with Help](https://typer.tiangolo.com/tutorial/arguments/help/#custom-help-name-metavar) for more details.
900 **Example**
902 ```python
903 @app.command()
904 def main(name: Annotated[str, typer.Argument(metavar="✨username✨")]):
905 print(f"Hello {name}")
906 ```
907 """
908 ),
909 ] = None,
910 expose_value: Annotated[
911 bool,
912 Doc(
913 """
914 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
916 ---
918 If this is `True` then the value is passed onwards to the command callback and stored on the context, otherwise it’s skipped.
919 """
920 ),
921 ] = True,
922 is_eager: Annotated[
923 bool,
924 Doc(
925 """
926 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.
927 For more information and an extended example, see the documentation [here](https://typer.tiangolo.com/tutorial/options/version/#fix-with-is_eager).
928 """
929 ),
930 ] = False,
931 envvar: Annotated[
932 str | list[str] | None,
933 Doc(
934 """
935 Configure an argument to read a value from an environment variable if it is not provided in the command line as a CLI argument.
936 For more information, see the [documentation on Environment Variables](https://typer.tiangolo.com/tutorial/arguments/envvar/).
938 **Example**
940 ```python
941 @app.command()
942 def main(name: Annotated[str, typer.Argument(envvar="ME")]):
943 print(f"Hello Mr. {name}")
944 ```
945 """
946 ),
947 ] = None,
948 # TODO: Remove shell_complete in a future version (after 0.16.0)
949 shell_complete: Annotated[
950 Callable[
951 [_click.Context, _click.Parameter, str],
952 list["CompletionItem"] | list[str],
953 ]
954 | None,
955 Doc(
956 """
957 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
958 It is however not fully functional, and will likely be removed in future versions.
959 """
960 ),
961 ] = None,
962 autocompletion: Annotated[
963 Callable[..., Any] | None,
964 Doc(
965 """
966 Provide a custom function that helps to autocomplete the values of this CLI Argument.
967 See [the tutorial on parameter autocompletion](https://typer.tiangolo.com/tutorial/options-autocompletion) for more details.
969 **Example**
971 ```python
972 def complete():
973 return ["Me", "Myself", "I"]
975 @app.command()
976 def main(name: Annotated[str, typer.Argument(autocompletion=complete)]):
977 print(f"Hello {name}")
978 ```
979 """
980 ),
981 ] = None,
982 default_factory: Annotated[
983 Callable[[], Any] | None,
984 Doc(
985 """
986 Provide a custom function that dynamically generates a [default](https://typer.tiangolo.com/tutorial/arguments/default) for this CLI Argument.
988 **Example**
990 ```python
991 def get_name():
992 return random.choice(["Me", "Myself", "I"])
994 @app.command()
995 def main(name: Annotated[str, typer.Argument(default_factory=get_name)]):
996 print(f"Hello {name}")
997 ```
998 """
999 ),
1000 ] = None,
1001 # Custom type
1002 parser: Annotated[
1003 Callable[[str], Any] | None,
1004 Doc(
1005 """
1006 Use your own custom types in Typer applications by defining a `parser` function that parses input into your own types:
1008 **Example**
1010 ```python
1011 class CustomClass:
1012 def __init__(self, value: str):
1013 self.value = value
1015 def __str__(self):
1016 return f"<CustomClass: value={self.value}>"
1018 def my_parser(value: str):
1019 return CustomClass(value * 2)
1021 @app.command()
1022 def main(arg: Annotated[CustomClass, typer.Argument(parser=my_parser):
1023 print(f"arg is {arg}")
1024 ```
1025 """
1026 ),
1027 ] = None,
1028 # TyperArgument
1029 show_default: Annotated[
1030 bool | str,
1031 Doc(
1032 """
1033 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/).
1035 **Example**
1037 ```python
1038 @app.command()
1039 def main(name: Annotated[str, typer.Argument(show_default=False)] = "Rick"):
1040 print(f"Hello {name}")
1041 ```
1042 """
1043 ),
1044 ] = True,
1045 show_choices: Annotated[
1046 bool,
1047 Doc(
1048 """
1049 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
1051 ---
1053 When set to `False`, this suppresses choices from being displayed inline when `prompt` is used.
1054 """
1055 ),
1056 ] = True,
1057 show_envvar: Annotated[
1058 bool,
1059 Doc(
1060 """
1061 When an ["envvar"](https://typer.tiangolo.com/tutorial/arguments/envvar) is defined, prevent it from showing up in the help text:
1063 **Example**
1065 ```python
1066 @app.command()
1067 def main(name: Annotated[str, typer.Argument(envvar="ME", show_envvar=False)]):
1068 print(f"Hello Mr. {name}")
1069 ```
1070 """
1071 ),
1072 ] = True,
1073 help: Annotated[
1074 str | None,
1075 Doc(
1076 """
1077 Help text for this CLI Argument.
1078 See [the tutorial about CLI Arguments with help](https://typer.tiangolo.com/tutorial/arguments/help/) for more dedails.
1080 **Example**
1082 ```python
1083 @app.command()
1084 def greet(name: Annotated[str, typer.Argument(help="Person to greet")]):
1085 print(f"Hello {name}")
1086 ```
1087 """
1088 ),
1089 ] = None,
1090 hidden: Annotated[
1091 bool,
1092 Doc(
1093 """
1094 Hide this CLI Argument from [help outputs](https://typer.tiangolo.com/tutorial/arguments/help). `False` by default.
1096 **Example**
1098 ```python
1099 @app.command()
1100 def main(name: Annotated[str, typer.Argument(hidden=True)] = "World"):
1101 print(f"Hello {name}")
1102 ```
1103 """
1104 ),
1105 ] = False,
1106 # Choice
1107 case_sensitive: Annotated[
1108 bool,
1109 Doc(
1110 """
1111 For a CLI Argument representing an [Enum (choice)](https://typer.tiangolo.com/tutorial/parameter-types/enum),
1112 you can allow case-insensitive matching with this parameter:
1114 **Example**
1116 ```python
1117 from enum import StrEnum
1119 class NeuralNetwork(StrEnum):
1120 simple = "simple"
1121 conv = "conv"
1122 lstm = "lstm"
1124 @app.command()
1125 def main(
1126 network: Annotated[NeuralNetwork, typer.Argument(case_sensitive=False)]):
1127 print(f"Training neural network of type: {network}")
1128 ```
1130 With this setting, "LSTM" or "lstm" will both be valid values that will be resolved to `NeuralNetwork.lstm`.
1131 """
1132 ),
1133 ] = True,
1134 # Numbers
1135 min: Annotated[
1136 int | float | None,
1137 Doc(
1138 """
1139 For a CLI Argument representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),
1140 you can define numeric validations with `min` and `max` values:
1142 **Example**
1144 ```python
1145 @app.command()
1146 def main(
1147 user: Annotated[str, typer.Argument()],
1148 user_id: Annotated[int, typer.Argument(min=1, max=1000)],
1149 ):
1150 print(f"ID for {user} is {user_id}")
1151 ```
1153 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.
1154 """
1155 ),
1156 ] = None,
1157 max: Annotated[
1158 int | float | None,
1159 Doc(
1160 """
1161 For a CLI Argument representing a [number](https://typer.tiangolo.com/tutorial/parameter-types/number/) (`int` or `float`),
1162 you can define numeric validations with `min` and `max` values:
1164 **Example**
1166 ```python
1167 @app.command()
1168 def main(
1169 user: Annotated[str, typer.Argument()],
1170 user_id: Annotated[int, typer.Argument(min=1, max=1000)],
1171 ):
1172 print(f"ID for {user} is {user_id}")
1173 ```
1175 If the user attempts to input an invalid number, an error will be shown, explaining why the value is invalid.
1176 """
1177 ),
1178 ] = None,
1179 clamp: Annotated[
1180 bool,
1181 Doc(
1182 """
1183 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`,
1184 you can opt to use the closest minimum or maximum value instead of raising an error. This is done by setting `clamp` to `True`.
1186 **Example**
1188 ```python
1189 @app.command()
1190 def main(
1191 user: Annotated[str, typer.Argument()],
1192 user_id: Annotated[int, typer.Argument(min=1, max=1000, clamp=True)],
1193 ):
1194 print(f"ID for {user} is {user_id}")
1195 ```
1197 If the user attempts to input 3420 for `user_id`, this will internally be converted to `1000`.
1198 """
1199 ),
1200 ] = False,
1201 # DateTime
1202 formats: Annotated[
1203 list[str] | None,
1204 Doc(
1205 """
1206 For a CLI Argument representing a [DateTime object](https://typer.tiangolo.com/tutorial/parameter-types/datetime),
1207 you can customize the formats that can be parsed automatically:
1209 **Example**
1211 ```python
1212 from datetime import datetime
1214 @app.command()
1215 def main(
1216 birthday: Annotated[
1217 datetime,
1218 typer.Argument(
1219 formats=["%Y-%m-%d", "%Y-%m-%d %H:%M:%S", "%m/%d/%Y"]
1220 ),
1221 ],
1222 ):
1223 print(f"Birthday defined at: {birthday}")
1224 ```
1225 """
1226 ),
1227 ] = None,
1228 # File
1229 mode: Annotated[
1230 str | None,
1231 Doc(
1232 """
1233 For a CLI Argument representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),
1234 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).
1236 **Example**
1238 ```python
1239 @app.command()
1240 def main(config: Annotated[typer.FileText, typer.Argument(mode="a")]):
1241 config.write("This is a single line\\n")
1242 print("Config line written")
1243 ```
1244 """
1245 ),
1246 ] = None,
1247 encoding: Annotated[
1248 str | None,
1249 Doc(
1250 """
1251 Customize the encoding of this CLI Argument represented by a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/).
1253 **Example**
1255 ```python
1256 @app.command()
1257 def main(config: Annotated[typer.FileText, typer.Argument(encoding="utf-8")]):
1258 config.write("All the text gets written\\n")
1259 ```
1260 """
1261 ),
1262 ] = None,
1263 errors: Annotated[
1264 str | None,
1265 Doc(
1266 """
1267 **Note**: you probably shouldn't use this parameter, it is inherited from Click and supported for compatibility.
1269 ---
1271 The error handling mode.
1272 """
1273 ),
1274 ] = "strict",
1275 lazy: Annotated[
1276 bool | None,
1277 Doc(
1278 """
1279 For a CLI Argument representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),
1280 by default the file will not be created until you actually start writing to it.
1281 You can change this behaviour by setting this parameter.
1282 By default, it's set to `True` for writing and to `False` for reading.
1284 **Example**
1286 ```python
1287 @app.command()
1288 def main(config: Annotated[typer.FileText, typer.Argument(mode="a", lazy=False)]):
1289 config.write("This is a single line\\n")
1290 print("Config line written")
1291 ```
1292 """
1293 ),
1294 ] = None,
1295 atomic: Annotated[
1296 bool,
1297 Doc(
1298 """
1299 For a CLI Argument representing a [File object](https://typer.tiangolo.com/tutorial/parameter-types/file/),
1300 you can ensure that all write instructions first go into a temporal file, and are only moved to the final destination after completing
1301 by setting `atomic` to `True`. This can be useful for files with potential concurrent access.
1303 **Example**
1305 ```python
1306 @app.command()
1307 def main(config: Annotated[typer.FileText, typer.Argument(mode="a", atomic=True)]):
1308 config.write("All the text")
1309 ```
1310 """
1311 ),
1312 ] = False,
1313 # Path
1314 exists: Annotated[
1315 bool,
1316 Doc(
1317 """
1318 When set to `True` for a [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/),
1319 additional validation is performed to check that the file or directory exists. If not, the value will be invalid.
1321 **Example**
1323 ```python
1324 from pathlib import Path
1326 @app.command()
1327 def main(config: Annotated[Path, typer.Argument(exists=True)]):
1328 text = config.read_text()
1329 print(f"Config file contents: {text}")
1330 ```
1331 """
1332 ),
1333 ] = False,
1334 file_okay: Annotated[
1335 bool,
1336 Doc(
1337 """
1338 Determine whether or not a [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/)
1339 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.
1341 **Example**
1343 ```python
1344 from pathlib import Path
1346 @app.command()
1347 def main(config: Annotated[Path, typer.Argument(exists=True, file_okay=False)]):
1348 print(f"Directory listing: {[x.name for x in config.iterdir()]}")
1349 ```
1350 """
1351 ),
1352 ] = True,
1353 dir_okay: Annotated[
1354 bool,
1355 Doc(
1356 """
1357 Determine whether or not a [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/)
1358 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.
1360 **Example**
1362 ```python
1363 from pathlib import Path
1365 @app.command()
1366 def main(config: Annotated[Path, typer.Argument(exists=True, dir_okay=False)]):
1367 text = config.read_text()
1368 print(f"Config file contents: {text}")
1369 ```
1370 """
1371 ),
1372 ] = True,
1373 writable: Annotated[
1374 bool,
1375 Doc(
1376 """
1377 Whether or not to perform a writable check for this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).
1379 **Example**
1381 ```python
1382 from pathlib import Path
1384 @app.command()
1385 def main(config: Annotated[Path, typer.Argument(writable=True)]):
1386 config.write_text("All the text")
1387 ```
1388 """
1389 ),
1390 ] = False,
1391 readable: Annotated[
1392 bool,
1393 Doc(
1394 """
1395 Whether or not to perform a readable check for this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).
1397 **Example**
1399 ```python
1400 from pathlib import Path
1402 @app.command()
1403 def main(config: Annotated[Path, typer.Argument(readable=True)]):
1404 config.read_text("All the text")
1405 ```
1406 """
1407 ),
1408 ] = True,
1409 resolve_path: Annotated[
1410 bool,
1411 Doc(
1412 """
1413 Whether or not to fully resolve the path of this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/),
1414 meaning that the path becomes absolute and symlinks are resolved.
1416 **Example**
1418 ```python
1419 from pathlib import Path
1421 @app.command()
1422 def main(config: Annotated[Path, typer.Argument(resolve_path=True)]):
1423 config.read_text("All the text")
1424 ```
1425 """
1426 ),
1427 ] = False,
1428 allow_dash: Annotated[
1429 bool,
1430 Doc(
1431 """
1432 When set to `True`, a single dash for this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/)
1433 would be a valid value, indicating standard streams. This is a more advanced use-case.
1434 """
1435 ),
1436 ] = False,
1437 path_type: Annotated[
1438 None | type[str] | type[bytes],
1439 Doc(
1440 """
1441 A string type that will be used to represent this [`Path` argument](https://typer.tiangolo.com/tutorial/parameter-types/path/).
1442 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.
1443 This is a more advanced use-case.
1444 """
1445 ),
1446 ] = None,
1447 # Rich settings
1448 rich_help_panel: Annotated[
1449 str | None,
1450 Doc(
1451 """
1452 Set the panel name where you want this CLI Argument to be shown in the [help text](https://typer.tiangolo.com/tutorial/arguments/help).
1454 **Example**
1456 ```python
1457 @app.command()
1458 def main(
1459 name: Annotated[str, typer.Argument(help="Who to greet")],
1460 age: Annotated[str, typer.Option(help="Their age", rich_help_panel="Data")],
1461 ):
1462 print(f"Hello {name} of age {age}")
1463 ```
1464 """
1465 ),
1466 ] = None,
1467) -> Any:
1468 """
1469 A [CLI Argument](https://typer.tiangolo.com/tutorial/arguments) is a positional parameter to your command line application.
1471 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:
1473 ## Example
1475 ```python
1476 @app.command()
1477 def main(name: Annotated[str, typer.Argument()] = "World"):
1478 print(f"Hello {name}!")
1479 ```
1481 Note how in this example, if `name` is not specified on the command line, the application will still execute normally and print "Hello World!".
1482 """
1483 return ArgumentInfo( 1abcdefghij
1484 # Parameter
1485 default=default,
1486 # Arguments can only have one param declaration
1487 # it will be generated from the param name
1488 param_decls=None,
1489 callback=callback,
1490 metavar=metavar,
1491 expose_value=expose_value,
1492 is_eager=is_eager,
1493 envvar=envvar,
1494 shell_complete=shell_complete,
1495 autocompletion=autocompletion,
1496 default_factory=default_factory,
1497 # Custom type
1498 parser=parser,
1499 # TyperArgument
1500 show_default=show_default,
1501 show_choices=show_choices,
1502 show_envvar=show_envvar,
1503 help=help,
1504 hidden=hidden,
1505 # Choice
1506 case_sensitive=case_sensitive,
1507 # Numbers
1508 min=min,
1509 max=max,
1510 clamp=clamp,
1511 # DateTime
1512 formats=formats,
1513 # File
1514 mode=mode,
1515 encoding=encoding,
1516 errors=errors,
1517 lazy=lazy,
1518 atomic=atomic,
1519 # Path
1520 exists=exists,
1521 file_okay=file_okay,
1522 dir_okay=dir_okay,
1523 writable=writable,
1524 readable=readable,
1525 resolve_path=resolve_path,
1526 allow_dash=allow_dash,
1527 path_type=path_type,
1528 # Rich settings
1529 rich_help_panel=rich_help_panel,
1530 )