为什么使用 argparse？
在 argparse 出现之前，开发者通常使用 sys.argv 来手动处理命令行参数，这虽然可行，但存在很多问题：
（图片来源网络，侵删）
- 代码繁琐：需要手动解析参数列表，处理短选项（
-f）和长选项（--file）。 - 错误处理困难：难以优雅地处理用户输入错误（如缺少参数、类型错误等）。
- 帮助信息不统一：需要手动编写
-h或--help的输出信息。
argparse 解决了所有这些问题，它提供了：
- 自动生成帮助信息：根据你定义的参数，自动生成
-h或--help的输出。 - 类型检查和转换：自动将参数转换为指定的数据类型（如整数、浮点数）。
- 错误提示：当用户输入无效参数时，程序会自动报错并退出。
- 丰富的参数类型：支持位置参数、可选参数、布尔标志、数量参数等。
argparse 的基本使用步骤
使用 argparse 主要遵循以下四个步骤：
- 导入模块：
import argparse - 创建解析器对象：
parser = argparse.ArgumentParser(description='...') - 添加参数：使用
parser.add_argument()定义程序接受的命令行参数。 - 解析参数：使用
args = parser.parse_args()解析命令行输入，并将结果存储在args对象中。
一个简单的例子
让我们从一个最简单的例子开始,逐步理解。
目标：编写一个脚本，接受一个文件名和一个数字，并打印它们。
（图片来源网络，侵删）
代码 (my_script.py):
import argparse
# 1. 创建解析器对象
# description 参数会在帮助信息的开头显示
parser = argparse.ArgumentParser(description="一个简单的脚本示例。")
# 2. 添加参数
# 添加一个位置参数 'filename'
# type: 指定参数类型
# help: 为该参数提供帮助信息
parser.add_argument("filename", type=str, help="要处理的文件名")
# 添加一个可选参数 '--count' 或 '-c'
# action='store_true': 表示这是一个布尔标志，如果出现该参数，则值为 True，否则为 False
parser.add_argument("-c", "--count", action="store_true", help="是否显示计数")
# 添加一个带值的有可选参数 '--number' 或 '-n'
# type: 指定参数类型
# default: 如果用户不提供该参数，则使用默认值
parser.add_argument("-n", "--number", type=int, default=1, help="一个数字，默认为1")
# 3. 解析参数
# parse_args() 会从 sys.argv 中解析参数
args = parser.parse_args()
# 4. 使用解析后的参数
print(f"文件名: {args.filename}")
print(f"是否计数: {args.count}")
print(f"数字: {args.number}")
如何运行这个脚本？
-
查看帮助信息 在命令行中运行
python my_script.py -h或python my_script.py --help：$ python my_script.py -h usage: my_script.py [-h] [-c] [-n NUMBER] filename 一个简单的脚本示例。 positional arguments: filename 要处理的文件名 options: -h, --help show this help message and exit -c, --count 是否显示计数 -n NUMBER, --number NUMBER 一个数字，默认为1你可以看到
argparse自动为我们生成了清晰的使用说明。 -
不带任何参数运行 会报错，因为
filename是一个位置参数，是必需的。
（图片来源网络，侵删）$ python my_script.py usage: my_script.py [-h] [-c] [-n NUMBER] filename my_script.py: error: the following arguments are required: filename
-
提供必需的参数
$ python my_script.py data.txt 文件名: data.txt 是否计数: False 数字: 1
-
使用可选参数
$ python my_script.py data.txt -c -n 5 文件名: data.txt 是否计数: True 数字: 5
add_argument() 的核心参数详解
add_argument() 是 argparse 的核心，它的参数定义了命令行参数的行为。
1 参数名称
- 位置参数：直接提供一个字符串，如
parser.add_argument("filename")，这些参数是必需的，其顺序由用户在命令行中提供的位置决定。 - 可选参数：以 或 开头，如
parser.add_argument("-f", "--file")，用户可以选择是否提供，短选项（如-f）是可选的。
2 action：参数如何处理
这是 action 参数最常用的几个值：
-
'store'(默认行为): 将参数的值存储下来。parser.add_argument("--name", action="store", default="Guest") # 运行: python script.py --name Alice -> args.name = "Alice" # 运行: python script.py -> args.name = "Guest" -
'store_true'/'store_false': 用于布尔标志，如果参数出现，则存储True/False，否则存储默认值False/True。parser.add_argument("-v", "--verbose", action="store_true", help="启用详细模式") # 运行: python script.py -v -> args.verbose = True # 运行: python script.py -> args.verbose = False -
'store_const': 存储一个预定义的常量，常量由const参数指定。parser.add_argument("--mode", action="store_const", const="DEBUG", default="INFO") # 运行: python script.py --mode -> args.mode = "DEBUG" # 运行: python script.py -> args.mode = "INFO" -
'append': 将参数的值添加到一个列表中，可以多次使用该参数。parser.add_argument("--file", action="append", default=[]) # 运行: python script.py --file a.txt --file b.txt -> args.file = ['a.txt', 'b.txt'] -
'count': 计算参数出现的次数，常用于增加日志级别等。parser.add_argument("-v", "--verbose", action="count", default=0) # 运行: python script.py -v -> args.verbose = 1 # 运行: python script.py -vv -> args.verbose = 2 -
'help'(默认): 打印帮助信息并退出。 -
'version': 打印版本信息并退出，需要配合version参数使用。parser.add_argument("--version", action="version", version='%(prog)s 1.0') # 运行: python script.py --version -> 输出: my_script.py 1.0
3 type：参数类型
argparse 默认将所有参数视为字符串，你可以用 type 参数来指定类型，argparse 会自动进行转换。
parser.add_argument("width", type=int)
parser.add_argument("height", type=float)
parser.add_argument("files", type=argparse.FileType('r')) # 可以直接打开文件
如果转换失败（例如输入非数字给 int），argparse 会自动报错。
4 default：默认值
如果用户没有提供该可选参数,则使用这个默认值。
parser.add_argument("--port", type=int, default=8080)
5 required：是否必需
将可选参数设为必需的,这对于那些虽然以 开头但逻辑上必须提供的参数很有用。
parser.add_argument("--config", type=str, required=True, help="配置文件的路径")
6 help 和 metavar
help: 参数的帮助信息，会在-h中显示。metavar: 在帮助信息中显示的参数名称，默认是参数的全大写形式，当你有多个参数时，metavar可以让帮助信息更清晰。
# 默认帮助信息会显示: output_file input_file
# parser.add_argument("input_file")
# parser.add_argument("output_file")
# 使用 metavar 可以自定义
parser.add_argument("input_file", metavar="源文件")
parser.add_argument("output_file", metavar="目标文件")
# 帮助信息会显示: 源文件 目标文件
7 choices：限制参数值
参数的值必须是 choices 列表中的一个。
parser.add_argument("--log-level", choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'], default='INFO')
# 运行: python script.py --log-level DEBUG -> 正确
# 运行: python script.py --log-level FATAL -> 错误: error: argument --log-level: invalid choice: 'FATAL' (choose from 'DEBUG', 'INFO', 'WARNING', 'ERROR')
高级用法
1 互斥参数组
某些参数是互斥的,用户只能选择其中一个。--encrypt 和 --decrypt 不能同时使用。
import argparse
parser = argparse.ArgumentParser()
# 创建互斥组
group = parser.add_mutually_exclusive_group()
# 向组中添加参数
group.add_argument("--encrypt", action="store_true", help="加密模式")
group.add_argument("--decrypt", action="store_true", help="解密模式")
parser.add_argument("filename", help="要处理的文件")
args = parser.parse_args()
if args.encrypt:
print(f"正在加密文件 {args.filename}...")
elif args.decrypt:
print(f"正在解密文件 {args.filename}...")
else:
print("请选择加密或解密模式。")
如果同时提供 --encrypt 和 --decrypt，argparse 会报错。
2 可选参数组
你可以将相关的参数分组,使帮助信息更有条理。
import argparse
parser = argparse.ArgumentParser(description="一个功能丰富的脚本")
# 创建参数组
group1 = parser.add_argument_group('网络设置')
group1.add_argument("--host", default="localhost", help="服务器主机")
group1.add_argument("--port", type=int, default=8080, help="服务器端口")
group2 = parser.add_argument_group('输出选项')
group2.add_argument("-v", "--verbose", action="store_true", help="启用详细输出")
group2.add_argument("-q", "--quiet", action="store_true", help="静默模式")
args = parser.parse_args()
运行 python script.py -h 会看到参数被清晰地分成了两组。
完整综合示例
下面是一个综合运用了上述知识点的完整例子。
目标：一个模拟的文件备份工具，可以指定源目录、目标目录，并可以选择是否压缩、是否显示进度。
代码 (backup_tool.py):
import argparse
import os
import sys
def main():
# 1. 创建解析器
parser = argparse.ArgumentParser(
description="一个简单的文件备份工具。",
formatter_class=argparse.ArgumentDefaultsHelpFormatter # 显示默认值
)
# 2. 添加参数
# 位置参数：源目录
parser.add_argument(
"source",
type=str,
help="源目录的路径"
)
# 可选参数：目标目录
parser.add_argument(
"-d", "--destination",
type=str,
default="./backup",
help="备份目标目录的路径"
)
# 互斥的布尔标志：压缩或显示进度
group = parser.add_mutually_exclusive_group()
group.add_argument(
"-z", "--zip",
action="store_true",
help="将备份结果压缩为 .zip 文件"
)
group.add_argument(
"-p", "--progress",
action="store_true",
help="显示备份进度"
)
# 带值的选择：日志级别
parser.add_argument(
"--log-level",
choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'],
default='INFO',
help="设置日志级别"
)
# 3. 解析参数
args = parser.parse_args()
# 4. 使用参数并执行逻辑
print("--- 备份工具配置 ---")
print(f"源目录: {os.path.abspath(args.source)}")
print(f"目标目录: {os.path.abspath(args.destination)}")
print(f"压缩模式: {'是' if args.zip else '否'}")
print(f"显示进度: {'是' if args.progress else '否'}")
print(f"日志级别: {args.log_level}")
print("---------------------")
# 这里是实际的备份逻辑...
if not os.path.isdir(args.source):
print(f"错误: 源目录 '{args.source}' 不存在!", file=sys.stderr)
sys.exit(1)
if args.progress:
print("开始备份... (模拟进度)")
# 模拟进度
for i in range(1, 6):
print(f"进度: {i * 20}%")
print("备份完成!")
if __name__ == "__main__":
main()
如何运行这个综合示例？
# 查看帮助信息（注意默认值和分组）
$ python backup_tool.py -h
# 基本备份
$ python backup_tool.py my_project
# 指定目标目录和压缩模式
$ python backup_tool.py my_project -d ./my_backups -z
# 显示进度，并设置日志级别
$ python backup_tool.py my_project -p --log-level DEBUG
# 尝试使用互斥参数（会报错）
$ python backup_tool.py my_project -z -p
usage: backup_tool.py [-h] [-d DESTINATION] [-z] [-p] [--log-level {DEBUG,INFO,WARNING,ERROR}] source
backup_tool.py: error: argument -p/--progress: not allowed with argument -z/--zip
argparse 是 Python 开发者必备的工具，通过掌握其核心概念——创建解析器、添加参数、解析参数，你可以轻松地为你的脚本创建专业、健壮且用户友好的命令行界面。-h 是你最好的朋友，在不确定时，随时用它来查看参数的帮助信息。
