如何为Python Click共享选项按命令自定义帮助文本？

问题背景 #

在Python Click多命令工具开发中，已通过共享选项定义减少重复代码，但需要为不同命令的--list选项设置差异化帮助文本：

• cmd1的--list帮助文本：列出篮子里的苹果
• cmd2的--list帮助文本：列出容器里的橙子

核心约束：不能修改共享选项的原始定义（项目中命令与共享选项分属不同文件），仅允许在对应命令的@list_option装饰器附近配置专属帮助文本。

原始代码如下：

import sys
import click

# 共享选项定义（不可修改）
list_option = click.option(
  "-l",
  "--list",
  is_flag=True,
  help="List items."
)

@click.group()
@click.pass_context
def cli(ctx):
    pass

@cli.command()
@click.pass_context
@list_option
def cmd1(ctx, **kwargs):
    print(f'Running cmd1: {kwargs = }')

@cli.command()
@click.pass_context
@list_option
def cmd2(ctx, **kwargs):
    print(f'Running cmd2: {kwargs = }')

if __name__ == '__main__':
    sys.exit(cli())

解决方案 #

编写一个轻量的辅助装饰器，在命令定义阶段覆盖指定选项的帮助文本，完全满足约束要求。

修改后完整代码 #

import sys
import click

# 共享选项定义（保持原样，无需修改）
list_option = click.option(
  "-l",
  "--list",
  is_flag=True,
  help="List items."
)

# 辅助装饰器：用于覆盖指定选项的帮助文本
def override_option_help(option_name, new_help):
    def decorator(command):
        for param in command.params:
            if param.name == option_name:
                param.help = new_help
                break
        return command
    return decorator

@click.group()
@click.pass_context
def cli(ctx):
    pass

@cli.command()
@click.pass_context
@list_option
@override_option_help("list", "列出篮子里的苹果")
def cmd1(ctx, **kwargs):
    print(f'Running cmd1: {kwargs = }')

@cli.command()
@click.pass_context
@list_option
@override_option_help("list", "列出容器里的橙子")
def cmd2(ctx, **kwargs):
    print(f'Running cmd2: {kwargs = }')

if __name__ == '__main__':
    sys.exit(cli())

方案说明 #

1. 辅助装饰器作用：override_option_help通过遍历命令的参数列表，找到目标选项并替换其help属性，不会影响共享选项的原始定义。
2. 装饰器顺序：必须将@override_option_help放在@list_option之后，确保先应用共享选项，再覆盖其帮助文本。
3. 跨文件适配：辅助装饰器可以放在命令所在文件或通用工具文件中，无需改动共享选项所在文件，完美适配项目结构。

内容的提问来源于stack exchange，提问作者zapta