click 8.4.0__tar.gz → 8.4.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {click-8.4.0 → click-8.4.2}/PKG-INFO +1 -1
- {click-8.4.0 → click-8.4.2}/docs/advanced.md +23 -17
- {click-8.4.0 → click-8.4.2}/docs/api.md +4 -0
- click-8.4.2/docs/changes.md +5 -0
- {click-8.4.0 → click-8.4.2}/docs/conf.py +1 -0
- {click-8.4.0 → click-8.4.2}/docs/documentation.md +48 -0
- click-8.4.2/docs/index.md +153 -0
- {click-8.4.0 → click-8.4.2}/docs/options.md +9 -3
- {click-8.4.0 → click-8.4.2}/docs/parameters.md +1 -1
- {click-8.4.0 → click-8.4.2}/docs/quickstart.md +7 -7
- {click-8.4.0 → click-8.4.2}/docs/wincmd.md +6 -4
- {click-8.4.0 → click-8.4.2}/pyproject.toml +7 -3
- {click-8.4.0 → click-8.4.2}/src/click/_termui_impl.py +51 -15
- {click-8.4.0 → click-8.4.2}/src/click/core.py +154 -50
- {click-8.4.0 → click-8.4.2}/src/click/decorators.py +30 -6
- {click-8.4.0 → click-8.4.2}/src/click/exceptions.py +46 -12
- {click-8.4.0 → click-8.4.2}/src/click/formatting.py +12 -7
- {click-8.4.0 → click-8.4.2}/src/click/shell_completion.py +67 -41
- {click-8.4.0 → click-8.4.2}/src/click/termui.py +5 -1
- {click-8.4.0 → click-8.4.2}/src/click/testing.py +51 -15
- {click-8.4.0 → click-8.4.2}/src/click/types.py +160 -85
- {click-8.4.0 → click-8.4.2}/src/click/utils.py +20 -8
- {click-8.4.0 → click-8.4.2}/tests/test_arguments.py +26 -0
- {click-8.4.0 → click-8.4.2}/tests/test_basic.py +119 -0
- {click-8.4.0 → click-8.4.2}/tests/test_commands.py +43 -0
- {click-8.4.0 → click-8.4.2}/tests/test_defaults.py +150 -0
- {click-8.4.0 → click-8.4.2}/tests/test_options.py +78 -4
- {click-8.4.0 → click-8.4.2}/tests/test_shell_completion.py +28 -49
- {click-8.4.0 → click-8.4.2}/tests/test_stream_lifecycle.py +3 -1
- {click-8.4.0 → click-8.4.2}/tests/test_termui.py +98 -10
- {click-8.4.0 → click-8.4.2}/tests/test_testing.py +11 -0
- {click-8.4.0 → click-8.4.2}/tests/test_types.py +15 -6
- {click-8.4.0 → click-8.4.2}/tests/test_utils.py +79 -0
- {click-8.4.0 → click-8.4.2}/uv.lock +1 -1
- click-8.4.0/CHANGES.rst +0 -1467
- click-8.4.0/docs/changes.rst +0 -4
- click-8.4.0/docs/index.rst +0 -145
- {click-8.4.0 → click-8.4.2}/LICENSE.txt +0 -0
- {click-8.4.0 → click-8.4.2}/README.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/_static/click-icon.svg +0 -0
- {click-8.4.0 → click-8.4.2}/docs/_static/click-logo.svg +0 -0
- {click-8.4.0 → click-8.4.2}/docs/_static/click-name.svg +0 -0
- {click-8.4.0 → click-8.4.2}/docs/arguments.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/click-concepts.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/command-line-reference.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/commands-and-groups.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/commands.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/complex.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/contrib.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/contributing.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/design-opinions.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/entry-points.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/exceptions.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/extending-click.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/faqs.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/handling-files.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/license.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/option-decorators.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/parameter-types.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/prompts.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/setuptools.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/shell-completion.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/standalone-apps.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/support-multiple-versions.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/testing.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/unicode-support.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/upgrade-guides.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/utils.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/virtualenv.md +0 -0
- {click-8.4.0 → click-8.4.2}/docs/why.md +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/__init__.py +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/_compat.py +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/_textwrap.py +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/_utils.py +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/_winconsole.py +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/globals.py +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/parser.py +0 -0
- {click-8.4.0 → click-8.4.2}/src/click/py.typed +0 -0
- {click-8.4.0 → click-8.4.2}/tests/conftest.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_chain.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_command_decorators.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_compat.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_context.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_custom_classes.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_formatting.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_imports.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_info_dict.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_normalization.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/test_parser.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_aliased_group.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_confirmation_option.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_group_kw_options.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_help_option.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_options.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_password_option.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_progressbar.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_simple_example.py +0 -0
- {click-8.4.0 → click-8.4.2}/tests/typing/typing_version_option.py +0 -0
|
@@ -130,11 +130,11 @@ it's good to know that the system works this way.
|
|
|
130
130
|
```{eval-rst}
|
|
131
131
|
.. click:example::
|
|
132
132
|
|
|
133
|
-
import urllib
|
|
133
|
+
import urllib.request
|
|
134
134
|
|
|
135
135
|
def open_url(ctx, param, value):
|
|
136
136
|
if value is not None:
|
|
137
|
-
ctx.params['fp'] = urllib.urlopen(value)
|
|
137
|
+
ctx.params['fp'] = urllib.request.urlopen(value)
|
|
138
138
|
return value
|
|
139
139
|
|
|
140
140
|
@click.command()
|
|
@@ -144,22 +144,31 @@ it's good to know that the system works this way.
|
|
|
144
144
|
click.echo(f"{url}: {fp.code}")
|
|
145
145
|
|
|
146
146
|
In this case the callback returns the URL unchanged but also passes a
|
|
147
|
-
second `fp` value to the callback.
|
|
148
|
-
the information in a wrapper, however:
|
|
147
|
+
second `fp` value to the callback.
|
|
149
148
|
|
|
150
|
-
..
|
|
149
|
+
.. caution::
|
|
150
|
+
|
|
151
|
+
Writing to :attr:`~click.Context.params` directly bypasses Click's
|
|
152
|
+
per-parameter pipeline: :meth:`~click.Context.get_parameter_source` returns
|
|
153
|
+
``None`` for it, the value is never run through any :class:`~click.ParamType`
|
|
154
|
+
conversion. And if the key collides with a declared parameter, then the
|
|
155
|
+
shared-name arbitration loses information about where the value came from.
|
|
156
|
+
Prefer the wrapper pattern below when any of those semantics matter.
|
|
151
157
|
|
|
152
|
-
|
|
158
|
+
What's more recommended is to pass the information in a wrapper, however:
|
|
153
159
|
|
|
154
|
-
|
|
160
|
+
.. click:example::
|
|
155
161
|
|
|
162
|
+
import urllib.request
|
|
163
|
+
|
|
164
|
+
class URL:
|
|
156
165
|
def __init__(self, url, fp):
|
|
157
166
|
self.url = url
|
|
158
167
|
self.fp = fp
|
|
159
168
|
|
|
160
169
|
def open_url(ctx, param, value):
|
|
161
170
|
if value is not None:
|
|
162
|
-
return URL(value, urllib.urlopen(value))
|
|
171
|
+
return URL(value, urllib.request.urlopen(value))
|
|
163
172
|
|
|
164
173
|
@click.command()
|
|
165
174
|
@click.option('--url', callback=open_url)
|
|
@@ -186,7 +195,7 @@ token to lowercase:
|
|
|
186
195
|
```{eval-rst}
|
|
187
196
|
.. click:example::
|
|
188
197
|
|
|
189
|
-
CONTEXT_SETTINGS =
|
|
198
|
+
CONTEXT_SETTINGS = {'token_normalize_func': lambda x: x.lower()}
|
|
190
199
|
|
|
191
200
|
@click.command(context_settings=CONTEXT_SETTINGS)
|
|
192
201
|
@click.option('--name', default='Pete')
|
|
@@ -281,17 +290,14 @@ In the end, the result looks something like this:
|
|
|
281
290
|
```{eval-rst}
|
|
282
291
|
.. click:example::
|
|
283
292
|
|
|
284
|
-
import sys
|
|
285
293
|
from subprocess import call
|
|
286
294
|
|
|
287
|
-
@click.command(context_settings=
|
|
288
|
-
ignore_unknown_options=True,
|
|
289
|
-
))
|
|
295
|
+
@click.command(context_settings={'ignore_unknown_options': True})
|
|
290
296
|
@click.option('-v', '--verbose', is_flag=True, help='Enables verbose mode')
|
|
291
297
|
@click.argument('timeit_args', nargs=-1, type=click.UNPROCESSED)
|
|
292
298
|
def cli(verbose, timeit_args):
|
|
293
299
|
"""A fake wrapper around Python's timeit."""
|
|
294
|
-
cmdline = ['echo', 'python', '-mtimeit'
|
|
300
|
+
cmdline = ['echo', 'python', '-mtimeit', *timeit_args]
|
|
295
301
|
if verbose:
|
|
296
302
|
click.echo(f"Invoking: {' '.join(cmdline)}")
|
|
297
303
|
call(cmdline)
|
|
@@ -321,7 +327,7 @@ are important to know about how this ignoring of unhandled flag happens:
|
|
|
321
327
|
- Unknown short options might be partially handled and reassembled if
|
|
322
328
|
necessary. For instance in the above example there is an option
|
|
323
329
|
called `-v` which enables verbose mode. If the command would be
|
|
324
|
-
|
|
330
|
+
invoked with `-va` then the `-v` part would be handled by Click
|
|
325
331
|
(as it is known) and `-a` would end up in the leftover parameters
|
|
326
332
|
for further processing.
|
|
327
333
|
- Depending on what you plan on doing you might have some success by
|
|
@@ -399,8 +405,8 @@ cleanup function.
|
|
|
399
405
|
@click.group()
|
|
400
406
|
@click.option("--name", default="repo.db")
|
|
401
407
|
@click.pass_context
|
|
402
|
-
def cli(ctx,
|
|
403
|
-
ctx.obj = db = open_db(
|
|
408
|
+
def cli(ctx, name):
|
|
409
|
+
ctx.obj = db = open_db(name)
|
|
404
410
|
|
|
405
411
|
@ctx.call_on_close
|
|
406
412
|
def close_db():
|
|
@@ -50,6 +50,46 @@ For subcommands, a short help snippet is generated. By default, it's the first s
|
|
|
50
50
|
invoke(cli, args=['--help'])
|
|
51
51
|
```
|
|
52
52
|
|
|
53
|
+
## Group Help Page
|
|
54
|
+
|
|
55
|
+
The group help prints sub commands, options, epilog help, and arguments, and prints them together.
|
|
56
|
+
|
|
57
|
+
```{eval-rst}
|
|
58
|
+
.. click:example::
|
|
59
|
+
|
|
60
|
+
import click
|
|
61
|
+
|
|
62
|
+
@click.group(
|
|
63
|
+
help="Example Click app with subcommands, options, and positional arguments.",
|
|
64
|
+
epilog=("Examples:\n\n\b\n python hello.py greet Alice --count 2\n"),
|
|
65
|
+
)
|
|
66
|
+
def cli() -> None:
|
|
67
|
+
"""Run the example CLI."""
|
|
68
|
+
|
|
69
|
+
@cli.command()
|
|
70
|
+
@click.argument("name")
|
|
71
|
+
@click.option(
|
|
72
|
+
"--count",
|
|
73
|
+
default=1,
|
|
74
|
+
show_default=True,
|
|
75
|
+
type=click.IntRange(1, None),
|
|
76
|
+
help="Number of greetings to print.",
|
|
77
|
+
)
|
|
78
|
+
@click.option(
|
|
79
|
+
"--greeting",
|
|
80
|
+
default="Hello",
|
|
81
|
+
show_default=True,
|
|
82
|
+
help="Greeting prefix to use.",
|
|
83
|
+
)
|
|
84
|
+
def greet(name: str, count: int, greeting: str) -> None:
|
|
85
|
+
"""Greet NAME one or more times."""
|
|
86
|
+
for _ in range(count):
|
|
87
|
+
click.echo(f"{greeting} {name}!")
|
|
88
|
+
|
|
89
|
+
.. click:run::
|
|
90
|
+
invoke(cli, args=['--help'])
|
|
91
|
+
```
|
|
92
|
+
|
|
53
93
|
## Command Epilog Help
|
|
54
94
|
|
|
55
95
|
The help epilog is printed at the end of the help and is useful for showing example command usages or referencing additional help resources.
|
|
@@ -270,6 +310,14 @@ The default placeholder variable ([meta variable](https://en.wikipedia.org/wiki/
|
|
|
270
310
|
|
|
271
311
|
```
|
|
272
312
|
|
|
313
|
+
```{admonition} Optional elements are bracketed
|
|
314
|
+
:class: note
|
|
315
|
+
|
|
316
|
+
The usage line follows a consistent convention: an element is optional when it is enclosed in square brackets and required when it appears outside them. A required argument appears as `FOO` and an optional one as `[FOO]`, with a variadic argument adding a trailing `...` (so `[FOO]...`). A single pair of brackets can group several tokens, so a chained group renders an extra command and its arguments as one optional, repeatable unit: `[COMMAND2 [ARGS]...]...`. A {class}`Group` that can run without naming a subcommand (`invoke_without_command=True`) also brackets the leading command, showing `[COMMAND]` instead of `COMMAND`. The `[OPTIONS]` placeholder is always bracketed, since adding options is itself optional.
|
|
317
|
+
|
|
318
|
+
This mirrors the conventional utility-argument syntax for optional arguments and operands ([POSIX §12.1](https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap12.html), [`man-pages(7)`](https://man7.org/linux/man-pages/man7/man-pages.7.html)), where a bracketed expression followed by `...` denotes zero or more occurrences. A subcommand name is a positional operand, so Click brackets it under the same rule.
|
|
319
|
+
```
|
|
320
|
+
|
|
273
321
|
## Help Parameter Customization
|
|
274
322
|
|
|
275
323
|
Help parameters are automatically added by Click for any command. The default is `--help` but can be overridden by the context setting {attr}`~Context.help_option_names`. Click also performs automatic conflict resolution on the default help parameter, so if a command itself implements a parameter named `help` then the default help will not be run.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
{.hide-header}
|
|
2
|
+
# Welcome to Click
|
|
3
|
+
|
|
4
|
+
```{image} _static/click-name.svg
|
|
5
|
+
:align: center
|
|
6
|
+
:height: 200px
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
Click is a Python package for creating beautiful command line interfaces
|
|
10
|
+
in a composable way with as little code as necessary. It's the "Command
|
|
11
|
+
Line Interface Creation Kit". It's highly configurable but comes with
|
|
12
|
+
sensible defaults out of the box.
|
|
13
|
+
|
|
14
|
+
It aims to make the process of writing command line tools quick and fun
|
|
15
|
+
while also preventing any frustration caused by the inability to implement
|
|
16
|
+
an intended CLI API.
|
|
17
|
+
|
|
18
|
+
Click in three points:
|
|
19
|
+
|
|
20
|
+
- arbitrary nesting of commands
|
|
21
|
+
- automatic help page generation
|
|
22
|
+
- supports lazy loading of subcommands at runtime
|
|
23
|
+
|
|
24
|
+
What does it look like? Here is an example of a simple Click program:
|
|
25
|
+
|
|
26
|
+
```{eval-rst}
|
|
27
|
+
.. click:example::
|
|
28
|
+
|
|
29
|
+
import click
|
|
30
|
+
|
|
31
|
+
@click.command()
|
|
32
|
+
@click.option('--count', default=1, help='Number of greetings.')
|
|
33
|
+
@click.option('--name', prompt='Your name',
|
|
34
|
+
help='The person to greet.')
|
|
35
|
+
def hello(count, name):
|
|
36
|
+
"""Simple program that greets NAME for a total of COUNT times."""
|
|
37
|
+
for x in range(count):
|
|
38
|
+
click.echo(f"Hello {name}!")
|
|
39
|
+
|
|
40
|
+
if __name__ == '__main__':
|
|
41
|
+
hello()
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
And what it looks like when run:
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
.. click:run::
|
|
48
|
+
|
|
49
|
+
invoke(hello, ['--count=3'], prog_name='python hello.py', input='John\n')
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
It automatically generates nicely formatted help pages:
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
.. click:run::
|
|
56
|
+
|
|
57
|
+
invoke(hello, ['--help'], prog_name='python hello.py')
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
You can get the library directly from PyPI:
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
pip install click
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
# Documentation
|
|
67
|
+
|
|
68
|
+
```{toctree}
|
|
69
|
+
:maxdepth: 2
|
|
70
|
+
|
|
71
|
+
faqs
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Tutorials
|
|
75
|
+
|
|
76
|
+
```{toctree}
|
|
77
|
+
:maxdepth: 1
|
|
78
|
+
|
|
79
|
+
quickstart
|
|
80
|
+
virtualenv
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## How to Guides
|
|
84
|
+
|
|
85
|
+
```{toctree}
|
|
86
|
+
:maxdepth: 1
|
|
87
|
+
|
|
88
|
+
entry-points
|
|
89
|
+
setuptools
|
|
90
|
+
standalone-apps
|
|
91
|
+
upgrade-guides
|
|
92
|
+
support-multiple-versions
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## Conceptual Guides
|
|
96
|
+
|
|
97
|
+
```{toctree}
|
|
98
|
+
:maxdepth: 1
|
|
99
|
+
|
|
100
|
+
design-opinions
|
|
101
|
+
why
|
|
102
|
+
click-concepts
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
## General Reference
|
|
106
|
+
|
|
107
|
+
```{toctree}
|
|
108
|
+
:maxdepth: 1
|
|
109
|
+
|
|
110
|
+
parameters
|
|
111
|
+
parameter-types
|
|
112
|
+
options
|
|
113
|
+
option-decorators
|
|
114
|
+
arguments
|
|
115
|
+
commands-and-groups
|
|
116
|
+
commands
|
|
117
|
+
documentation
|
|
118
|
+
prompts
|
|
119
|
+
handling-files
|
|
120
|
+
advanced
|
|
121
|
+
complex
|
|
122
|
+
extending-click
|
|
123
|
+
testing
|
|
124
|
+
utils
|
|
125
|
+
shell-completion
|
|
126
|
+
exceptions
|
|
127
|
+
command-line-reference
|
|
128
|
+
unicode-support
|
|
129
|
+
wincmd
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
## API Reference
|
|
133
|
+
|
|
134
|
+
```{toctree}
|
|
135
|
+
:maxdepth: 2
|
|
136
|
+
|
|
137
|
+
api
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
# About Project
|
|
141
|
+
|
|
142
|
+
- This documentation is structured according to [Diataxis](https://diataxis.fr/) and written with [MyST](https://myst-parser.readthedocs.io/en/latest/)
|
|
143
|
+
- [Version Policy](https://palletsprojects.com/versions)
|
|
144
|
+
- [Donate](https://palletsprojects.com/donate)
|
|
145
|
+
|
|
146
|
+
```{toctree}
|
|
147
|
+
:maxdepth: 1
|
|
148
|
+
|
|
149
|
+
contributing
|
|
150
|
+
contrib
|
|
151
|
+
license
|
|
152
|
+
changes
|
|
153
|
+
```
|
|
@@ -352,7 +352,7 @@ Use cases for this more explicit pattern include:
|
|
|
352
352
|
* Shell aliases can set a flag, then an invocation can add a negation of the
|
|
353
353
|
flag
|
|
354
354
|
|
|
355
|
-
If a forward slash(`/`) is contained in your option name already, you can split
|
|
355
|
+
If a forward slash (`/`) is contained in your option name already, you can split
|
|
356
356
|
the parameters using `;`. In Windows `/` is commonly used as the prefix
|
|
357
357
|
character.
|
|
358
358
|
|
|
@@ -563,7 +563,7 @@ own help text.
|
|
|
563
563
|
|
|
564
564
|
When several options in a group resolve their values simultaneously, only one
|
|
565
565
|
wins the parameter slot. The full arbitration policy (source precedence,
|
|
566
|
-
explicit-beats-auto tie-break,
|
|
566
|
+
explicit-beats-auto tie-break, last-declared fallback) is enumerated under
|
|
567
567
|
[Option value resolution](#option-value-resolution).
|
|
568
568
|
|
|
569
569
|
## Option value resolution
|
|
@@ -621,6 +621,12 @@ The first source that produces a value wins. Environment variables and
|
|
|
621
621
|
`default_map` entries set to `Sentinel.UNSET` are skipped, so they fall through
|
|
622
622
|
to the next source rather than supplying `UNSET` to the function.
|
|
623
623
|
|
|
624
|
+
If after the four sources above no explicit value was found (or only a
|
|
625
|
+
`default_map`/`default` value was) and the option declares `prompt=`, Click
|
|
626
|
+
prompts the user for one. The resulting value is recorded as
|
|
627
|
+
{attr}`ParameterSource.PROMPT`, which ranks above every source listed above
|
|
628
|
+
for arbitration purposes (see [Slot arbitration](#slot-arbitration)).
|
|
629
|
+
|
|
624
630
|
### Slot arbitration
|
|
625
631
|
|
|
626
632
|
Several options can target the same `name` to form a feature switch group. When
|
|
@@ -703,7 +709,7 @@ Here are the rules used to parse environment variable values for flag options:
|
|
|
703
709
|
```{caution}
|
|
704
710
|
For boolean flags with a pair of values, the only recognized environment variable is the one provided to the `envvar` argument.
|
|
705
711
|
|
|
706
|
-
So an option defined as `--flag
|
|
712
|
+
So an option defined as `--flag/--no-flag`, with an `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.
|
|
707
713
|
```
|
|
708
714
|
|
|
709
715
|
If the flag is activated, its value is set to `flag_value`. Otherwise, the value
|
|
@@ -19,7 +19,7 @@ Click supports only two principle types of parameters for scripts (by design): o
|
|
|
19
19
|
|
|
20
20
|
## Arguments
|
|
21
21
|
|
|
22
|
-
- Are optional
|
|
22
|
+
- Are optional within reason, but not entirely so.
|
|
23
23
|
- Recommended to use for subcommands, urls, or files.
|
|
24
24
|
- Can take an arbitrary number of arguments.
|
|
25
25
|
- Are not fully documented by the help page since they may be too specific to be automatically documented. For more see {ref}`documenting-arguments`.
|
|
@@ -142,17 +142,17 @@ and registered with a group later with `group.add_command()`. This could be used
|
|
|
142
142
|
modules.
|
|
143
143
|
|
|
144
144
|
```{code-block} python
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
145
|
+
@click.command()
|
|
146
|
+
def greet():
|
|
147
|
+
click.echo("Hello, World!")
|
|
148
148
|
```
|
|
149
149
|
|
|
150
150
|
```{code-block} python
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
151
|
+
@click.group()
|
|
152
|
+
def group():
|
|
153
|
+
pass
|
|
154
154
|
|
|
155
|
-
|
|
155
|
+
group.add_command(greet)
|
|
156
156
|
```
|
|
157
157
|
|
|
158
158
|
## Adding Parameters
|
|
@@ -23,10 +23,12 @@ used for parameters.
|
|
|
23
23
|
|
|
24
24
|
## Unicode Output and Input
|
|
25
25
|
|
|
26
|
-
Unicode output and input on Windows is implemented through the concept of a
|
|
27
|
-
that when click first needs a text output
|
|
28
|
-
|
|
29
|
-
|
|
26
|
+
Unicode output and input on Windows is implemented through the concept of a
|
|
27
|
+
dispatching text stream. This means that when click first needs a text output
|
|
28
|
+
(or input) stream on windows it goes through a few checks to figure out if a
|
|
29
|
+
windows console is connected or not. If no Windows console is present then the
|
|
30
|
+
text output stream is returned as such and the encoding for that stream is set
|
|
31
|
+
to `utf-8` like on all platforms.
|
|
30
32
|
|
|
31
33
|
However if a console is connected the stream will instead be emulated and use the cmd.exe unicode APIs to output text
|
|
32
34
|
information. In this case the stream will also use `utf-16-le` as internal encoding. However there is some hackery going
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "click"
|
|
3
|
-
version = "8.4.
|
|
3
|
+
version = "8.4.2"
|
|
4
4
|
description = "Composable command line interface toolkit"
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
license = "BSD-3-Clause"
|
|
@@ -140,8 +140,13 @@ select = [
|
|
|
140
140
|
"I", # isort
|
|
141
141
|
"UP", # pyupgrade
|
|
142
142
|
"W", # pycodestyle warning
|
|
143
|
+
"ICN", #flake8-import-conventions (ICN)
|
|
143
144
|
]
|
|
144
145
|
|
|
146
|
+
[tool.ruff.lint.flake8-import-conventions.aliases]
|
|
147
|
+
# Declare the default aliases.
|
|
148
|
+
typing = "t"
|
|
149
|
+
|
|
145
150
|
[tool.ruff.lint.isort]
|
|
146
151
|
force-single-line = true
|
|
147
152
|
order-by-type = false
|
|
@@ -180,12 +185,11 @@ commands = [[
|
|
|
180
185
|
]]
|
|
181
186
|
|
|
182
187
|
[tool.tox.env.stress]
|
|
183
|
-
description = "stress tests for
|
|
188
|
+
description = "high-iteration stress tests for race conditions"
|
|
184
189
|
commands = [[
|
|
185
190
|
"pytest", "-v", "--tb=short", "-x", "-m", "stress",
|
|
186
191
|
"--basetemp={env_tmp_dir}",
|
|
187
192
|
"--override-ini=addopts=",
|
|
188
|
-
"tests/test_stream_lifecycle.py",
|
|
189
193
|
{replace = "posargs", default = [], extend = true},
|
|
190
194
|
]]
|
|
191
195
|
|
|
@@ -29,6 +29,7 @@ from ._compat import term_len
|
|
|
29
29
|
from ._compat import WIN
|
|
30
30
|
from .exceptions import ClickException
|
|
31
31
|
from .utils import echo
|
|
32
|
+
from .utils import KeepOpenFile
|
|
32
33
|
|
|
33
34
|
V = t.TypeVar("V")
|
|
34
35
|
|
|
@@ -430,25 +431,39 @@ def _pager_contextmanager(
|
|
|
430
431
|
@contextlib.contextmanager
|
|
431
432
|
def get_pager_file(color: bool | None = None) -> t.Generator[t.TextIO, None, None]:
|
|
432
433
|
"""Context manager.
|
|
434
|
+
|
|
433
435
|
Yields a writable file-like object which can be used as an output pager.
|
|
434
|
-
|
|
436
|
+
|
|
437
|
+
.. versionadded:: 8.4.0
|
|
438
|
+
|
|
435
439
|
:param color: controls if the pager supports ANSI colors or not. The
|
|
436
440
|
default is autodetection.
|
|
437
441
|
"""
|
|
438
442
|
with _pager_contextmanager(color=color) as (stream, encoding, color):
|
|
439
443
|
# Split streams by capabilities rather than the abstract TextIO /
|
|
440
444
|
# BinaryIO annotations: buffered text streams can be unwrapped to bytes,
|
|
441
|
-
# while
|
|
445
|
+
# while other streams are yielded as-is.
|
|
446
|
+
wrapper: MaybeStripAnsi | None = None
|
|
442
447
|
if _has_binary_buffer(stream):
|
|
443
448
|
# Text stream backed by a binary buffer.
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
# Binary stream
|
|
447
|
-
stream = MaybeStripAnsi(stream, color=color, encoding=encoding)
|
|
449
|
+
wrapper = MaybeStripAnsi(stream.buffer, color=color, encoding=encoding)
|
|
450
|
+
stream = wrapper
|
|
448
451
|
try:
|
|
449
|
-
|
|
452
|
+
# Narrow the BinaryIO | TextIO union that _pager_contextmanager
|
|
453
|
+
# yields; the caller writes text to the pager.
|
|
454
|
+
yield t.cast(t.TextIO, stream)
|
|
450
455
|
finally:
|
|
451
|
-
|
|
456
|
+
try:
|
|
457
|
+
stream.flush()
|
|
458
|
+
finally:
|
|
459
|
+
# Hand the binary buffer back to the pager that produced it
|
|
460
|
+
# rather than letting this TextIOWrapper close it on garbage
|
|
461
|
+
# collection. The pager owns the buffer's lifecycle: subprocess
|
|
462
|
+
# pipes and temp files are closed by their own helpers, while a
|
|
463
|
+
# borrowed stdout must stay open for the caller. detach() runs
|
|
464
|
+
# even if flush() raised, so the buffer is never closed here.
|
|
465
|
+
if wrapper is not None:
|
|
466
|
+
wrapper.detach()
|
|
452
467
|
|
|
453
468
|
|
|
454
469
|
@contextlib.contextmanager
|
|
@@ -468,8 +483,11 @@ def _pipepager(
|
|
|
468
483
|
"""
|
|
469
484
|
# Split the command into the invoked CLI and its parameters.
|
|
470
485
|
if not cmd_parts:
|
|
486
|
+
# No usable pager: fall back to stdout through _nullpager so it gets the
|
|
487
|
+
# same borrowed-stream handling and the caller's stream is not closed.
|
|
471
488
|
stdout = _default_text_stdout() or StringIO()
|
|
472
|
-
|
|
489
|
+
with _nullpager(stdout, color) as rv:
|
|
490
|
+
yield rv
|
|
473
491
|
return
|
|
474
492
|
|
|
475
493
|
import shutil
|
|
@@ -479,8 +497,11 @@ def _pipepager(
|
|
|
479
497
|
|
|
480
498
|
cmd_filepath = shutil.which(cmd)
|
|
481
499
|
if not cmd_filepath:
|
|
500
|
+
# No usable pager: fall back to stdout through _nullpager so it gets the
|
|
501
|
+
# same borrowed-stream handling and the caller's stream is not closed.
|
|
482
502
|
stdout = _default_text_stdout() or StringIO()
|
|
483
|
-
|
|
503
|
+
with _nullpager(stdout, color) as rv:
|
|
504
|
+
yield rv
|
|
484
505
|
return
|
|
485
506
|
|
|
486
507
|
# Produces a normalized absolute path string.
|
|
@@ -568,8 +589,11 @@ def _tempfilepager(
|
|
|
568
589
|
"""
|
|
569
590
|
# Split the command into the invoked CLI and its parameters.
|
|
570
591
|
if not cmd_parts:
|
|
592
|
+
# No usable pager: fall back to stdout through _nullpager so it gets the
|
|
593
|
+
# same borrowed-stream handling and the caller's stream is not closed.
|
|
571
594
|
stdout = _default_text_stdout() or StringIO()
|
|
572
|
-
|
|
595
|
+
with _nullpager(stdout, color) as rv:
|
|
596
|
+
yield rv
|
|
573
597
|
return
|
|
574
598
|
|
|
575
599
|
import shutil
|
|
@@ -579,8 +603,11 @@ def _tempfilepager(
|
|
|
579
603
|
|
|
580
604
|
cmd_filepath = shutil.which(cmd)
|
|
581
605
|
if not cmd_filepath:
|
|
606
|
+
# No usable pager: fall back to stdout through _nullpager so it gets the
|
|
607
|
+
# same borrowed-stream handling and the caller's stream is not closed.
|
|
582
608
|
stdout = _default_text_stdout() or StringIO()
|
|
583
|
-
|
|
609
|
+
with _nullpager(stdout, color) as rv:
|
|
610
|
+
yield rv
|
|
584
611
|
return
|
|
585
612
|
|
|
586
613
|
# Produces a normalized absolute path string.
|
|
@@ -610,11 +637,20 @@ def _tempfilepager(
|
|
|
610
637
|
def _nullpager(
|
|
611
638
|
stream: t.TextIO, color: bool | None = None
|
|
612
639
|
) -> t.Iterator[tuple[t.TextIO, str, bool]]:
|
|
613
|
-
"""Simply print unformatted text.
|
|
640
|
+
"""Simply print unformatted text. This is the ultimate fallback. Don't close the
|
|
641
|
+
output stream in this case, since it's coming from elsewhere rather than our
|
|
642
|
+
internal helpers.
|
|
643
|
+
|
|
644
|
+
The stream is wrapped in :class:`~click.utils.KeepOpenFile` so that, as a
|
|
645
|
+
borrowed stream, it is not closed by a ``with`` block. The wrapper that
|
|
646
|
+
:func:`get_pager_file` builds around it is detached rather than closed.
|
|
647
|
+
"""
|
|
614
648
|
encoding = get_best_encoding(stream)
|
|
649
|
+
|
|
615
650
|
if color is None:
|
|
616
651
|
color = False
|
|
617
|
-
|
|
652
|
+
|
|
653
|
+
yield KeepOpenFile(stream), encoding, color # type: ignore[misc]
|
|
618
654
|
|
|
619
655
|
|
|
620
656
|
class Editor:
|
|
@@ -759,7 +795,7 @@ def open_url(url: str, wait: bool = False, locate: bool = False) -> int:
|
|
|
759
795
|
elif WIN:
|
|
760
796
|
if locate:
|
|
761
797
|
url = _unquote_file(url)
|
|
762
|
-
args = ["explorer",
|
|
798
|
+
args = ["explorer", "/select,", url]
|
|
763
799
|
try:
|
|
764
800
|
return subprocess.call(args)
|
|
765
801
|
except OSError:
|