help not resolving automatically

[Rowlando13]

From the docs:

The help parameter is implemented in Click in a very special manner. Unlike regular parameters it’s automatically added by Click for any command and it performs automatic conflict resolution. By default it’s called --help, but this can be changed. If a command itself implements a parameter with the same name, the default help parameter stops accepting it. There is a context setting that can be used to override the names of the help parameters called help_option_names.

What is wrong:
Help does not automatically resolve if there is an arg or kwarg called help. In the sample the file is called help.py

import click

# This works 
@click.command()
@click.argument('helps')
def this_works(helps):
    print(helps)

# > python -m help this
# this

# > python -m help --help
# Usage: help.py [OPTIONS] HELPS

# Options:
#   --help  Show this message and exit.

# This does not work
@click.command()
@click.argument('help')
def this_does_not_work(help):
    print(help)

# > python -m help this
# Usage: help.py [OPTIONS] HELP
# Try 'help.py --help' for help.

# Error: Invalid value for '--help': 'this' is not a valid boolean.

# > python -m help --help
# Usage: help.py [OPTIONS] HELP
# Try 'help.py --help' for help.

# Error: Missing argument 'HELP'.

# This does not work
@click.command()
@click.option('--help', default='this_2')
def this_does_not_work_also(help='this_2'):
    print(help)

# > python -m help 
# None

# > python -m help --help
# Error: Option '--help' requires an argument.

if __name__ == '__main__':
    #this_works()
    #this_does_not_work()
    this_does_not_work_also()

• Python version: 3.10.15
• Click version: 8.1.7

[Veebaa]

I have been looking into this and have thought of two solutions for this issue:

1. Detect conflict early and warn the user about it:

• You could issue an error or a clear warning message when the user defines help as an argument, suggesting they rename it to avoid this conflict with --help.
• i.e. a safety net for users who would not be aware of this conflict.

if 'help' in command.params:
    raise click.UsageError("The parameter name 'help' conflicts with the default '--help' flag. Please choose a different name.")

2. Handling the --help flag internally

• Modify the argument parsing flow to allow the help parameter to be used while still dealing with --help as a special case.

I would like to contribute to this issue. How can I help?