Merge branch 'main' into fix/help-option-shadowing-suggestion

Author: Rowlando13

.pre-commit-config.yaml

@@ -2,12 +2,17 @@ repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: c60c980e561ed3e73101667fe8365c609d19a438  # frozen: v0.15.9
     hooks:
-      - id: ruff
+      - id: ruff-check
       - id: ruff-format
   - repo: https://github.com/astral-sh/uv-pre-commit
     rev: 0397b68f6f88c024f1d2b355a9818779f6336d16  # frozen: 0.11.3
     hooks:
       - id: uv-lock
+  - repo: https://github.com/codespell-project/codespell
+    rev: 2ccb47ff45ad361a21071a7eedda4c37e6ae8c5a  # frozen: v2.4.2
+    hooks:
+      - id: codespell
+        args: ['--write-changes', '--ignore-words-list=inout,te']
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: 3e8a8703264a2f4a69428a0aa4dcb512790b2c8c  # frozen: v6.0.0
     hooks:

CHANGES.rst

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

docs/commands.md

@@ -351,6 +351,35 @@ And in action:
     })
 ```
 
+### Multi-value parameters
+
+When a `default_map` value is a string for a parameter with `nargs > 1` or a
+{class}`Tuple` type, the string is split automatically, the same way an
+environment variable would be. By default, values are split on whitespace. See
+[Multiple Options from Environment
+Values](options.md#multiple-options-from-environment-values) for details on
+splitting behavior.
+
+```python
+default_map = {
+    "draw": {
+        "point": "3 4",  # split into ("3", "4") for nargs=2
+        "color": "red",  # passed as-is for nargs=1
+    }
+}
+```
+
+You can also pass an already-structured tuple or list, which will be used as-is
+without splitting:
+
+```python
+default_map = {
+    "draw": {
+        "point": (3, 4),  # used directly
+    }
+}
+```
+
 ## Context Defaults
 
 ```{versionadded} 2.0

docs/conf.py

@@ -31,6 +31,7 @@
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3/", None),
 }
+myst_heading_anchors = 3
 
 # HTML -----------------------------------------------------------------
 

docs/contributing.md

@@ -1,21 +1,44 @@
 # Contributing
 
-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/).
+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/).
 
 ## Extra Test Environments
 
 Click includes some extra test environments:
 
--   `tox r -e stress` runs stress tests for race conditions in Click's test runner.
+-   `tox r -e stress` runs stress tests for race conditions
+    in Click's test runner.
 
     ```shell-session
     $ tox r -e stress
     ```
 
--   `tox r -e random` runs tests in parallel in a random order to detect test pollution.
+-   `tox r -e random` runs tests in parallel in a random
+    order to detect test pollution.
 
     ```shell-session
     $ tox r -e random
     ```
 
--   A CI workflow (`.github/workflows/test-flask.yaml`) runs Flask's test suite to catch downstream regressions.
+-   A CI workflow (`.github/workflows/test-flask.yaml`)
+    runs Flask's test suite to catch downstream
+    regressions.
+
+## Code Style
+
+Avoid ternary expressions (`x if cond else y`): coverage
+cannot measure both branches. Use an explicit `if`/`else`
+block instead.
+
+Do not add unnecessary dependencies. If a feature can be
+implemented with the standard library, do not pull in an
+external package for it.
+
+## Formatting
+
+Wrap lines in Markdown files at 80 characters.

docs/parameter-types.md

@@ -70,6 +70,12 @@ The resulting value from an option will always be one of the originally passed c
 regardless of `case_sensitive`.
 ```
 
+```{versionchanged} 8.4.0
+{class}`Choice` is now generic. Parameterize it with the choice value type
+({class}`!Choice[HashType]` for an enum, {class}`!Choice[str]` for plain
+strings) to enable type-checked consumers.
+```
+
 (ranges)=
 
 ### Int and Float Ranges
@@ -153,16 +159,21 @@ To implement a custom type, you need to subclass the {class}`ParamType` class. F
 function that fails with a `ValueError` is also supported, though discouraged. Override the {meth}`~ParamType.convert`
 method to convert the value from a string to the correct type.
 
+{class}`ParamType` is generic in the converted value type: parameterize it with
+the type returned by `convert` so that consumers (and type checkers) can rely
+on the narrowed return type.
+
 The following code implements an integer type that accepts hex and octal numbers in addition to normal integers, and
 converts them into regular integers.
 
 ```python
 import click
 
-class BasedIntParamType(click.ParamType):
+
+class BasedIntParamType(click.ParamType[int]):
     name = "integer"
 
-    def convert(self, value, param, ctx):
+    def convert(self, value, param, ctx) -> int:
         if isinstance(value, int):
             return value
 
@@ -175,6 +186,7 @@ class BasedIntParamType(click.ParamType):
         except ValueError:
             self.fail(f"{value!r} is not a valid integer", param, ctx)
 
+
 BASED_INT = BasedIntParamType()
 ```
 
@@ -184,3 +196,10 @@ conversion fails. The `param` and `ctx` arguments may be `None` in some cases su
 Values from user input or the command line will be strings, but default values and Python arguments may already be the
 correct type. The custom type should check at the top if the value is already valid and pass it through to support those
 cases.
+
+```{versionchanged} 8.4.0
+{class}`ParamType` is now a generic abstract base class. Parameterize it with
+the converted value type ({class}`!ParamType[int]` for an integer-returning
+type) so that {meth}`~ParamType.convert` and downstream consumers carry the
+narrowed type.
+```

docs/shell-completion.md

@@ -120,7 +120,7 @@ indicate special handling for paths, and `help` for shells that support showing
 In this example, the type will suggest environment variables that start with the incomplete value.
 
 ```python
-class EnvVarType(ParamType):
+class EnvVarType(ParamType[str]):
     name = "envvar"
 
     def shell_complete(self, ctx, param, incomplete):

docs/support-multiple-versions.md

@@ -55,7 +55,7 @@ def add_ctx_arg(f: F) -> F:
 Here's an example ``ParamType`` subclass which uses this:
 
 ```python
-class CommaDelimitedString(click.ParamType):
+class CommaDelimitedString(click.ParamType[str]):
     @add_ctx_arg
     def get_metavar(self, param: click.Parameter, ctx: click.Context | None) -> str:
         return "TEXT,TEXT,..."

examples/aliases/aliases.py

@@ -40,7 +40,7 @@ class AliasedGroup(click.Group):
     """
 
     def get_command(self, ctx, cmd_name):
-        # Step one: bulitin commands as normal
+        # Step one: built-in commands as normal
         rv = click.Group.get_command(self, ctx, cmd_name)
         if rv is not None:
             return rv

examples/repo/repo.py

@@ -48,7 +48,7 @@ def cli(ctx, repo_home, config, verbose):
     This tool is supposed to look like a distributed version control
     system to show how something like this can be structured.
     """
-    # Create a repo object and remember it as as the context object.  From
+    # Create a repo object and remember it as the context object.  From
     # this point onwards other commands can refer to it by using the
     # @pass_repo decorator.
     ctx.obj = Repo(os.path.abspath(repo_home))