Python的argparse模块
一、argparse 简介
argparse 是 Python 标准库中的一个模块，用于解析命令行参数。当脚本需要通过 python script.py <参数> 的方式接收用户输入时，argparse 提供了结构化的方式来定义、解析和校验这些参数。
在没有 argparse 的情况下，开发者通常使用 sys.argv 获取命令行参数：
import sys
print(sys.argv)
这种方式存在明显局限：参数类型需要手动转换、缺少参数时报错不友好、无法自动生成帮助文档、不支持 --name value 这类命名参数。而 argparse 解决了所有这些问题。
二、第一个 argparse 程序
import argparse
parser = argparse.ArgumentParser(description="打招呼脚本")
parser.add_argument("name")
args = parser.parse_args()
print(f"Hello, {args.name}!")
运行：
python hello.py Alice
输出：
Hello, Alice!
执行 python hello.py --help 可以看到自动生成的帮助信息：
usage: hello.py [-h] name
打招呼脚本
positional arguments:
name
optional arguments:
-h, --help show this help message and exit
三、位置参数
位置参数是必须传入的参数，按位置顺序解析。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("name")
parser.add_argument("age", type=int)
args = parser.parse_args()
print(f"{args.name} is {args.age} years old")
运行：
python script.py Alice 25
输出：
Alice is 25 years old
type=int 告诉 argparse 将输入自动转换为整数类型。如果未传入 age 或传入非数字值，argparse 会自动报错并退出。
四、可选参数
可选参数以 - 或 -- 开头，可以传入也可以不传入。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--name", default="Guest")
args = parser.parse_args()
print(f"Hello, {args.name}!")
运行结果对比：
| 命令 | 输出 |
|---|---|
python script.py |
Hello, Guest! |
python script.py --name Alice |
Hello, Alice! |
可以同时定义短参数和长参数：
parser.add_argument("-n", "--name", default="Guest")
此时 -n 和 --name 等价。
五、action="store_true"
action="store_true" 表示：该参数不需要值，只要在命令行中出现，其值就为 True，不出现则为 False。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--debug", action="store_true")
args = parser.parse_args()
print(f"debug mode: {args.debug}")
运行结果对比：
| 命令 | 输出 |
|---|---|
python script.py |
debug mode: False |
python script.py --debug |
debug mode: True |
这种模式常用于开关型参数，例如调试模式、静默模式、干跑模式等。
对应的 action="store_false" 则相反：出现时为 False，不出现时为 True。
六、参数配置选项
argparse 提供了多个配置选项来控制参数行为。
type – 类型转换
parser.add_argument("--port", type=int)
parser.add_argument("--ratio", type=float)
default – 默认值
parser.add_argument("--timeout", type=int, default=30)
未传入该参数时，值为 30。
help – 帮助说明
parser.add_argument("--output", help="output file path")
该说明会出现在 --help 的输出中。
required – 强制必传
可选参数默认不是必须的，可以通过 required=True 强制要求传入：
parser.add_argument("--token", required=True)
choices – 限定取值范围
parser.add_argument("--env", choices=["dev", "staging", "prod"])
传入不在列表中的值会自动报错。
七、args 对象的本质
parser.parse_args() 返回一个 argparse.Namespace 对象，所有解析后的参数都作为该对象的属性存在。
import argparse
parser = argparse.ArgumentParser()
parser.add_argument("--name")
parser.add_argument("--dry-run", action="store_true")
args = parser.parse_args()
print(type(args))
print(args)
运行：
python script.py --name Alice --dry-run
输出：
<class 'argparse.Namespace'>
Namespace(name='Alice', dry_run=True)
属性名的生成规则如下：
| 参数定义 | args 中的属性名 |
|---|---|
"name" |
args.name |
"--name" |
args.name |
"--dry-run" |
args.dry_run |
"-n", "--name" |
args.name（优先使用长参数名） |
注意：--dry-run 中的 - 会被自动替换为 _，因为 Python 变量名中不能包含 -。
八、综合实战示例
下面是一个结合了参数解析和实际操作的完整示例，实现了一个带命令行参数的 Git 克隆脚本：
import argparse
import subprocess
def main():
parser = argparse.ArgumentParser(description="Git 仓库克隆工具")
parser.add_argument("repo_url", help="Git 仓库地址")
parser.add_argument("-b", "--branch", default="main", help="分支名")
parser.add_argument("-d", "--dir", default="./repo", help="目标目录")
parser.add_argument("--dry-run", action="store_true", help="仅打印命令不执行")
parser.add_argument("--debug", action="store_true", help="调试模式")
args = parser.parse_args()
if args.debug:
print(f"Parsed arguments: {args}")
cmd = ["git", "clone", "-b", args.branch, args.repo_url, args.dir]
if args.dry_run:
print(f"Command: {' '.join(cmd)}")
else:
subprocess.run(cmd, check=True)
print("Operation completed.")
if __name__ == "__main__":
main()
运行示例：
python clone.py https://gitlab.com/group/repo.git -b develop -d ./tmp --dry-run
九、总结
| 概念 | 要点 |
|---|---|
| 位置参数 | 必须传入，按顺序解析，无需 -- 前缀 |
| 可选参数 | 以 - 或 -- 开头，可不传 |
store_true |
出现即为 True，不出现为 False |
type |
自动进行类型转换 |
default |
未传参数时的默认值 |
choices |
限制参数取值范围 |
args 对象 |
argparse.Namespace 类型，参数名自动映射为属性 |
argparse 是编写命令行工具的标准方案，适用于从简单脚本到复杂 CLI 应用的各类场景。
浙公网安备 33010602011771号