argparse 是命令行接口契约工具，非装饰器；nargs 值需慎用，如 '*' 必须置末尾；子命令应独立定义并设 dest；type 应为校验+转换函数；help 是 api 文档核心，需全覆盖且格式清晰。

argparse 不是“优雅”的装饰，而是命令行接口的契约工具——用错地方或乱设参数，反而让脚本更难维护、更难调试。

为什么 add_argument 的 nargs 值总让人踩坑

最常见的误用是把 nargs='*' 当成“可选多个参数”的万能解，结果发现它会吞掉后续所有参数（包括本该是其他选项的），甚至让 --help 显示混乱。

• nargs='*'：匹配 0 个或多个，但必须放在参数列表末尾，且不能和 nargs='+' 或位置参数混用
• nargs='+'：至少 1 个，适合强制要求输入文件列表，比如 python script.py --files a.txt b.txt c.txt
• nargs=2：明确要两个值，如 --range 10 20，解析后是 [10, 20]，不是元组也不是字符串拼接
• 如果参数带 default 且 nargs 不为 '?'，记得显式设 const（尤其配合 action='store_const' 时）

子命令（subparsers）不是炫技，而是避免写一堆 if arg.cmd == 'xxx'

当脚本承担多个职责（如 deploy、rollback、status），硬编码分支逻辑会让 --help 失效、参数校验松散、错误提示模糊。

python 查询技能

查询客流数据，输出JSON格式，可直接导入Bitable等可视化工具

下载

• 每个子命令应有自己的 add_parser()，并独立调用 add_argument()，不要复用主 parser 的参数
• 务必给子命令设置 dest（如 subparsers.add_parser('deploy', dest='cmd')），否则无法在 args.cmd 中拿到命令名
• 子命令不支持全局 add_argument(..., action='store_true') 自动透传，需显式在每个子 parser 中添加或通过 set_defaults() 统一注入
• 别忘了调用 parser.set_defaults(func=...) 绑定执行函数，而不是靠 if args.cmd == 'x' 手动分发

type 参数不是类型转换器，而是验证+预处理入口

type=int 看似简单，但它会在解析阶段抛出 ArgumentTypeError，而这个异常默认被 argparse 吞掉、只打印 usage。你真正需要的是可控的校验逻辑。

• 用自定义函数替代内置类型：例如 type=valid_port，函数内 raise argparse.ArgumentTypeError('port must be 1024–65535')
• type 函数接收原始字符串，返回转换后值（如 Path 对象、datetime 实例），不要在其中做 IO 或网络请求
• 避免用 type=lambda x: x.strip()，它无法提供有意义的错误信息；改用显式函数 + help 描述
• 如果需同时做类型转换和范围检查，优先封装进 type 函数，而非依赖 action 或后续代码校验

help 文本不是可有可无的注释，而是用户第一眼看到的 API 文档

很多脚本的 --help 输出全是 optional arguments: 和空行，因为开发者把 help 当成“补充说明”，而不是接口契约的一部分。

• 每个 add_argument() 都应有 help，哪怕只有一句话；缺失时 argparse 会显示 None 或空白
• 用 metavar 控制 help 中的占位符名（如 metavar='FILE' → --config FILE），别让它默认显示大写的参数名
• 长帮助文本中换行会被压缩成空格，如需保留格式，用 formatter_class=argparse.RawDescriptionHelpFormatter
• epilog 和 description 支持 %(prog)s 占位符，比硬编码脚本名更健壮

最常被忽略的其实是 allow_abbrev=False —— 默认开启缩写（--ver 匹配 --version），但在多命令、多选项场景下极易引发歧义，上线前务必关掉。

Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！