Python optparse.OptionGroup 怎样把旧 CLI 帮助选项分组

旧 CLI 的参数越来越多时，最稳妥的整理方式是保留原来的 OptionParser 解析入口，只把不常用或同一业务域的选项移到 optparse.OptionGroup。创建组时传入主解析器和组标题，再用 parser.add_option_group(group) 注册；这样改变的是帮助文本的层次，短选项、长选项和解析结果仍然沿用旧逻辑。

官方地址：https://docs.python.org/3.14/library/optparse.html#grouping-options

先区分公共选项和专题选项

分组前不要按“代码写在哪个函数里”划分，而要按用户查看帮助页时的决策路径划分。像 --config、--verbose 这类所有场景都会用到的参数可以留在默认的 Options 区域；输入输出、调试、迁移兼容等只在特定任务出现的选项，更适合放进独立组。

下面的示例把输入输出和调试参数分开。示例只负责说明对象关系，不代表已经截取某个终端的真实输出：

from optparse import OptionGroup, OptionParser

parser = OptionParser(usage="%prog [options] source")
# 公共参数保持在默认 Options 区域，避免用户找不到入口开关。
parser.add_option("-v", "--verbose", action="store_true", dest="verbose",
                  help="显示必要的处理信息")

io_group = OptionGroup(parser, "输入输出选项",
                       "控制源文件读取和结果写出。")
# 组内只放输入输出任务需要的参数，帮助页会形成独立小节。
io_group.add_option("-o", "--output", dest="output",
                    help="指定结果文件")
io_group.add_option("--encoding", dest="encoding", default="utf-8",
                    help="指定文本编码，默认 utf-8")

debug_group = OptionGroup(parser, "调试选项")
# 调试开关与正常业务参数分开，减少默认帮助页的视觉噪声。
debug_group.add_option("--trace", action="store_true", dest="trace",
                       help="输出阶段性诊断信息")

# 只有挂回主解析器，组才会出现在帮助页并参与选项解析。
parser.add_option_group(io_group)
parser.add_option_group(debug_group)

这里的关键不是把参数复制到另一个解析器，而是让每个组继续共享同一个 OptionParser。因此旧代码读取的 options.output、options.trace 不需要改名。

用注册顺序控制帮助页层次

OptionGroup 的标题和描述决定小节的可读性，add_option_group() 的调用顺序则决定这些小节在帮助页中的先后。建议先注册用户最常用的专题组，再注册低频调试组；不要在不同初始化函数里无意间重复注册同一组。

需要动态组装帮助页时，可以把组注册集中在一个函数里，并按照固定列表逐个添加。这样后续维护者只需看这一处，就能知道帮助页的顶层顺序。

def register_help_groups(parser):
    # 固定注册顺序，避免不同初始化路径改变帮助页布局。
    groups = [build_io_group(parser), build_debug_group(parser)]
    for group in groups:
        # 每个组只注册一次，保持解析器的选项集合唯一。
        parser.add_option_group(group)

    # 返回解析器，便于旧的启动函数继续调用 parse_args()。
    return parser

分组不生效时按归属检查

如果帮助页仍然把选项列在默认 Options 区域，先检查它是否调用了 parser.add_option() 而不是 group.add_option()。如果组标题完全不见，通常是遗漏了 parser.add_option_group(group)。如果帮助页顺序变化，则重点检查是否有多个初始化路径重复注册或条件分支改变了注册次序。

可以用 get_option_group() 做一条轻量的结构检查。它返回选项所在的组；公共选项没有专题组时返回 None。这比只盯着最终帮助文本更快定位问题：

def check_group(parser, option_name):
    # 用完整的短选项或长选项查询，避免把显示文本当作键名。
    group = parser.get_option_group(option_name)
    if group is None:
        # None 表示该选项没有归属到 OptionGroup，可能是公共参数或注册遗漏。
        return "默认 Options 或尚未分组"
    # title 是组的识别信息，适合放入启动阶段的诊断日志。
    return group.title

print(check_group(parser, "--trace"))

最后再用旧 CLI 的真实参数做回归：检查 parse_args() 仍能得到原来的属性，确认新增组没有改变默认值、类型转换和错误提示。分组只服务帮助页组织，不负责互斥约束，也不会自动把参数变成子命令。

常见问题

OptionGroup 会改变命令行参数的解析方式吗？

不会。它仍然使用同一个 OptionParser，主要改变帮助页的组织方式；只要选项定义没有改动，解析结果可以保持不变。

为什么创建了 OptionGroup 但帮助页没有标题？

最常见原因是漏掉 parser.add_option_group(group)，或者创建的组对象没有被当前启动路径注册到主解析器。

如何让某个组显示在另一个组前面？

调整 parser.add_option_group() 的调用顺序，并把组的注册集中到一个初始化函数；不要依赖字典遍历或条件分支的偶然顺序。