1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
# User Input Prompts
```{currentmodule} click
```
Click supports prompts in two different places. The first is automated prompts when the parameter handling happens, and
the second is to ask for prompts at a later point independently.
This can be accomplished with the {func}`prompt` function, which asks for valid input according to a type, or the
{func}`confirm` function, which asks for confirmation (yes/no).
```{contents}
---
depth: 2
local: true
---
```
## AsyncClick changes
AsyncClick now async-izes :func:`asyncclick.prompt`. This may require changes
in your program. We are sorry to have to do this in a minor release, but there
is no way around this change because the validation callback might be async.
On the positive side, :func:`asyncclick.prompt` gained a new parameter ``blocking``.
When it is set to `False`, interaction with the user no longer blocks the async
event loop.
However, this currently interacts badly with interrupting the program, e.g. by
pressing Control-C. As most programs prompt the user first and run async tasks later,
the default for ``blocking`` is `True` until we can solve the interrupt problem.
(option-prompting)=
## Option Prompts
Option prompts are integrated into the option interface. Internally, it automatically calls either {func}`prompt` or
{func}`confirm` as necessary.
In some cases, you want parameters that can be provided from the command line, but if not provided, ask for user input
instead. This can be implemented with Click by defining a prompt string.
Example:
```{eval-rst}
.. click:example::
@click.command()
@click.option('--name', prompt=True)
def hello(name):
click.echo(f"Hello {name}!")
And what it looks like:
.. click:run::
invoke(hello, args=['--name=John'])
invoke(hello, input=['John'])
```
If you are not happy with the default prompt string, you can ask for
a different one:
```{eval-rst}
.. click:example::
@click.command()
@click.option('--name', prompt='Your name please')
def hello(name):
click.echo(f"Hello {name}!")
What it looks like:
.. click:run::
invoke(hello, input=['John'])
```
It is advised that prompt not be used in conjunction with the multiple flag set to True. Instead, prompt in the function
interactively.
By default, the user will be prompted for an input if one was not passed through the command line. To turn this behavior
off, see {ref}`optional-value`.
## Input Prompts
To manually ask for user input, you can use the {func}`prompt` function. By default, it accepts any Unicode string, but
you can ask for any other type. For instance, you can ask for a valid integer:
```python
value = await click.prompt('Please enter a valid integer', type=int)
```
Additionally, the type will be determined automatically if a default value is provided. For instance, the following will
only accept floats:
```python
value = await click.prompt('Please enter a number', default=42.0)
```
## Optional Prompts
If the option has `prompt` enabled, then setting `prompt_required=False` tells Click to only show the prompt if the
option's flag is given, instead of if the option is not provided at all.
```{eval-rst}
.. click:example::
@click.command()
@click.option('--name', prompt=True, prompt_required=False, default="Default")
def hello(name):
click.echo(f"Hello {name}!")
.. click:run::
invoke(hello)
invoke(hello, args=["--name", "Value"])
invoke(hello, args=["--name"], input="Prompt")
```
If `required=True`, then the option will still prompt if it is not given, but it will also prompt if only the flag is
given.
## Confirmation Prompts
To ask if a user wants to continue with an action, the {func}`confirm` function comes in handy. By default, it returns
the result of the prompt as a boolean value:
```python
if click.confirm('Do you want to continue?'):
click.echo('Well done!')
```
There is also the option to make the function automatically abort the execution of the program if it does not return
`True`:
```python
click.confirm('Do you want to continue?', abort=True)
```
## Dynamic Defaults for Prompts
The `auto_envvar_prefix` and `default_map` options for the context allow the program to read option values from the
environment or a configuration file. However, this overrides the prompting mechanism, so that the user does not get the
option to change the value interactively.
If you want to let the user configure the default value, but still be prompted if the option isn't specified on the
command line, you can do so by supplying a callable as the default value. For example, to get a default from the
environment:
```python
import os
@click.command()
@click.option(
"--username", prompt=True,
default=lambda: os.environ.get("USER", "")
)
def hello(username):
click.echo(f"Hello, {username}!")
```
To describe what the default value will be, set it in ``show_default``.
```{eval-rst}
.. click:example::
import os
@click.command()
@click.option(
"--username", prompt=True,
default=lambda: os.environ.get("USER", ""),
show_default="current user"
)
def hello(username):
click.echo(f"Hello, {username}!")
.. click:run::
invoke(hello, args=["--help"])
```
|
