ai

1. argparse 是什么？ #

argparse 是 Python 标准库，用于解析命令行参数，为脚本构建用户友好的 CLI 接口。
相比手动解析 sys.argv，argparse 自动生成 --help、自动校验参数类型和数量。
写任何需要通过命令行运行的 Python 脚本（工具、爬虫、数据处理）时，argparse 是标准选择。
无需安装，Python 3.2+ 内置，直接 import argparse 即可。

对比 sys.argv

# 不推荐：手动解析
# 导入 sys 模块访问命令行参数
import sys
# 检查是否提供了足够的参数
if len(sys.argv) < 2:
    print("错误：请提供文件名")
    # 参数不足时以错误码退出
    sys.exit(1)
# 取第一个位置参数作为文件名
filename = sys.argv[1]
print(f"处理文件：{filename}")

# 推荐：argparse
# 导入 argparse 模块
import argparse
# 创建参数解析器并设置程序描述
parser = argparse.ArgumentParser(description='文件处理工具')
# 添加必需的位置参数 filename
parser.add_argument('filename', help='要处理的文件名')
# 解析命令行参数
args = parser.parse_args()
# 通过 args 对象访问解析结果
print(f"处理文件：{args.filename}")

# 运行脚本并查看自动生成的帮助信息
python script.py --help

2. 前置知识 #

命令行是用户通过键盘输入命令与程序交互的方式，如 python script.py input.txt。
命令行参数分两类：位置参数（按顺序提供，如文件名）和可选参数（以 - 或 -- 开头，如 --verbose）。
解析后的参数通过 args.参数名 访问，argparse 返回的是一个命名空间对象。
Windows 在 CMD 或 PowerShell 中运行，macOS/Linux 在终端中运行，用法相同。

类型	示例	说明
位置参数	`python script.py file.txt`	必须按顺序提供
短选项	`python script.py -v`	单字母，方便输入
长选项	`python script.py --verbose`	可读性好

3. 快速上手 #

argparse 的基本流程固定四步：创建解析器 → 添加参数 → 解析 → 使用。
ArgumentParser(description=...) 中的 description 会显示在 --help 中。
parse_args() 解析 sys.argv，用户输入不合法时自动打印错误和帮助信息并退出。

# 导入 argparse 模块
import argparse

# 创建解析器，description 显示在 --help 中
parser = argparse.ArgumentParser(description='我的第一个 argparse 程序')
# 添加必需的位置参数 name
parser.add_argument('name', help='你的名字')
# 解析命令行传入的参数
args = parser.parse_args()
# 使用解析后的参数
print(f"你好，{args.name}！")

# 传入位置参数 name，输出「你好，张三！」
python hello.py 张三
# 查看帮助信息
python hello.py --help
# 缺少必需参数时会报错并显示帮助
python hello.py

4. 位置参数 #

位置参数没有 - 前缀，必须按定义顺序提供，缺少任何一个都会报错。
多个位置参数按添加顺序依次对应命令行中的值。
适合"主输入"类参数，如输入文件、目标路径等程序运行的核心参数。
参数名会作为 args 对象的属性名，如 add_argument('source') 对应 args.source。

# 导入 argparse
import argparse

# 创建文件复制工具的解析器
parser = argparse.ArgumentParser(description='文件复制工具')
# 第一个位置参数：源文件路径
parser.add_argument('source', help='源文件路径')
# 第二个位置参数：目标文件路径
parser.add_argument('dest', help='目标文件路径')
# 解析命令行参数
args = parser.parse_args()
# 输出复制信息
print(f"从 {args.source} 复制到 {args.dest}")

# 按顺序提供 source 和 dest 两个位置参数
python script.py source.txt dest.txt

5. 可选参数 #

可选参数以 -（短选项）或 --（长选项）开头，可以不提供。
建议同时提供短选项和长选项，如 -v 和 --verbose，方便不同使用习惯。
用 default=值 设置默认值，不提供参数时使用默认值。
用 type=int 等指定类型，argparse 自动将字符串转换为对应类型。
用 action='store_true' 可以让参数变成布尔开关，指定时为 True，未指定时为 False。

# 导入 argparse
import argparse

# 创建解析器
parser = argparse.ArgumentParser(description='文件处理工具')
# 必需的位置参数：文件名
parser.add_argument('filename', help='要处理的文件名')
# 可选参数：详细输出开关（无需传值）
parser.add_argument('-v', '--verbose', action='store_true', help='显示详细输出')
# 可选参数：处理次数，自动转为 int，默认 1
parser.add_argument('-n', '--number', type=int, default=1, help='处理次数（默认：1）')
# 解析参数
args = parser.parse_args()

# 输出基本处理信息
print(f"处理文件：{args.filename}，处理 {args.number} 次")
# 仅在指定 --verbose 时打印
if args.verbose:
    print("详细模式已启用")

# 只提供文件名，普通模式处理 1 次
python script.py file.txt
# 启用详细模式并指定处理 5 次
python script.py file.txt -v -n 5

6. 参数类型 #

命令行传入的值都是字符串，type= 参数让 argparse 自动转换为目标类型。
常用类型：int、float、str（默认，可省略）。
类型转换失败时 argparse 自动报错，无需手动 try/except。
在 add_argument 中直接指定 type=int 即可，解析后 args.number 已是整数。

# 导入 argparse
import argparse

# 创建解析器
parser = argparse.ArgumentParser(description='文件处理工具')
# 位置参数，自动转为整数
parser.add_argument('count', type=int, help='整数')
# 可选参数，自动转为浮点数
parser.add_argument('--price', type=float, help='价格')
# 位置参数，保持字符串（默认类型）
parser.add_argument('name', help='字符串（默认类型）')

args = parser.parse_args()
print(args.count)
print(args.price)
print(args.name)

# 传入整数 count 和浮点数 price
python script.py 10 --price 99.5 zhangsan
# 解析后 args.count 为 int 10，args.price 为 float 99.5，args.name为 str  zhangsan

7. 布尔参数 #

开关型参数用 action='store_true'：命令行出现该选项时为 True，否则为 False。
不需要也不应该给布尔参数传值，如 --debug 而非 --debug true。
action='store_false' 相反：出现选项时为 False，默认 True，常用于 --no-cache 类参数。
项目中 store_true 最为常见，用于 --verbose、--debug、--dry-run 等开关。

# 导入 argparse
import argparse
# 创建解析器
parser = argparse.ArgumentParser(description='文件处理工具')
# 出现 -v/--verbose 时 args.verbose 为 True
parser.add_argument('-v', '--verbose', action='store_true', help='详细输出')
# 出现 -d/--debug 时 args.debug 为 True
parser.add_argument('-d', '--debug', action='store_true', help='调试模式')

# 解析命令行参数
args = parser.parse_args()
# 根据布尔开关执行不同逻辑
if args.verbose:
    print("详细模式")
if args.debug:
    print("调试模式")

python script.py --verbose --debug

8. 多个值与 choices #

nargs='+' 让参数接收一个或多个值，结果是列表，适合多个文件名等场景。
nargs='*' 允许零个或多个值；nargs=2 要求恰好两个值（如坐标 x y）。
choices=[...] 限制参数只能从预定义列表中选择，输入非法值时自动报错。
日常开发中 nargs='+' 和 choices 最为实用，其余 nargs 形式按需查阅。

# 导入 argparse
import argparse

# 创建解析器
parser = argparse.ArgumentParser(description='文件处理工具')
# 接收一个或多个文件路径，结果存入列表
parser.add_argument('files', nargs='+', help='要处理的文件（至少一个）')

# 限制 mode 只能从预定义选项中选择
parser.add_argument('--mode', choices=['read', 'write', 'append'], default='read')

# 解析命令行参数
args = parser.parse_args()
# 打印处理文件和模式
print(f"处理文件: {args.files}")
print(f"模式: {args.mode}")

9. 常见错误与最佳实践 #

缺少必需位置参数时 argparse 自动报错并显示帮助，无需手动检查 len(sys.argv)。
类型错误（如 --number abc）和 choices 非法值也由 argparse 自动处理。
为每个参数写清晰的 help 文字，用户看 --help 就能知道怎么用。
可选参数提供合理 default，布尔开关用 action='store_true'，避免让用户传 true/false 字符串。

9.1 常见错误 #

错误	原因	argparse 行为
缺少位置参数	未提供必需参数	自动报错 + 显示帮助
类型不匹配	`--number abc`	自动报错
choices 非法	`--mode delete`	自动报错并列出可选值

9.2 最佳实践 #

同时提供短选项和长选项：-v / --verbose、-o / --output
参数名语义清晰：--input-file 优于 --f1
为可选参数设置合理默认值，减少用户必传参数数量
description 和 help 写中文说明，降低团队使用门槛

10. 总结 #

argparse 四步流程：创建 ArgumentParser → add_argument → parse_args() → 使用 args.xxx。
核心参数类型：位置参数、可选参数（-/--）、type 类型转换、action='store_true' 布尔开关。
进阶用法：nargs='+' 多值、choices 限制选项、default 默认值。
任何需要命令行参数的 Python 脚本都应使用 argparse，比 sys.argv 更健壮、更专业。

常用 add_argument 参数

参数	说明	示例
`help`	帮助文字	`help='输入文件'`
`type`	类型转换	`type=int`
`default`	默认值	`default=1`
`action`	布尔开关	`action='store_true'`
`nargs`	多个值	`nargs='+'`
`choices`	限制选项	`choices=['a', 'b']`

导航菜单

1. argparse 是什么？ #

2. 前置知识 #

3. 快速上手 #

4. 位置参数 #

5. 可选参数 #

6. 参数类型 #

7. 布尔参数 #

8. 多个值与 choices #

9. 常见错误与最佳实践 #

9.1 常见错误 #

9.2 最佳实践 #

10. 总结 #