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.
Files changed (98) hide show
  1. {click-8.4.0 → click-8.4.2}/PKG-INFO +1 -1
  2. {click-8.4.0 → click-8.4.2}/docs/advanced.md +23 -17
  3. {click-8.4.0 → click-8.4.2}/docs/api.md +4 -0
  4. click-8.4.2/docs/changes.md +5 -0
  5. {click-8.4.0 → click-8.4.2}/docs/conf.py +1 -0
  6. {click-8.4.0 → click-8.4.2}/docs/documentation.md +48 -0
  7. click-8.4.2/docs/index.md +153 -0
  8. {click-8.4.0 → click-8.4.2}/docs/options.md +9 -3
  9. {click-8.4.0 → click-8.4.2}/docs/parameters.md +1 -1
  10. {click-8.4.0 → click-8.4.2}/docs/quickstart.md +7 -7
  11. {click-8.4.0 → click-8.4.2}/docs/wincmd.md +6 -4
  12. {click-8.4.0 → click-8.4.2}/pyproject.toml +7 -3
  13. {click-8.4.0 → click-8.4.2}/src/click/_termui_impl.py +51 -15
  14. {click-8.4.0 → click-8.4.2}/src/click/core.py +154 -50
  15. {click-8.4.0 → click-8.4.2}/src/click/decorators.py +30 -6
  16. {click-8.4.0 → click-8.4.2}/src/click/exceptions.py +46 -12
  17. {click-8.4.0 → click-8.4.2}/src/click/formatting.py +12 -7
  18. {click-8.4.0 → click-8.4.2}/src/click/shell_completion.py +67 -41
  19. {click-8.4.0 → click-8.4.2}/src/click/termui.py +5 -1
  20. {click-8.4.0 → click-8.4.2}/src/click/testing.py +51 -15
  21. {click-8.4.0 → click-8.4.2}/src/click/types.py +160 -85
  22. {click-8.4.0 → click-8.4.2}/src/click/utils.py +20 -8
  23. {click-8.4.0 → click-8.4.2}/tests/test_arguments.py +26 -0
  24. {click-8.4.0 → click-8.4.2}/tests/test_basic.py +119 -0
  25. {click-8.4.0 → click-8.4.2}/tests/test_commands.py +43 -0
  26. {click-8.4.0 → click-8.4.2}/tests/test_defaults.py +150 -0
  27. {click-8.4.0 → click-8.4.2}/tests/test_options.py +78 -4
  28. {click-8.4.0 → click-8.4.2}/tests/test_shell_completion.py +28 -49
  29. {click-8.4.0 → click-8.4.2}/tests/test_stream_lifecycle.py +3 -1
  30. {click-8.4.0 → click-8.4.2}/tests/test_termui.py +98 -10
  31. {click-8.4.0 → click-8.4.2}/tests/test_testing.py +11 -0
  32. {click-8.4.0 → click-8.4.2}/tests/test_types.py +15 -6
  33. {click-8.4.0 → click-8.4.2}/tests/test_utils.py +79 -0
  34. {click-8.4.0 → click-8.4.2}/uv.lock +1 -1
  35. click-8.4.0/CHANGES.rst +0 -1467
  36. click-8.4.0/docs/changes.rst +0 -4
  37. click-8.4.0/docs/index.rst +0 -145
  38. {click-8.4.0 → click-8.4.2}/LICENSE.txt +0 -0
  39. {click-8.4.0 → click-8.4.2}/README.md +0 -0
  40. {click-8.4.0 → click-8.4.2}/docs/_static/click-icon.svg +0 -0
  41. {click-8.4.0 → click-8.4.2}/docs/_static/click-logo.svg +0 -0
  42. {click-8.4.0 → click-8.4.2}/docs/_static/click-name.svg +0 -0
  43. {click-8.4.0 → click-8.4.2}/docs/arguments.md +0 -0
  44. {click-8.4.0 → click-8.4.2}/docs/click-concepts.md +0 -0
  45. {click-8.4.0 → click-8.4.2}/docs/command-line-reference.md +0 -0
  46. {click-8.4.0 → click-8.4.2}/docs/commands-and-groups.md +0 -0
  47. {click-8.4.0 → click-8.4.2}/docs/commands.md +0 -0
  48. {click-8.4.0 → click-8.4.2}/docs/complex.md +0 -0
  49. {click-8.4.0 → click-8.4.2}/docs/contrib.md +0 -0
  50. {click-8.4.0 → click-8.4.2}/docs/contributing.md +0 -0
  51. {click-8.4.0 → click-8.4.2}/docs/design-opinions.md +0 -0
  52. {click-8.4.0 → click-8.4.2}/docs/entry-points.md +0 -0
  53. {click-8.4.0 → click-8.4.2}/docs/exceptions.md +0 -0
  54. {click-8.4.0 → click-8.4.2}/docs/extending-click.md +0 -0
  55. {click-8.4.0 → click-8.4.2}/docs/faqs.md +0 -0
  56. {click-8.4.0 → click-8.4.2}/docs/handling-files.md +0 -0
  57. {click-8.4.0 → click-8.4.2}/docs/license.md +0 -0
  58. {click-8.4.0 → click-8.4.2}/docs/option-decorators.md +0 -0
  59. {click-8.4.0 → click-8.4.2}/docs/parameter-types.md +0 -0
  60. {click-8.4.0 → click-8.4.2}/docs/prompts.md +0 -0
  61. {click-8.4.0 → click-8.4.2}/docs/setuptools.md +0 -0
  62. {click-8.4.0 → click-8.4.2}/docs/shell-completion.md +0 -0
  63. {click-8.4.0 → click-8.4.2}/docs/standalone-apps.md +0 -0
  64. {click-8.4.0 → click-8.4.2}/docs/support-multiple-versions.md +0 -0
  65. {click-8.4.0 → click-8.4.2}/docs/testing.md +0 -0
  66. {click-8.4.0 → click-8.4.2}/docs/unicode-support.md +0 -0
  67. {click-8.4.0 → click-8.4.2}/docs/upgrade-guides.md +0 -0
  68. {click-8.4.0 → click-8.4.2}/docs/utils.md +0 -0
  69. {click-8.4.0 → click-8.4.2}/docs/virtualenv.md +0 -0
  70. {click-8.4.0 → click-8.4.2}/docs/why.md +0 -0
  71. {click-8.4.0 → click-8.4.2}/src/click/__init__.py +0 -0
  72. {click-8.4.0 → click-8.4.2}/src/click/_compat.py +0 -0
  73. {click-8.4.0 → click-8.4.2}/src/click/_textwrap.py +0 -0
  74. {click-8.4.0 → click-8.4.2}/src/click/_utils.py +0 -0
  75. {click-8.4.0 → click-8.4.2}/src/click/_winconsole.py +0 -0
  76. {click-8.4.0 → click-8.4.2}/src/click/globals.py +0 -0
  77. {click-8.4.0 → click-8.4.2}/src/click/parser.py +0 -0
  78. {click-8.4.0 → click-8.4.2}/src/click/py.typed +0 -0
  79. {click-8.4.0 → click-8.4.2}/tests/conftest.py +0 -0
  80. {click-8.4.0 → click-8.4.2}/tests/test_chain.py +0 -0
  81. {click-8.4.0 → click-8.4.2}/tests/test_command_decorators.py +0 -0
  82. {click-8.4.0 → click-8.4.2}/tests/test_compat.py +0 -0
  83. {click-8.4.0 → click-8.4.2}/tests/test_context.py +0 -0
  84. {click-8.4.0 → click-8.4.2}/tests/test_custom_classes.py +0 -0
  85. {click-8.4.0 → click-8.4.2}/tests/test_formatting.py +0 -0
  86. {click-8.4.0 → click-8.4.2}/tests/test_imports.py +0 -0
  87. {click-8.4.0 → click-8.4.2}/tests/test_info_dict.py +0 -0
  88. {click-8.4.0 → click-8.4.2}/tests/test_normalization.py +0 -0
  89. {click-8.4.0 → click-8.4.2}/tests/test_parser.py +0 -0
  90. {click-8.4.0 → click-8.4.2}/tests/typing/typing_aliased_group.py +0 -0
  91. {click-8.4.0 → click-8.4.2}/tests/typing/typing_confirmation_option.py +0 -0
  92. {click-8.4.0 → click-8.4.2}/tests/typing/typing_group_kw_options.py +0 -0
  93. {click-8.4.0 → click-8.4.2}/tests/typing/typing_help_option.py +0 -0
  94. {click-8.4.0 → click-8.4.2}/tests/typing/typing_options.py +0 -0
  95. {click-8.4.0 → click-8.4.2}/tests/typing/typing_password_option.py +0 -0
  96. {click-8.4.0 → click-8.4.2}/tests/typing/typing_progressbar.py +0 -0
  97. {click-8.4.0 → click-8.4.2}/tests/typing/typing_simple_example.py +0 -0
  98. {click-8.4.0 → click-8.4.2}/tests/typing/typing_version_option.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: click
3
- Version: 8.4.0
3
+ Version: 8.4.2
4
4
  Summary: Composable command line interface toolkit
5
5
  Maintainer-email: Pallets <contact@palletsprojects.com>
6
6
  Requires-Python: >=3.10
@@ -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. What's more recommended is to pass
148
- the information in a wrapper, however:
147
+ second `fp` value to the callback.
149
148
 
150
- .. click:example::
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
- import urllib
158
+ What's more recommended is to pass the information in a wrapper, however:
153
159
 
154
- class URL(object):
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 = dict(token_normalize_func=lambda x: x.lower())
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=dict(
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'] + list(timeit_args)
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
- ignored with `-va` then the `-v` part would be handled by Click
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, repo_home):
403
- ctx.obj = db = open_db(repo_home)
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():
@@ -283,6 +283,10 @@ classes and functions.
283
283
  .. autoexception:: FileError
284
284
  ```
285
285
 
286
+ ```{eval-rst}
287
+ .. autoexception:: NoSuchCommand
288
+ ```
289
+
286
290
  ```{eval-rst}
287
291
  .. autoexception:: NoSuchOption
288
292
  ```
@@ -0,0 +1,5 @@
1
+ # Changes
2
+
3
+
4
+ ```{include} ../CHANGES.md
5
+ ```
@@ -31,6 +31,7 @@ extlinks = {
31
31
  intersphinx_mapping = {
32
32
  "python": ("https://docs.python.org/3/", None),
33
33
  }
34
+ myst_enable_extensions = ["attrs_block"]
34
35
  myst_heading_anchors = 3
35
36
 
36
37
  # HTML -----------------------------------------------------------------
@@ -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, first-declared fallback) is enumerated under
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\--no-flag`, with a `envvar="FLAG"` parameter, there is no magical `NO_FLAG=<anything>` variable that is recognized. Only the `FLAG=<anything>` environment variable is recognized.
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 with in reason, but not entirely so.
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
- @click.command()
146
- def greet():
147
- click.echo("Hello, World!")
145
+ @click.command()
146
+ def greet():
147
+ click.echo("Hello, World!")
148
148
  ```
149
149
 
150
150
  ```{code-block} python
151
- @click.group()
152
- def group():
153
- pass
151
+ @click.group()
152
+ def group():
153
+ pass
154
154
 
155
- group.add_command(greet)
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 dispatching text stream. What this means is
27
- that when click first needs a text output (or input) stream on windows it goes through a few checks to figure out of a
28
- windows console is connected or not. If no Windows console is present then the text output stream is returned as such
29
- and the encoding for that stream is set to `utf-8` like on all platforms.
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.0"
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 stream lifecycle race conditions"
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
- .. versionadded:: 8.4
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 text-only streams are yielded as-is.
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
- stream = MaybeStripAnsi(stream.buffer, color=color, encoding=encoding)
445
- elif isinstance(stream, t.BinaryIO):
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
- yield stream
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
- stream.flush()
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
- yield stdout, "utf-8", False
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
- yield stdout, "utf-8", False
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
- yield stdout, "utf-8", False
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
- yield stdout, "utf-8", False
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. This is the ultimate fallback."""
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
- yield stream, encoding, color
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", f"/select,{url}"]
798
+ args = ["explorer", "/select,", url]
763
799
  try:
764
800
  return subprocess.call(args)
765
801
  except OSError: