Python argparse 子命令怎么共享公共参数

用 argparse 做备份工具时，命令往往会拆成 backup、restore 等子命令。路径、配置文件、日志级别这类参数又希望每个子命令都能使用，于是问题变成：Python argparse 子命令怎么共享公共参数？最稳妥的做法是单独创建一个公共父解析器，再通过 parents 传给每个子解析器。

公共参数放在父解析器，子命令只补充自己的参数；父解析器要先完成定义，并关闭自己的帮助选项，否则很容易出现参数位置不对或 -h/--help 冲突。

官方地址：https://docs.python.org/3/library/argparse.html

先判断公共参数应该出现在哪里

很多“共享失败”其实不是共享机制失效，而是调用位置和定义位置混在了一起。若参数加在主解析器上，调用通常写成 tool --config app.toml backup；若参数来自父解析器并被并入子命令，调用应写成 tool backup --config app.toml。两种写法都能成立，但不要一边按前者输入，一边只把参数定义给后者。

公共参数为什么要放进独立父解析器

下面用一个原创的备份 CLI 演示。父解析器只定义可复用字段，不负责单独解析，也不应该再创建一套独立帮助选项。parents 会把父解析器中已有的参数动作并入子解析器，因此公共字段会和子命令自己的字段一起进入同一个 Namespace。

import argparse

# 父解析器只承载公共参数，避免和子解析器重复注册 -h。
common = argparse.ArgumentParser(add_help=False)
common.add_argument("--config", default="app.toml", help="配置文件路径")
common.add_argument("--verbose", action="store_true", help="输出详细日志")

# 主解析器负责识别命令，公共参数由子解析器通过 parents 复用。
parser = argparse.ArgumentParser(prog="tool")
subparsers = parser.add_subparsers(dest="command", required=True)

backup = subparsers.add_parser("backup", parents=[common], help="创建备份")
backup.add_argument("--source", required=True, help="待备份目录")

restore = subparsers.add_parser("restore", parents=[common], help="恢复备份")
restore.add_argument("--archive", required=True, help="备份文件")

args = parser.parse_args()
print(args)

这里有一个容易忽略的细节：父解析器必须在传入 parents 之前完成初始化。如果先构造子解析器，之后才执行 common.add_argument()，新参数不会追补到已经创建的子解析器中。需要变更公共参数时，重新构造相关解析器最安全。

让公共参数和子命令处理函数汇合

实际项目不应在入口处堆积大量 if args.command。可以让每个子解析器通过 set_defaults(func=...) 绑定处理函数，解析结束后统一调用。这样公共参数仍然只写一次，而备份和恢复各自保留专属字段。

def run_backup(args):
    # 备份函数同时读取公共 config/verbose 和专属 source。
    print(f"backup: {args.source}, config={args.config}, verbose={args.verbose}")


def run_restore(args):
    # 恢复函数读取同名公共字段，但只使用自己的 archive。
    print(f"restore: {args.archive}, config={args.config}, verbose={args.verbose}")


# 绑定处理函数；解析结果仍是一个 Namespace。
backup.set_defaults(func=run_backup)
restore.set_defaults(func=run_restore)
args = parser.parse_args()
args.func(args)

这段写法的检查重点不是打印内容，而是字段是否完整：执行 tool backup --source data/ --config prod.toml 时，应能在同一个对象里拿到 command、source、config、verbose 和 func。恢复命令则把 source 换成 archive。

三个常见坑怎么定位

1. 帮助参数冲突：父解析器默认也会添加 -h/--help，子解析器再合并时就可能重复注册。公共父解析器使用 add_help=False，把帮助显示交给最终的主解析器或子解析器。
2. 参数位置错误：父解析器的参数属于子命令，所以要放在 backup 或 restore 后面；若必须放前面，就把它定义在主解析器。
3. 后加参数不生效：parents 不是运行时引用，而是构造时收集已有动作。把所有 add_argument() 放在创建子解析器之前。

可以用三组命令做快速复查：分别执行 tool backup --help、tool restore --help 和一条带完整公共参数的实际调用。两份帮助中都出现公共选项、各自只出现专属选项，且处理函数没有读取不存在的字段，说明结构基本正确。

argparse 子命令共享参数常见问题

公共参数能不能直接复制到每个子命令？

可以，但长期维护容易出现默认值、类型或帮助文案不一致。参数稳定且确实公共时，父解析器更适合；只有少量差异时，才考虑在子解析器中明确覆盖。

主解析器和父解析器应该二选一吗？

不必。主解析器负责命令入口及真正位于子命令前的选项，父解析器负责被多个子命令复用的选项，两者边界清楚即可。

为什么修改了 common 却看不到新参数？

因为子解析器创建时已经复制了父解析器的参数动作。把公共参数定义完整后再构造子解析器，或统一封装解析器创建过程。