Python 3.14 argparse 默认程序名怎么变化：模块启动方式、帮助文本与脚本迁移

同一个命令行解析器，直接执行脚本、用 python -m 启动模块，帮助信息里的第一行可能并不一样。Python 3.14 调整了 argparse.ArgumentParser 在没有显式传入 prog 时的默认程序名，让帮助文本更贴近解释器实际找到入口代码的方式；但这也意味着依赖旧标题的快照测试和使用说明需要重新核对。

先看一个容易被忽略的变化：usage 第一行也属于接口

很多命令行工具的测试只断言 args 中的字段，却把 --help 和错误信息当成“展示层”。实际上，用户复制帮助文本、脚本抓取错误首行、文档测试比对快照时，第一行的程序名就是可见接口。

Python 3.14 的官方说明把这次调整放在 argparse 改进中：ArgumentParser 的默认程序名会反映解释器被要求查找 __main__ 模块代码的方式。只要没有覆盖 prog，启动入口就可能影响下面这行的内容：

usage: tool.py [-h] {check,export} ...

这里真正需要关注的不是某个固定字符串，而是“谁负责决定名称”。3.14 之前，默认值更多依赖 sys.argv[0] 的传统表现；3.14 则把启动语义纳入推导。

脚本、模块和包入口分别会暴露什么

可以用一个最小解析器做验证，代码故意不传 prog，只观察帮助文本的 usage 行：

import argparse

parser = argparse.ArgumentParser(description="检查输入文件")
parser.add_argument("path")
parser.parse_args(["--help"])

把文件直接交给解释器时，入口名称通常接近脚本路径；把相同逻辑放进包内并用 python -m 包.模块 启动时，帮助文本会更接近模块调用方式。包入口再通过 python -m 包名 运行，读者看到的名称又可能落在包名上。

这个变化最适合用在“同一套代码有多个启动入口”的工具上：帮助文本能够提示用户当前实际调用的路径。它不会替你处理参数别名、子命令设计，也不会改变 parse_args() 的返回对象。

什么时候应该显式设置 prog

如果你的命令文档写的是 acme-check，但用户可以通过 python -m acme.tools 启动它，那么帮助标题最好不要随入口漂移。显式设置 prog 是最直接的兼容门禁：

parser = argparse.ArgumentParser(
    prog="acme-check",
    description="检查输入文件"
)

这样做不会禁止用户使用 -m，只是把对外显示名称固定下来。安装脚本、README、shell 补全和帮助快照可以围绕同一个名字维护，避免升级 Python 后只因为第一行变化就产生大量无意义差异。

反过来，如果工具主要供内部开发者通过多个模块入口调试，默认行为反而有价值：它把真实调用路径暴露出来，排查“到底运行了哪一个模块”时更直观。这里别急着全局替换成显式 prog，先确认名称是不是公共契约。

升级时按三处验收，不要只改快照

先比对 --help 的 usage 和 description

分别用脚本和模块入口执行 --help，记录第一行、选项顺序和描述文本。若只是不希望入口名变化，优先添加 prog；不要为了让快照通过而在测试中截掉第一行。

再检查错误输出是否被文档引用

对一个不存在的子命令运行解析器，错误首行同样会带程序名。CI 如果把这段输出写入工单或文档，迁移时要同步更新示例，并确认没有把内部绝对路径暴露给用户。

最后确认打包入口和手工入口

至少验收一次 python tool.py、一次 python -m package.module，如果项目提供 console script，再验收安装后的命令。三者的名字可以不同，但必须是有意设计的结果。

常见问题

Python 3.14 会改变参数解析结果吗？

默认程序名的调整主要影响帮助和错误文本，不会改变已经声明的参数如何进入 Namespace。仍应运行现有参数测试，尤其是自定义 formatter 或子解析器场景。

显式设置 prog 会影响实际启动命令吗？

不会。prog 只是解析器展示和错误信息使用的名称，实际仍由 shell、解释器或打包入口决定。

为什么模块启动时不直接写死脚本名？

因为模块入口未必对应一个独立脚本文件。按启动方式推导名称能让帮助信息更贴近用户真正执行的命令；如果产品需要统一名称，再显式覆盖即可。

把变化变成一条清晰的迁移规则

Python 3.14 的这项改动提醒我们：命令行帮助不是装饰，而是工具契约的一部分。内部调试工具可以保留默认推导，让入口信息自然显现；对外发布的 CLI 则应显式设置 prog，再用脚本、模块和打包命令各跑一遍帮助与错误输出。这样升级后出现的差异就能被解释，而不是靠删除快照断言来掩盖。