argparse 入门：位置参数、选项与自动 help

引言

这是第九章「综合项目：命令行工具」的第 2 篇。第 1 篇我们用手工方式从 sys.argv 切参数，很快会撞上一堵墙：--verbose 是选项还是文件名？参数缺失时谁来打印友好的用法提示？--help 帮助文本谁来维护？全都自己写，工具还没写功能就先写了一堆参数外壳。本篇引入标准库 argparse，把”描述参数”和”解析参数”彻底分工：你只需要声明参数长什么样，切词、报错、usage、--help 全部免费。

本篇讲 argparse 的最小可用闭环：ArgumentParser 三步曲、位置参数与可选参数、dest 与属性名规则、自动生成的 help/usage（全部附本机实测输出）、以及参数解析失败时 SystemExit(2) 的特殊性。第 3 篇在此基础上讲 type= 类型转换、choices、nargs、子命令等进阶设施。前置知识：第 1 篇的 sys.argv 与工程化骨架、第四章第 8 篇《异常处理》里的 BaseException 层次图——本篇的 SystemExit 就生活在那棵树的顶端。

概念与原理

声明式参数描述：argparse 的工作模型

argparse 的核心思想是声明式（declarative）：与”自己写 if 判断 argv”的命令式方式相反，你只描述”程序接受哪些参数、每个参数什么类型什么含义”，其余一切由库代劳。工作模型只有三步：

第一步创建 ArgumentParser 对象——它就是一张”参数登记表”，同时保存程序的描述文字；第二步用 add_argument() 逐条登记参数：每一个参数是一行声明，包含命令行名字、类型、默认值、帮助文本；第三步调用 parse_args() 执行解析，返回一个命名空间对象（argparse.Namespace），所有参数作为它的属性存在，用 args.xxx 访问。

为什么声明式更好？首先是一致性：所有用 argparse 的工具，--help 的排版、错误信息的措辞、退出码约定完全一致，用户零学习成本；其次是免费正确性：缺参数、未知选项、类型不合法这些最容易写错的边界情况，库已经替你处理妥当；最后是免费文档：--help 不是手写的，是从声明里自动生成、永不与代码失同步的。

位置参数与可选参数：两种参数的本质区别

命令行参数只有两个家族。位置参数（positional）按位置含义定：cp 旧文件新文件 里第一个词是源、第二个是目标，换顺序意思就反了。它们在声明时不用 - 前缀，通常必填。可选参数（optional）以 -- 开头，靠名字而非位置识别：git commit --amend 里的 --amend 写在哪里都不影响含义，它明显可省。POSIX 惯例还区分长选项（--verbose，双横线）与短选项（-v，单横线），argparse 允许一个参数同时挂两个名字：add_argument("--name", "-n") 表示二者等价。

可选参数里有一类特殊的开关（用 action="store_true" 声明）：它不消费后面的值，出现即真、缺省即假。--loud 这样的布尔开关不需要”值”，它自身就是值——这是它与 --name 林晓（必须跟随一个值）最大的区别，也是初学最容易搞混的地方。

dest：从命令行名字到 Python 属性名

parse_args() 把每个参数变成 args 上的一个属性，属性名由dest（destination，落脚点）规则决定：取 add_argument 的第一个参数（长选项）去掉 --，把中间的连字符换成下划线。--user-name 的 dest 自动是 user_name，所以访问 args.user_name——而不是 args.user-name，因为 Python 标识符里不允许连字符。若只声明了短选项（-l），dest 就用该字符本身（args.l）。这条规则也能被显式覆盖：add_argument("--user-name", dest="user") 后属性就叫 args.user，适合”命令行名很长、代码里想用短名”的场景。

自动生成的 usage 与 help

parse_args 之外，ArgumentParser 还自动注册了 -h/--help 选项：python 工具.py --help 时打印用法说明并以状态 0 结束。输出的结构分三块：usage: 一行是所有参数的”签名”（方括号 [ ] 表示可省、{a,b} 表示枚举）；然后是 description（创建解析器时传入的整段说明）；最后按”位置参数/选项”两栏列出每个参数与它的 help 文本。prog（usage 里的程序名）默认取自 sys.argv[0] 的文件名——这解释了为什么改了脚本文件名，usage 会跟着变。

参数失败与 SystemExit(2)：argparse 的错误哲学

parse_args() 遇到缺参数、类型错误、未知选项时做两件事：把 usage: 行和错误原因写到标准错误（stderr），然后raise SystemExit(2)。-h/--help 则是 SystemExit(0)。这是 argparse 最值得玩味的设计：参数错误不是一个”返回值”，而是一个进程级事件。

第四章第 8 篇的异常层次图里有完整答案：SystemExit 是 BaseException 的直接子类，不是 Exception 的子类。因此 try/except Exception 拦不住它——这恰恰是正确的：参数错误意味着调用方违反了契约，程序应当带着约定好的退出码 2 立即离开，而不该被业务代码当普通异常吞掉后继续运行。SystemExit 与 KeyboardInterrupt 一样，属于”不该被随意捕获”的例外家族。若确有拦截需求（单元测试、库化封装），必须显式 except SystemExit，异常对象的 code 属性就是退出码。这一设计与第 1 篇的骨架一脉相承：sys.exit 是唯一的退出通道，argparse 只是替你在入口处做了把关。

操作与实现

最小可用：三步曲模板

把下面代码存为 greet.py——这是 argparse 的最小完整示例，两行声明加一行解析：

import argparse

parser = argparse.ArgumentParser(description="打招呼的小工具")
parser.add_argument("name", help="你的名字")
args = parser.parse_args()
print(f"你好，{args.name}！")

第一行创建解析器并登记程序说明；第二行声明一个位置参数 name；第三行解析并得到结果对象。运行：

python greet.py 林晓

你好，林晓！

现在体验”免费午餐”——--help 是自动生成的：

python greet.py --help

usage: greet.py [-h] name

打招呼的小工具

positional arguments:
  name        你的名字

options:
  -h, --help  show this help message and exit

注意三处细节：usage 行的 [-h] 表示 help 可省、name 表示必填的位置参数（无方括号）；“打招呼的小工具”正是 description= 传入的文本；“options” 一栏是 Python 3.10 以来的标准栏目名（更早的版本叫 “optional arguments”）。

缺参数时发生了什么

故意不给参数：

python greet.py

usage: greet.py [-h] name
greet.py: error: the following arguments are required: name

第一行重复 usage 签名，第二行是错误原因；两行都输出到 stderr。程序的退出码呢？这正是 SystemExit(2) 的现场：

python greet.py; echo "退出码: $?"

usage: greet.py [-h] name
greet.py: error: the following arguments are required: name
退出码: 2

错误信息 + 退出码 2 一体发出，与第 1 篇骨架里”用法错误惯例返回 2”正好接轨——只是这次是 argparse 替我们执行的。

可选参数：长选项、短选项与开关

扩展为可选参数版本 greet2.py：--name/-n 带一个值，--loud 是无值开关：

import argparse

parser = argparse.ArgumentParser(description="带可选参数的工具")
parser.add_argument("--name", "-n", default="匿名用户", help="你的名字")
parser.add_argument("--loud", action="store_true", help="用全大写输出")
args = parser.parse_args()

text = args.name
if args.loud:
    text = text.upper()
print(f"你好，{text}！")

python greet2.py --name alice --loud
python greet2.py -n Bob
python greet2.py

你好，ALICE！
你好，Bob！
你好，匿名用户！

三种调用各验证一件事：长选项带值、短选项等价、缺省时命中 default。再看自动 help 如何表现可选参数：

python greet2.py --help

usage: greet2.py [-h] [--name NAME] [--loud]

带可选参数的工具

options:
  -h, --help            show this help message and exit
  --name NAME, -n NAME  你的名字
  --loud                用全大写输出

usage 行里可选参数全部用方括号包裹，说明它们都可省；--loud 没有值槽位（store_true 开关）；NAME 是 argparse 为 --name 自动起的占位符（metavar），可以猜到它期望一个值。

显式 dest：命令行名与属性名解耦

rename.py 演示三个点：长选项 --user-name 自动得到 user_name 属性、显式 dest="user" 覆盖、以及位置参数按声明顺序对应：

import argparse

parser = argparse.ArgumentParser(description="重命名工具")
parser.add_argument("--user-name", dest="user", default="管理员", help="操作者姓名")
parser.add_argument("old", help="旧文件名")
parser.add_argument("new", help="新文件名")
args = parser.parse_args()
print(f"{args.user} 执行重命名: {args.old} -> {args.new}")

注意访问的是 args.user 而不是 args.user_name——这就是 dest 的覆盖效果。运行与帮助：

python rename.py --user-name 林晓 旧名.py 新名.py

林晓 执行重命名: 旧名.py -> 新名.py

python rename.py --help

usage: rename.py [-h] [--user-name USER] old new

重命名工具

positional arguments:
  old               旧文件名
  new               新文件名

options:
  -h, --help        show this help message and exit
  --user-name USER  操作者姓名

usage 行一针见血地区分了两族：[--user-name USER] 可省且带值，old new 必填且按序。位置参数在 help 里按声明顺序罗列，一目了然。

SystemExit 的可捕获性：现场实验

最后验证第四章的异常体系论断。catch_sysexit.py 把 parse_args 包进 try，显式捕获 SystemExit 查看退出码：

import argparse

parser = argparse.ArgumentParser(description="演示 SystemExit 捕获")
parser.add_argument("n", type=int, help="一个整数")

try:
    args = parser.parse_args([])
except SystemExit as e:
    print(f"捕获到 SystemExit，退出码: {e.code}")

python catch_sysexit.py

usage: catch_sysexit.py [-h] n
catch_sysexit.py: error: the following arguments are required: n
捕获到 SystemExit，退出码: 2

实验证实三件事：错误信息照常打印到 stderr；SystemExit 确实可以被显式捕获且 e.code 为 2；捕获后程序继续执行（本示例随后正常结束，退出码回到 0）。把 except SystemExit 换成 except Exception 再跑，异常会直接漏到顶层——因为 SystemExit 不在 Exception 门下，这正是它”特殊”的全部含义。

易错点与陷阱

陷阱一：以 `-` 开头的值被当成选项

--name -x 想传一个以横线开头的值，argparse 会把 -x 认成”又一个选项”，结果选项缺值。本机实测：

python greet2.py --name -x

usage: greet2.py [-h] [--name NAME] [--loud]
greet2.py: error: argument --name/-n: expected one argument

修复方式是用等号形式 --name=-x，实测可正常解析。有趣的细节是：负数例外——--name -1 实测可以正常解析，因为 argparse 内置了”负数字面量”的特例（仅当没有长得像负数的选项字符串时生效）。记住结论即可：非数字的横线开头值必须用 = 形式，否则会被吞成”选项缺失”。

陷阱二：用 except Exception 拦截解析失败

argparse 的失败是 SystemExit 不是 Exception（第四章第 8 篇的层次图里 SystemExit 直接从 BaseException 分叉）。想”捕获参数错误并温柔处理”的代码如果写 except Exception:，一切都接不住，程序照常从 parse_args 退出。需要拦截时写 except SystemExit as e:，并用 e.code 拿到退出码；但也要想清楚：拦截之后程序继续运行，退出码仍是你自己的责任——SystemExit 被吞掉不等于”错误被修复”。

陷阱三：用错属性名，AttributeError

--user-name 的属性是 args.user_name，--out-dir 的属性是 args.out_dir：dest 规则把连字符换成了下划线，且只在第一个长选项上做推导。写 args.user-name 会直接 AttributeError。同理，显式声明过 dest="user" 后还在写 args.user_name，同样拿不到。不确定时先 print(args) 看命名空间里到底有什么，比猜名字快得多。

陷阱四：—help 是”短路出口”，后面的代码不执行

python greet.py --help 时，parse_args 打印帮助后立刻 SystemExit(0)，help 之后的任何初始化代码都不会跑。这不是 bug，但初学常惊讶”帮助打印完程序就结束了”——这正是设计意图：--help 是一次完整的信息查询请求，不是”看一眼再继续”。同理，--help 与真正的选项错误都走 SystemExit 通道，只是状态码不同（0 与 2）。

小结

argparse 把参数解析从”手写 if 链”升级为三段声明：ArgumentParser 建表、add_argument 登记、parse_args 解析出命名空间。位置参数按顺序必填，可选参数靠 -- 识别可自由放置，store_true 是特殊的无值开关；dest 规则把命令行名规范成 Python 属性名（连字符转下划线），也可用 dest= 显式覆盖；--help 与 usage 全部自动生成且与声明永远同步；解析失败时错误进 stderr 并 raise SystemExit(2)——这是继承自 BaseException 的进程级事件，except Exception 拦不住它，这也解释了为何符合约定体系的退出码对工具如此重要。下一篇，把 type= 类型转换、choices、nargs、子命令与互斥组装进同样的三段式里。

练习与思考题

用 argparse 重写第 1 篇的 hello_cli.py：位置参数 name，缺省时的报错提示与手动版有何不同？对比两个版本的 使用说明，哪个更接近 git 这类成熟工具？
为 greet2.py 增加一个 --count 参数打印 N 遍问候（暂不加 type=int）：运行 python greet2.py --count 3 后先 print(type(args.count))，观察它是什么类型——这说明把用户输入当数字使用前必须做什么？（提示：预告第 3 篇的 type=）
思考题：argparse 为什么用 SystemExit(2) 而非”返回错误对象”？如果 parse_args 改成返回 None 表示失败，调用方可能漏掉检查导致什么后果？结合第 1 篇”退出码是显式数据”的结论回答。
实操题：把 catch_sysexit.py 的 except SystemExit 改为 except Exception，重新运行并观察输出与退出码，用第四章的异常层次图解释原因。