Skip to content

Commit 2d0490b

Browse files
authored
Merge branch 'main' into fix/help-option-shadowing-suggestion
2 parents a34f960 + 8d34495 commit 2d0490b

22 files changed

Lines changed: 406 additions & 169 deletions

.pre-commit-config.yaml

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,17 @@ repos:
22
- repo: https://github.com/astral-sh/ruff-pre-commit
33
rev: c60c980e561ed3e73101667fe8365c609d19a438 # frozen: v0.15.9
44
hooks:
5-
- id: ruff
5+
- id: ruff-check
66
- id: ruff-format
77
- repo: https://github.com/astral-sh/uv-pre-commit
88
rev: 0397b68f6f88c024f1d2b355a9818779f6336d16 # frozen: 0.11.3
99
hooks:
1010
- id: uv-lock
11+
- repo: https://github.com/codespell-project/codespell
12+
rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a # frozen: v2.4.2
13+
hooks:
14+
- id: codespell
15+
args: ['--write-changes', '--ignore-words-list=inout,te']
1116
- repo: https://github.com/pre-commit/pre-commit-hooks
1217
rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c # frozen: v6.0.0
1318
hooks:

CHANGES.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@ Unreleased
3333
Version 8.3.3
3434
-------------
3535

36-
Unreleased
36+
Released 2026-04-20
3737

3838
- Use :func:`shlex.split` to split pager and editor commands into ``argv``
3939
lists for :class:`subprocess.Popen`, removing ``shell=True``.
@@ -972,7 +972,7 @@ Released 2018-09-25
972972
so that changing the working directory does not affect it. :pr:`920`
973973
- Fix incorrect completions when defaults are present :issue:`925`,
974974
:pr:`930`
975-
- Add copy option attrs so that custom classes can be re-used.
975+
- Add copy option attrs so that custom classes can be reused.
976976
:issue:`926`, :pr:`994`
977977
- "x" and "a" file modes now use stdout when file is ``"-"``.
978978
:pr:`929`

docs/commands.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -351,6 +351,35 @@ And in action:
351351
})
352352
```
353353

354+
### Multi-value parameters
355+
356+
When a `default_map` value is a string for a parameter with `nargs > 1` or a
357+
{class}`Tuple` type, the string is split automatically, the same way an
358+
environment variable would be. By default, values are split on whitespace. See
359+
[Multiple Options from Environment
360+
Values](options.md#multiple-options-from-environment-values) for details on
361+
splitting behavior.
362+
363+
```python
364+
default_map = {
365+
"draw": {
366+
"point": "3 4", # split into ("3", "4") for nargs=2
367+
"color": "red", # passed as-is for nargs=1
368+
}
369+
}
370+
```
371+
372+
You can also pass an already-structured tuple or list, which will be used as-is
373+
without splitting:
374+
375+
```python
376+
default_map = {
377+
"draw": {
378+
"point": (3, 4), # used directly
379+
}
380+
}
381+
```
382+
354383
## Context Defaults
355384

356385
```{versionadded} 2.0

docs/conf.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@
3131
intersphinx_mapping = {
3232
"python": ("https://docs.python.org/3/", None),
3333
}
34+
myst_heading_anchors = 3
3435

3536
# HTML -----------------------------------------------------------------
3637

docs/contributing.md

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,44 @@
11
# Contributing
22

3-
This is a quick reference for Click-specific development tasks. For setting up the development environment and the general contribution workflow, see the Pallets [quick reference](https://palletsprojects.com/contributing/quick/) and the [detailed contributing guide](https://palletsprojects.com/contributing/).
3+
This is a quick reference for Click-specific development
4+
tasks. For setting up the development environment and the
5+
general contribution workflow, see the Pallets [quick
6+
reference](https://palletsprojects.com/contributing/quick/)
7+
and the [detailed contributing
8+
guide](https://palletsprojects.com/contributing/).
49

510
## Extra Test Environments
611

712
Click includes some extra test environments:
813

9-
- `tox r -e stress` runs stress tests for race conditions in Click's test runner.
14+
- `tox r -e stress` runs stress tests for race conditions
15+
in Click's test runner.
1016

1117
```shell-session
1218
$ tox r -e stress
1319
```
1420
15-
- `tox r -e random` runs tests in parallel in a random order to detect test pollution.
21+
- `tox r -e random` runs tests in parallel in a random
22+
order to detect test pollution.
1623
1724
```shell-session
1825
$ tox r -e random
1926
```
2027
21-
- A CI workflow (`.github/workflows/test-flask.yaml`) runs Flask's test suite to catch downstream regressions.
28+
- A CI workflow (`.github/workflows/test-flask.yaml`)
29+
runs Flask's test suite to catch downstream
30+
regressions.
31+
32+
## Code Style
33+
34+
Avoid ternary expressions (`x if cond else y`): coverage
35+
cannot measure both branches. Use an explicit `if`/`else`
36+
block instead.
37+
38+
Do not add unnecessary dependencies. If a feature can be
39+
implemented with the standard library, do not pull in an
40+
external package for it.
41+
42+
## Formatting
43+
44+
Wrap lines in Markdown files at 80 characters.

docs/parameter-types.md

Lines changed: 21 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,12 @@ The resulting value from an option will always be one of the originally passed c
7070
regardless of `case_sensitive`.
7171
```
7272

73+
```{versionchanged} 8.4.0
74+
{class}`Choice` is now generic. Parameterize it with the choice value type
75+
({class}`!Choice[HashType]` for an enum, {class}`!Choice[str]` for plain
76+
strings) to enable type-checked consumers.
77+
```
78+
7379
(ranges)=
7480

7581
### Int and Float Ranges
@@ -153,16 +159,21 @@ To implement a custom type, you need to subclass the {class}`ParamType` class. F
153159
function that fails with a `ValueError` is also supported, though discouraged. Override the {meth}`~ParamType.convert`
154160
method to convert the value from a string to the correct type.
155161

162+
{class}`ParamType` is generic in the converted value type: parameterize it with
163+
the type returned by `convert` so that consumers (and type checkers) can rely
164+
on the narrowed return type.
165+
156166
The following code implements an integer type that accepts hex and octal numbers in addition to normal integers, and
157167
converts them into regular integers.
158168

159169
```python
160170
import click
161171

162-
class BasedIntParamType(click.ParamType):
172+
173+
class BasedIntParamType(click.ParamType[int]):
163174
name = "integer"
164175

165-
def convert(self, value, param, ctx):
176+
def convert(self, value, param, ctx) -> int:
166177
if isinstance(value, int):
167178
return value
168179

@@ -175,6 +186,7 @@ class BasedIntParamType(click.ParamType):
175186
except ValueError:
176187
self.fail(f"{value!r} is not a valid integer", param, ctx)
177188

189+
178190
BASED_INT = BasedIntParamType()
179191
```
180192

@@ -184,3 +196,10 @@ conversion fails. The `param` and `ctx` arguments may be `None` in some cases su
184196
Values from user input or the command line will be strings, but default values and Python arguments may already be the
185197
correct type. The custom type should check at the top if the value is already valid and pass it through to support those
186198
cases.
199+
200+
```{versionchanged} 8.4.0
201+
{class}`ParamType` is now a generic abstract base class. Parameterize it with
202+
the converted value type ({class}`!ParamType[int]` for an integer-returning
203+
type) so that {meth}`~ParamType.convert` and downstream consumers carry the
204+
narrowed type.
205+
```

docs/shell-completion.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ indicate special handling for paths, and `help` for shells that support showing
120120
In this example, the type will suggest environment variables that start with the incomplete value.
121121

122122
```python
123-
class EnvVarType(ParamType):
123+
class EnvVarType(ParamType[str]):
124124
name = "envvar"
125125

126126
def shell_complete(self, ctx, param, incomplete):

docs/support-multiple-versions.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -55,7 +55,7 @@ def add_ctx_arg(f: F) -> F:
5555
Here's an example ``ParamType`` subclass which uses this:
5656

5757
```python
58-
class CommaDelimitedString(click.ParamType):
58+
class CommaDelimitedString(click.ParamType[str]):
5959
@add_ctx_arg
6060
def get_metavar(self, param: click.Parameter, ctx: click.Context | None) -> str:
6161
return "TEXT,TEXT,..."

examples/aliases/aliases.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -40,7 +40,7 @@ class AliasedGroup(click.Group):
4040
"""
4141

4242
def get_command(self, ctx, cmd_name):
43-
# Step one: bulitin commands as normal
43+
# Step one: built-in commands as normal
4444
rv = click.Group.get_command(self, ctx, cmd_name)
4545
if rv is not None:
4646
return rv

examples/repo/repo.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ def cli(ctx, repo_home, config, verbose):
4848
This tool is supposed to look like a distributed version control
4949
system to show how something like this can be structured.
5050
"""
51-
# Create a repo object and remember it as as the context object. From
51+
# Create a repo object and remember it as the context object. From
5252
# this point onwards other commands can refer to it by using the
5353
# @pass_repo decorator.
5454
ctx.obj = Repo(os.path.abspath(repo_home))

0 commit comments

Comments
 (0)