Python Click 如何在子命令帮助文本中显示全局选项

Click 默认不会将父级命令组定义的选项自动渲染到嵌套子命令的帮助文本中，要实现全局选项在所有层级子命令帮助页同步展示，通用方案是自定义命令组类实现选项透传，具体实现如下：

核心实现逻辑 #

自定义继承自click.Group的类，完成两个核心能力：

• 解析命令链路时，自动把所有父级定义的全局选项注入到当前子命令的参数列表，供帮助文本渲染使用
• 命令执行时，把全局选项的参数值存入上下文对象，所有子命令可直接读取，不需要重复声明参数接收

实现代码：

import click

class GlobalOptGroup(click.Group):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)
        self.global_opts = []

    def add_global_opt(self, opt):
        self.global_opts.append(opt)
        self.params.insert(0, opt)

    def get_command(self, ctx, cmd_name):
        cmd = super().get_command(ctx, cmd_name)
        if not cmd:
            return None
        # 向当前子命令注入全局选项，用于帮助展示
        for opt in reversed(self.global_opts):
            if opt not in cmd.params:
                cmd.params.insert(0, opt)
        # 子组递归传递全局选项配置
        if isinstance(cmd, GlobalOptGroup):
            cmd.global_opts = self.global_opts + cmd.global_opts
        return cmd

    def invoke(self, ctx):
        ctx.ensure_object(dict)
        # 把全局选项值写入上下文，供子命令调用
        for opt in self.global_opts:
            ctx.obj[opt.name] = ctx.params[opt.name]
        return super().invoke(ctx)

改造原有CLI代码 #

将原有命令组替换为使用上述自定义类，全局选项通过add_global_opt方法绑定即可，不需要在每个子命令上重复声明：

#!/usr/bin/env python
import click

# 此处放入上面的GlobalOptGroup类实现

@click.group(cls=GlobalOptGroup)
def cli():
    """CLI toolbox"""

# 绑定全局选项
cli.add_global_opt(click.option("-l", "--log-level", help="Set log level."))

@cli.group(cls=GlobalOptGroup)
def admin():
    pass

@admin.command()
@click.pass_context
def invite(ctx):
    # 子命令中可直接从上下文读取全局选项值
    log_level = ctx.obj.get("log_level")
    print(f"run invite command, log level is {log_level}")

if __name__ == "__main__":
    cli()

效果验证 #

改造后执行任意层级子命令的--help都能看到全局选项：

• 执行./cli.py admin --help，Options栏会正常展示-l, --log-level TEXT Set log level.
• 执行./cli.py admin invite --help，同样能看到该全局选项

如果是结构非常简单、层级很少的CLI，也可以选择在每个子命令/子组上手动重复声明全局选项，不需要自定义类，但这种方式维护成本高，全局选项变更时需要同步修改所有绑定位置，不推荐中大型CLI使用。

注意：原示例中直接在cli、admin组的回调函数顶层写print逻辑，会导致调用组下任意子命令时都触发打印，属于Click组命令的默认执行逻辑，业务逻辑建议结合上下文对象传递，不要直接写在组回调顶层。

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