argparse.ArgumentParser 初始化必须指定 prog 和 description；prog 应设为最终命令名（如 mytool），description 用动宾短语概括核心功能；子命令须用 add_subparsers(dest="cmd", required=True) 管理；类型、默认值、formatter_class（如 RawDescriptionHelpFormatter）需显式配置。
argparse.ArgumentParser 的初始化必须指定 prog 和 description
不设 prog 会导致帮助信息里显示错误的脚本名（比如 python script.py 而不是你期望的 mytool），不设 description 则缺失首行概要，用户第一眼无法判断工具用途。尤其在自动化流水线中，其他工程师靠 help 输出快速理解命令语义。
实操建议：
-
prog应设为最终安装后调用的命令名，如mytool，而非__file__ -
description用一句动宾短语说明核心能力，例如"Deploy services from local config" - 避免在
description里塞参数说明——那是add_argument的职责
子命令（subparsers）是 CLI 分层结构的唯一可靠方案
当工具功能超过 3 个独立动作（如 mytool build、mytool push、mytool verify），硬编码 if args.command == "build" 会迅速失控。argparse 的 add_subparsers 不仅提供自动 help 分组，还强制参数归属清晰，避免 --timeout 在不同命令下含义冲突。
常见错误现象：
立即学习“Python免费学习笔记（深入）”；
- 漏掉
required=True导致无子命令时静默失败（Python 3.10+ 默认为False） - 给子解析器设
dest但主解析器没对应add_argument，导致args.cmd不存在 - 子命令参数未设
nargs或type，输入数字被当字符串，后续计算报错
示例关键片段：
subparsers = parser.add_subparsers(dest="cmd", required=True)
build = subparsers.add_parser("build", help="Build service image")
build.add_argument("--tag", type=str, default="latest")
类型转换和默认值必须显式声明，别依赖隐式行为
Python 3.10 的 argparse 对 type=int 等基础类型支持稳定，但对 type=Path 或自定义类仍需手动处理。更危险的是：不设 default 时，缺失参数的值是 None，而 None 参与路径拼接或数值比较极易引发 TypeError 或逻辑跳过。
使用场景提示：
- 文件路径参数务必用
type=Path+default=Path.cwd()，而非字符串拼接 - 布尔开关用
action="store_true"，禁用type=bool—— 它会把任何非空字符串转成True - 枚举值用
choices=["dev", "prod"]，比手动校验更早拦截非法输入
help 文本中的换行和缩进会被 argparse 自动抹平
写多行 help 时直接回车，输出里全变成空格连接。这不是 bug，是 argparse 的格式化策略：它用 textwrap.fill 重排段落。想保留段落结构，必须用 formatter_class=argparse.RawDescriptionHelpFormatter。
性能与兼容性影响：
-
RawDescriptionHelpFormatter仅影响 help 渲染，不改变解析逻辑，无运行时开销 - 若同时需要保留换行又想让选项描述自动折行，改用
argparse.RawTextHelpFormatter（但会牺牲所有自动排版） - 别在 help 字符串里写
\n后又用默认 formatter——那只是白费力气
容易被忽略的地方是：子命令的 help 文本同样受主解析器 formatter_class 控制，不需要单独设置。
