为什么使用 argparse？

在 argparse 出现之前，开发者通常手动处理 sys.argv 来解析命令行参数，这种方式虽然可行，但很繁琐，并且需要自己处理各种情况，

• 如何区分位置参数和可选参数？
• 如何为参数添加帮助信息（-h 或 --help）？
• 如何处理参数的类型（如整数、浮点数）？
• 如何设置参数是否必需,以及默认值？

argparse 模块解决了所有这些问题，让你的命令行工具既专业又易用。

argparse 的核心组件

使用 argparse 主要涉及三个核心步骤和四个核心对象：

核心步骤

1. 创建解析器：创建一个 ArgumentParser 对象，它是整个解析过程的入口。
2. 添加参数：使用 add_argument() 方法向解析器中添加你期望从命令行接收的参数。
3. 解析参数：调用 parse_args() 方法来解析命令行的输入，这个方法会返回一个包含所有参数值的对象。

核心对象

1. ArgumentParser 对象：解析器本身，负责管理所有参数和生成帮助信息。
2. add_argument() 方法：用于定义一个或多个命令行参数，这是最关键的部分。
3. 命名空间 对象：parse_args() 的返回值，一个类似字典的对象，属性名是你定义的参数名，属性值是用户提供的参数值。
4. 动作：add_argument() 的 action 参数，定义了当参数在命令行中出现时应该执行的操作（如存储值、计数、布尔开关等）。

一个简单的完整示例

让我们从一个最简单的例子开始,逐步理解每个部分。

# my_script.py
import argparse
# 1. 创建解析器
# description 会在帮助信息的开头显示
parser = argparse.ArgumentParser(description="这是一个简单的计算器程序。")
# 2. 添加参数
# 'x' 和 'y' 是位置参数，用户必须提供
# type=int 指定参数类型为整数
# help 提供该参数的帮助信息
parser.add_argument("x", type=int, help="第一个操作数")
parser.add_argument("y", type=int, help="第二个操作数")
# 'operation' 是一个可选参数，带有一个短选项 '-o' 和一个长选项 '--op'
# choices=['add', 'sub', 'mul', 'div'] 限制了参数的值只能是这四个之一
parser.add_argument("-o", "--operation", choices=['add', 'sub', 'mul', 'div'], 
                    default='add', help="指定操作类型 (默认: add)")
# 3. 解析参数
# 当脚本运行时，parse_args() 会自动从 sys.argv 中解析参数
args = parser.parse_args()
# 4. 使用解析后的参数
print(f"解析到的参数: {args}")
if args.operation == 'add':
    result = args.x + args.y
elif args.operation == 'sub':
    result = args.x - args.y
elif args.operation == 'mul':
    result = args.x * args.y
elif args.operation == 'div':
    result = args.x / args.y
print(f"计算结果: {result}")

如何运行这个脚本？

1. 查看帮助信息

   
   （图片来源网络，侵删）

   $ python my_script.py -h

   输出：

   usage: my_script.py [-h] [-o {add,sub,mul,div}] x y
   这是一个简单的计算器程序。
   positional arguments:
     x                      第一个操作数
     y                      第二个操作数
   options:
     -h, --help             show this help message and exit
     -o {add,sub,mul,div}, --operation {add,sub,mul,div}
                           指定操作类型 (默认: add)

2. 执行加法

   $ python my_script.py 10 20

   输出：

   解析到的参数: Namespace(x=10, y=20, operation='add')
   计算结果: 30

3. 执行乘法

   
   （图片来源网络，侵删）

   $ python my_script.py 10 20 -o mul

   输出：

   解析到的参数: Namespace(x=10, y=20, operation='mul')
   计算结果: 200

4. 提供无效的操作类型

   $ python my_script.py 10 20 -o power

   输出：

   usage: my_script.py [-h] [-o {add,sub,mul,div}] x y
   my_script.py: error: argument -o/--operation: invalid choice: 'power' (choose from 'add', 'sub', 'mul', 'div')

   argparse 自动为你处理了错误！

add_argument() 的常用参数

add_argument() 是 argparse 的灵魂，下面是它最常用的一些参数：

基本参数

• name or flags：
  • 位置参数：直接写参数名，如 "filename"。
  • 可选参数：以 开头的短选项（如 "-v"）和/或以 开头的长选项（如 "--verbose"）。
• action：定义参数的行为，这是最重要的参数之一。
  • 'store' (默认): 将参数值存储下来。
  • 'store_true' / 'store_false': 用于布尔标志，如果出现，则存储 True / False，通常用于开关选项。
  • 'count': 计算参数出现的次数。-vv 会被计为 2。
  • 'append': 将参数值添加到一个列表中，可以多次使用该选项。
  • 'append_const': 将一个预定义的常量添加到列表中。
  • 'help': 打印帮助信息后退出。
  • 'version': 打印版本信息后退出。
• nargs：指定一个参数可以接受的值的数量。
  • 0 或 1 个值，如果值不存在，则使用 const 或 default。
  • 0 个或多个值，结果会是一个列表。
  • 1 个或多个值，结果会是一个列表，如果未提供，会报错。
  • 一个整数：确切的值的数量。nargs=2 需要两个值。
• const：action 或 nargs 为 时使用的常量值。
• default：如果参数未在命令行中出现，使用的默认值。
• type：将参数值转换为指定类型，如 int, float, str，甚至可以是一个自定义的函数。
• choices：限制参数值只能是给定的几个选项之一。
• required：对于可选参数，设置为 True 可以使其成为必需的。
• help：参数的简短描述。
• metavar：在帮助信息中显示的参数名称，通常用于自定义输出格式。

action 参数详解示例

import argparse
parser = argparse.ArgumentParser()
# 1. store_true: 布尔开关
parser.add_argument("-v", "--verbose", action="store_true", help="启用详细输出")
# 2. count: 计数
parser.add_argument("-q", "--quiet", action="count", default=0, help="静默模式，可多次使用")
# 3. append: 将值追加到列表
parser.add_argument("--file", action="append", help="要处理的文件列表")
# 4. 自定义类型函数
def check_positive(value):
    ivalue = int(value)
    if ivalue <= 0:
        raise argparse.ArgumentTypeError(f"{value} 必须是一个正整数")
    return ivalue
parser.add_argument("--port", type=check_positive, help="端口号，必须为正整数")
args = parser.parse_args()
print(f"Verbose: {args.verbose}")
print(f"Quiet level: {args.quiet}")
print(f"Files: {args.file}")
print(f"Port: {args.port}")

运行示例：

$ python script.py --verbose --file data1.txt --file data2.txt --port 8080 -qq
Verbose: True
Quiet level: 2
Files: ['data1.txt', 'data2.txt']
Port: 8080

高级特性

互斥参数组

某些参数是互斥的,用户只能选择其中一个。--input 和 --output 不能同时是必需的。

group = parser.add_mutually_exclusive_group()
group.add_argument("--input", help="输入文件路径")
group.add_argument("--output", help="输出文件路径")

如果用户同时指定了 --input 和 --output，argparse 会报错。

必需参数组

可以定义一组参数,其中至少有一个必须出现。

group = parser.add_argument_group('必需参数')
group.add_argument("--host", help="服务器主机名")
group.add_argument("--port", type=int, help="服务器端口")

这个 group 本身不是必需的，但你可以通过逻辑检查 args.host 和 args.port 是否至少有一个存在。

子解析器

如果你的命令行工具有多种不同的操作模式（类似于 git 的 commit, push, pull 等），子解析器非常有用。

import argparse
# 主解析器
parser = argparse.ArgumentParser(description="一个多功能工具。")
subparsers = parser.add_subparsers(dest="command", help="可用命令")
# 'greet' 子命令
parser_greet = subparsers.add_parser("greet", help="向用户问好")
parser_greet.add_argument("name", help="要问候的用户名")
# 'calculate' 子命令
parser_calculate = subparsers.add_parser("calculate", help="执行一个计算")
parser_calculate.add_argument("x", type=int)
parser_calculate.add_argument("y", type=int)
parser_calculate.add_argument("-o", "--operation", default="add", choices=['add', 'sub'])
args = parser.parse_args()
if args.command == "greet":
    print(f"你好, {args.name}!")
elif args.command == "calculate":
    # ... 计算逻辑 ...
    print(f"计算 {args.x} 和 {args.y}...")

运行示例：

$ python tool.py greet Alice
你好, Alice!
$ python tool.py calculate 10 5 -o sub
计算 10 和 5...

最佳实践

1. 始终提供帮助信息：为每个参数编写清晰、简洁的 help 文本。
2. 使用长短选项：为重要的可选参数同时提供短选项（如 -v）和长选项（如 --verbose），方便用户输入。
3. 设置合理的默认值：为可选参数提供有意义的默认值，减少用户的输入。
4. 验证输入：利用 type 或 choices 来限制参数的取值范围，避免无效输入导致程序出错。
5. 使用子解析器：当你的工具有多种不同功能时，使用子解析器可以让命令结构更清晰（如 git commit, docker run）。

argparse 模块是 Python 开发者必备的工具之一，它将你从繁琐的命令行参数解析工作中解放出来，让你专注于核心业务逻辑，通过掌握 ArgumentParser、add_argument() 和各种 action，你可以轻松创建出功能强大、用户友好的命令行应用程序。