Python argparse让位置参数与子命令独立解析的实现方法

我在把一个只有几个参数的脚本改成多命令 CLI 时，最容易踩的坑不是参数类型，而是位置参数的归属：tool run target 里的 target 应该由 run 解析，还是被顶层解析器提前拿走？稳定的做法是把全局上下文放进选项，把每个命令自己的 positional 只定义在对应的 subparser 中。

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

先把三层参数边界分清楚

一个命令行工具可以先按下面的形状设计：顶层是程序级选项，中间是命令名，最后是某个命令的参数。

尤其要避免在顶层放一个 nargs="*" 或 nargs="+" 的 positional，再期待它自动把后面的单词让给子命令。它们都在争夺同一段输入，帮助信息和错误位置会变得不直观。需要跨命令传递的值，用带名字的选项表达，用户也更容易读懂。

用 subparser 让位置参数各归其位

下面这个最小结构把 run 和 show 的目标分别交给两个子解析器。代码中的注释只解释关键边界，实际业务函数可以替换成项目自己的实现。

import argparse


def run_command(args):
    # run 只读取自己的 target，同时继承顶层的 workspace。
    print(f"run {args.target} in {args.workspace}")


def show_command(args):
    # show 的 name 与 run 的 target 互不复用，避免语义混淆。
    print(f"show {args.name} in {args.workspace}")


parser = argparse.ArgumentParser(description="处理项目目标")
# 这是跨子命令的上下文，因此使用有名字的选项而不是顶层 positional。
parser.add_argument("--workspace", default=".", help="项目工作目录")
subparsers = parser.add_subparsers(dest="command", required=True)

run_parser = subparsers.add_parser("run", help="执行一个目标")
run_parser.add_argument("target", help="要执行的目标名")
run_parser.set_defaults(handler=run_command)

show_parser = subparsers.add_parser("show", help="查看一个目标")
show_parser.add_argument("name", help="要查看的目标名")
show_parser.set_defaults(handler=show_command)

args = parser.parse_args()
# 先由 subparser 选择 handler，再让 handler 消费自己的字段。
args.handler(args)

因此，python tool.py --workspace ./demo run build 得到的是 command=run、target=build；换成 show config 时，结果字段变为 command=show、name=config。两条路径共享 workspace，却不会互相读取位置参数。

解析顺序决定了哪些写法可靠

命令名本身是 subparser 的选择值，通常应当放在全局选项之后、命令目标之前。推荐把接口固定成：

# 全局选项 + 子命令 + 子命令位置参数
python tool.py --workspace ./demo run build
python tool.py --workspace ./demo show config

如果某个参数只服务于 run，就定义在 run_parser 上，例如 --retry；不要为了“统一”把它提升到顶层。反过来，所有命令都需要的配置才留在主解析器。这样生成的帮助文本也会按层级显示，用户能直接判断参数属于哪里。

还要注意 nargs：单个目标使用默认值即可，多个目标使用 nargs="+" 时，应确认它不会吞掉本来应作为命令名的输入。一个简单规则是：命令名之前不要放可变数量 positional；可变列表尽量放在已经确定的子命令内部。

常见问题与边界处理

为什么缺少子命令时看起来像位置参数错误？

因为子命令选择本身就是顶层 parser 的一个位置入口。设置 required=True 后，缺少 run 或 show 会在顶层尽早失败，帮助信息会列出允许的命令。

两个子命令可以使用同名 positional 吗？

可以。它们属于不同的 Namespace 语义域；但如果业务分发代码需要统一读取字段，最好统一命名，或者在 handler 内做明确转换，不要依赖隐式字段存在。

什么时候才适合顶层 positional？

只有当它对所有命令都有同一含义、且数量固定时才考虑。只要它可能和子命令名混淆，就改用选项或把它下沉到具体 subparser。

把 positional 看成“已经确定上下文后的局部输入”，把 option 看成“跨命令的命名配置”，argparse 的层级就会清楚很多。先固定这条边界，再扩展别名、类型转换和错误提示，后续维护成本会低得多。