Fix parsing when a parameter is named help

Fixes #2819

Author: kdeldycke

CHANGES.md

@@ -15,6 +15,9 @@ Unreleased
   produced by a callback, covering cases {func}`version_option` intentionally
   does not. The feature set of {func}`version_option` is now frozen; see
   [discussion #3527](https://github.com/pallets/click/discussions/3527). {pr}`3581`
+- The automatic help option stores its value under a name no other parameter
+  uses. A parameter named `help`, like `click.argument("help")`, no longer
+  makes both unusable. {issue}`2819` {pr}`3678`
 
 ## Version 8.4.2
 

docs/documentation.md

@@ -322,7 +322,7 @@ The default placeholder variable ([meta variable](https://en.wikipedia.org/wiki/
 
 ## Help Parameter Customization
 
-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.
+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: if the command itself implements an option reusing one of the help option names, the default help parameter stops accepting that name, and is dropped entirely once all its names are taken. A parameter that merely stores its value under the name `help`, like `click.argument("help")`, does not disable the default help option: both keep working independently.
 
 This example changes the default parameters to `-h` and `--help`
 instead of just `--help`:

src/click/core.py

@@ -1153,6 +1153,10 @@ def get_help_option(self, ctx: Context) -> Option | None:
 
         Skipped if :attr:`add_help_option` is ``False``.
 
+        .. versionchanged:: 8.5.0
+            The help option is stored under a name no other parameter
+            uses, so a parameter named ``help`` no longer breaks parsing.
+
         .. versionchanged:: 8.1.8
             The help option is now cached to avoid creating it multiple times.
         """
@@ -1169,8 +1173,17 @@ def get_help_option(self, ctx: Context) -> Option | None:
             # Avoid circular import.
             from .decorators import help_option
 
+            # The parser stores parsed values keyed by parameter name, so
+            # sharing the name of another parameter (like an argument named
+            # "help") would make both clobber each other's value. The help
+            # option never exposes its value, so any free name works.
+            taken_names = {param.name for param in self.params}
+            storage_name = "help"
+            while storage_name in taken_names:
+                storage_name += "_"
+
             # Apply help_option decorator and pop resulting option
-            help_option(*help_option_names)(self)
+            help_option(*help_option_names, storage_name)(self)
             self._help_option = self.params.pop()  # type: ignore[assignment]
 
         return self._help_option

tests/test_basic.py

@@ -28,6 +28,74 @@ def cli():
     assert result.exit_code == 0
 
 
+@pytest.mark.parametrize(
+    ("params", "args", "expected_output", "expected_name"),
+    [
+        ([], [], "\n", "help"),
+        ([click.Argument(["help"])], ["value"], "value\n", "help_"),
+        (
+            [click.Option(["--assist", "help"])],
+            ["--assist", "value"],
+            "value\n",
+            "help_",
+        ),
+        (
+            [click.Argument(["help"]), click.Option(["--other", "help_"])],
+            ["value"],
+            "value\n",
+            "help__",
+        ),
+    ],
+    ids=["no-collision", "argument", "option", "chained-collisions"],
+)
+def test_param_named_help(runner, params, args, expected_output, expected_name):
+    """A parameter storing its value under the name ``help`` does not clash
+    with the automatic help option: the latter keeps its default ``help``
+    storage name unless a user parameter claims it, then underscores are
+    appended until the name is free.
+
+    https://github.com/pallets/click/issues/2819
+    """
+    cli = click.Command(
+        "cli", params=params, callback=lambda **kwargs: click.echo(kwargs.get("help"))
+    )
+
+    help_option = cli.get_help_option(click.Context(cli))
+    assert help_option is not None
+    assert help_option.name == expected_name
+
+    result = runner.invoke(cli, args)
+    assert result.output == expected_output
+    assert result.exit_code == 0
+
+    result = runner.invoke(cli, ["--help"])
+    assert "Show this message and exit." in result.output
+    assert result.exit_code == 0
+
+
+def test_option_reusing_help_flag(runner):
+    """An option reusing the ``--help`` flag replaces the automatic help
+    option entirely.
+
+    https://github.com/pallets/click/issues/2819
+    """
+
+    @click.command()
+    @click.option("--help", default="default value")
+    def cli(help):
+        click.echo(help)
+
+    assert cli.get_help_option(click.Context(cli)) is None
+
+    result = runner.invoke(cli, [])
+    assert result.output == "default value\n"
+    assert result.exit_code == 0
+
+    result = runner.invoke(cli, ["--help", "custom"])
+    assert result.output == "custom\n"
+    assert result.exit_code == 0
+
+
 def test_repr():
     @click.command()
     def command():