Argparse子命令与分组：实现子命令帮助信息独立分组显示且顶级帮助完整展示

要实现你想要的两全其美效果，我们可以通过保留子命令的默认帮助逻辑，但调整其帮助选项的分组，同时给子命令添加描述信息来解决问题。以下是修改后的完整代码：

import argparse

# 创建顶级解析器，禁用默认帮助，自定义帮助分组
parser = argparse.ArgumentParser(prog="example", add_help=False, epilog="A very cool program")

# 添加全局参数分组
toplevel = parser.add_argument_group("Global arguments")
toplevel.add_argument("-g", "--global", action="store_true", help="A global argument.")

# 自定义帮助对话框分组
help_group = parser.add_argument_group("Help dialog")
help_group.add_argument("-h", "--help", action="help", default=argparse.SUPPRESS, help="Show this help message and exit.")

# 创建子命令解析器容器
subparsers = parser.add_subparsers(title="Available subcommands", dest="subcommand", required=True)

# ------------------------------
# 子命令 "a" 的配置
# ------------------------------
# 创建子命令解析器，添加子命令描述（会在顶级帮助中显示）
parser_a = subparsers.add_parser("a", help="Help for sub-command a.")
# 移除argparse自动添加的默认-h/--help动作
default_help_a = parser_a._actions.pop()
# 创建子命令a的帮助对话框分组
help_a = parser_a.add_argument_group("Help dialog")
# 将默认帮助动作添加到自定义分组中
help_a._group_actions.append(default_help_a)
# 添加子命令a的必填参数分组
required_a = parser_a.add_argument_group("Required arguments")
required_a.add_argument("--bar", type=int, help="Flag bar help", required=True)

# ------------------------------
# 子命令 "b" 的配置
# ------------------------------
parser_b = subparsers.add_parser("b", help="Help for sub-command b.")
default_help_b = parser_b._actions.pop()
help_b = parser_b.add_argument_group("Help dialog")
help_b._group_actions.append(default_help_b)
# 必填参数分组
required_b = parser_b.add_argument_group("Required arguments")
required_b.add_argument("--baz", help="Flag baz help", required=True)
# 可选参数分组
optional_b = parser_b.add_argument_group("Optional arguments")
optional_b.add_argument("--tas", help="Flag tas help")

# 解析参数
args = parser.parse_args()
print(args)

关键修改说明 #

1. 给子命令添加描述信息
   在创建子命令解析器时，通过help参数指定子命令的描述（比如parser_a = subparsers.add_parser("a", help="Help for sub-command a.")），这样顶级帮助会自动显示每个子命令的说明，解决了你之前顶级帮助无子命令描述的问题。

2. 调整子命令帮助选项的分组

   • 不再使用add_help=False，保留argparse默认的帮助逻辑，避免手动添加-h带来的冲突
   • 通过parser_a._actions.pop()移除自动添加的-h/--help动作
   • 将这个动作添加到我们自定义的Help dialog分组中，让子命令的帮助信息格式符合你的要求

3. 保留顶级解析器的自定义帮助
   顶级解析器依然使用add_help=False，并手动添加-h/--help到自定义分组，确保顶级帮助的格式与子命令帮助保持一致。

效果验证 #

顶级帮助输出（example -h） #

usage: example [-g] [-h] {a,b} ...
Global arguments:
 -g, --global  A global argument.
Help dialog:
 -h, --help    Show this help message and exit.
Available subcommands:
 {a,b}
 a            Help for sub-command a.
 b            Help for sub-command b.
A very cool program

子命令a的帮助输出（example a -h） #

usage: example a --bar BAR [-h]
Required arguments:
 --bar BAR     Flag bar help
Help dialog:
 -h, --help    Show this help message and exit.

子命令b的帮助输出（example b -h） #

usage: example b --baz BAZ [-h]
Required arguments:
 --baz BAZ     Flag baz help
Optional arguments:
 --tas TAS     Flag tas help
Help dialog:
 -h, --help    Show this help message and exit.

关于conflict_handler的补充 #

你提到的conflict_handler="resolve"其实不是必须的，因为我们通过手动调整帮助动作的分组，已经避免了参数冲突。如果直接手动添加-h同时保留默认帮助，才需要用到冲突处理器，但我们的方案通过复用默认帮助动作并调整分组，既避免了冲突，又保持了argparse的原生帮助逻辑。

内容的提问来源于stack exchange，提问作者José Ferreira