设计 Python 命令行工具：argparse、main() 与退出码

目标

构建一个可供 shell 脚本、CI 任务和智能体驱动的命令行工具：参数行为可预测、帮助文本本身即文档、退出码结构化、输出流干净整洁。

前提条件

一个带有 pyproject.toml 的软件包（参见打包相关文章），其业务逻辑位于可导入的函数中，与参数处理部分分离。

步骤

1. 编写 def main(argv: list[str] | None = None) -> int，在其中构建解析器、解析 argv（缺省时回退到 sys.argv[1:]）并返回退出码。将其注册为 [project.scripts] tool = "pkg.cli:main"，并加入 if __name__ == "__main__": sys.exit(main())。这样测试代码就可以调用 main(["--flag", "x"])，并对返回值和捕获到的输出做断言。
2. 用 prog、description 以及包含示例的 epilog 来构建解析器。使用 type= 转换器（int、pathlib.Path，或一个抛出 ArgumentTypeError 的函数），使非法值被报告为用法错误；对封闭取值集合使用 choices=；多命令工具则使用 add_subparsers(dest="command", required=True)。
3. 遵循 sys.exit 文档所述的惯例：Unix 程序通常用 2 表示命令行语法错误，用 1 表示其他所有错误，0 表示成功。argparse 在参数非法时已经会以状态码 2 退出。仅当 --help 中已对其加以说明时，才从 sysexits.h 中采用更多代码（EX_USAGE 64、EX_NOINPUT 66、EX_UNAVAILABLE 69、EX_TEMPFAIL 75）。
4. 将结果写入 stdout，将诊断信息写入 stderr。当输出会被其他程序消费时提供 --json 选项，并用 --verbose/--quiet 来设置日志级别，而不是在代码中到处散布 print。
5. 在 main 中捕获预期内的失败（FileNotFoundError、连接错误、业务领域异常），向 stderr 打印一行信息并返回文档中说明的退出码；让预期之外的异常继续向上传播，以保留回溯信息和退出码 1。
6. 处理 KeyboardInterrupt 时先做清理，再返回 130，与 shell 惯例的“128 加信号编号”保持一致；并在 stdout 上吞掉 BrokenPipeError，使 tool | head 能安静地结束。
7. 让帮助信息如实可靠：用 metavar 提供可读的占位符，用 ArgumentDefaultsHelpFormatter 使默认值显示出来，并编写测试确认 --help 以 0 退出。

预期结果

tool --help 记录了完整的接口；tool --bad; echo $? 打印出 2；输入有问题时会向 stderr 打印一行信息并返回文档中说明的退出码；调用方无需解析文本，仅凭退出码即可分支处理。

限制与验证基础

sys.exit 文档指出，大多数系统要求退出码落在 0 到 127 的范围内；超出该范围的值会与 shell 的信号编码方式相冲突。设置 exit_on_error=False 会让解析器抛出 ArgumentError 而不是直接退出，这适合嵌入使用场景，但需要自行处理错误。上述惯例均依据所引用的文档；本文未声称任何可用性方面的实测数据。

按下 Ctrl-C 后的退出方式

shell 判断一次中断是否也应该终止外层脚本，依据的是子进程是否死于 SIGINT，而不是读取退出码。因此，一个捕获 KeyboardInterrupt 并返回 130 的工具，在 shell 看来就像是一次正常退出，于是 for f in *; do tool "$f"; done 会在每次 Ctrl-C 之后继续处理下一个文件。正确做法是先完成清理，再以未处理中断本应导致的方式结束进程（自 3.8 版本起，Python 自身也是这样做的）：

except KeyboardInterrupt:
    cleanup()
    signal.signal(signal.SIGINT, signal.SIG_DFL)
    os.kill(os.getpid(), signal.SIGINT)

$? 仍然读到 130，而等待该进程的父进程看到的是一次信号致死。只有在明确知道调用方仅读取退出码的情况下，才保留使用 return 130 这种写法。