Python 命令行参数：argparse 模块的详细配置

在编写 Python 脚本时，命令行参数是与用户交互的重要方式。无论是传递文件路径、设置选项，还是接收配置值，命令行参数都能让程序更加灵活和易用。Python 标准库中的 argparse 模块提供了强大且优雅的参数解析能力，是处理命令行输入的首选方案。

一、argparse 模块的核心概念

argparse 模块能够自动生成帮助信息、处理参数类型验证、还能在用户输入错误时给出友好的提示。使用它之前，需要理解三个基本概念：

参数解析器（ArgumentParser） 是整个机制的入口点，负责统筹所有参数的定义和解析工作。位置参数（Positional Arguments） 是必须提供的参数，解析时根据位置识别，比如 python script.py input.txt 中的 input.txt。可选参数（Optional Arguments） 以短横线或双短横线开头，可以省略，比如 -o output.txt 或 --output output.txt。

二、快速上手：第一个命令行程序

步骤 1：导入模块并创建解析器

import argparse

parser = argparse.ArgumentParser(description='处理文件的简单脚本')

ArgumentParser 的 description 参数会在帮助信息开头显示程序的用途说明。

步骤 2：添加参数

parser.add_argument('input_file', help='输入文件的路径')
parser.add_argument('-o', '--output', help='输出文件的路径')

add_argument 方法用于定义参数。第一个参数是参数名称，位置参数直接写名字，可选参数需要以 - 或 -- 开头。help 参数用于描述参数的用途，会显示在帮助信息中。

步骤 3：解析参数

args = parser.parse_args()

parse_args() 方法会读取 sys.argv 中的命令行输入，将解析结果存储到一个命名空间对象中。通过对象的属性即可访问参数值。

步骤 4：使用参数

print(f'输入文件: {args.input_file}')
if args.output:
    print(f'输出文件: {args.output}')

将上述代码整合到一个完整脚本中：

#!/usr/bin/env python3
import argparse

parser = argparse.ArgumentParser(description='处理文件的简单脚本')
parser.add_argument('input_file', help='输入文件的路径')
parser.add_argument('-o', '--output', help='输出文件的路径')

args = parser.parse_args()

print(f'输入文件: {args.input_file}')
if args.output:
    print(f'输出文件: {args.output}')

运行脚本并查看效果：

$ python script.py data.txt
输入文件: data.txt

$ python script.py data.txt -o result.txt
输入文件: data.txt
输出文件: result.txt

$ python script.py --help
usage: script.py [-h] [-o OUTPUT] input_file

处理文件的简单脚本

positional arguments:
  input_file      输入文件的路径

options:
  -h, --help      show this help message and exit
  -o OUTPUT, --output OUTPUT
                  输出文件的路径
```

---

## 三、参数的精细化配置

### 设置参数的默认值

某些参数可能有合理的默认值，此时可以使用 `default` 参数：

```python
parser.add_argument('--port', type=int, default=8080, help='服务端口号')
parser.add_argument('--verbose', action='store_true', help='启用详细输出')
```

`action='store_true'` 是一种特殊用法：当用户指定该参数时，值为 `True`；未指定时，值为 `False`。适用于开关类型的选项。

### 参数类型转换

`argparse` 会自动将用户输入的字符串转换为指定类型。如果类型转换失败，会抛出错误并提示用户。常用类型包括：

| 类型 | 说明 | 示例 |
|------|------|------|
| `int` | 整数 | `42` |
| `float` | 浮点数 | `3.14` |
| `str` | 字符串（默认） | `"hello"` |
| `bool` | 布尔值 | 需要配合 `type=int` 使用 |

对于文件路径，可以结合 `argparse.FileType` 实现自动文件对象创建：

```python
from argparse import FileType

parser.add_argument('--config', type=FileType('r'), help='配置文件')
args = parser.read_config()
```

### 限制参数的可选值

当参数只能取特定值时，使用 `choices` 参数进行限制：

```python
parser.add_argument('--level', choices=['low', 'medium', 'high'], 
                    default='medium', help='日志级别')
```

用户在命令行输入 `--level critical` 时，程序会报错并提示可选值范围。

### 互斥参数组

当某些参数不能同时使用时，需要将它们放入互斥组：

```python
group = parser.add_mutually_exclusive_group()
group.add_argument('--encrypt', action='store_true', help='启用加密')
group.add_argument('--decrypt', action='store_true', help='启用解密')
```

这样用户就无法同时使用 `--encrypt` 和 `--decrypt`。

---

## 四、父子命令：处理复杂命令行工具

大型工具通常支持子命令，比如 `git commit`、`git push`。`argparse` 通过 `subparsers` 支持这一模式：

```python
import argparse

parser = argparse.ArgumentParser(prog='filetool', 
                                 description='文件处理工具')
subparsers = parser.add_subparsers(title='命令', dest='command',
                                   help='可用的命令')

# 添加 'compress' 子命令
compress_parser = subparsers.add_parser('compress', help='压缩文件')
compress_parser.add_argument('input', help='输入文件')
compress_parser.add_argument('-o', '--output', help='输出文件')

# 添加 'extract' 子命令
extract_parser = subparsers.add_parser('extract', help='解压文件')
extract_parser.add_argument('archive', help='归档文件')
extract_parser.add_argument('-d', '--dir', help='目标目录')

args = parser.parse_args()

if args.command == 'compress':
    print(f'压缩 {args.input} 到 {args.output}')
elif args.command == 'extract':
    print(f'解压 {args.archive} 到 {args.dir}')
```

使用效果如下：

```bash
$ python filetool.py compress data.txt -o data.zip
压缩 data.txt 到 data.zip

$ python filetool.py extract data.zip -d /tmp
解压 data.zip 到 /tmp
```

---

## 五、定制化帮助与错误处理

### 自定义帮助格式

`argparse` 自动生成的帮助信息可能不符合你的需求，可以通过参数进行调整：

```python
parser = argparse.ArgumentParser(
    prog='mytool',
    description='我的工具',
    epilog='更多信息请访问 https://example.com',
    formatter_class=argparse.ArgumentDefaultsHelpFormatter  # 显示默认值
)
```

`ArgumentDefaultsHelpFormatter` 会自动在帮助信息中显示每个参数的默认值，让用户一目了然。

### 自定义参数行为

对于复杂场景，可以定义 `type` 函数或 `action` 类来自定义参数处理逻辑：

```python
def valid_port(string):
    value = int(string)
    if value < 1 or value > 65535:
        raise argparse.ArgumentTypeError(f'端口号必须在 1-65535 之间')
    return value

parser.add_argument('--port', type=valid_port, help='服务端口')
```

### 拦截错误消息

当解析失败时，`argparse` 会自动打印错误信息并退出。如果需要自定义行为，可以捕获 `SystemExit` 异常：

```python
try:
    args = parser.parse_args()
except SystemExit:
    # 自定义处理逻辑
    pass
```

---

## 六、综合实战：完整的命令行工具

下面是一个综合运用上述技巧的完整示例，实现了一个支持多选项的文件处理工具：

```python
#!/usr/bin/env python3
import argparse
import sys

def create_parser():
    parser = argparse.ArgumentParser(
        prog='fileproc',
        description='文件处理工具 - 转换、压缩、验证',
        epilog='示例: fileproc.py convert input.txt -f json -o output.json',
        formatter_class=argparse.ArgumentDefaultsHelpFormatter
    )
    
    subparsers = parser.add_subparsers(
        title='命令',
        dest='command',
        required=True,
        help='要执行的操作'
    )
    
    # convert 命令
    convert_parser = subparsers.add_parser('convert', help='转换文件格式')
    convert_parser.add_argument('input', help='输入文件')
    convert_parser.add_argument('-f', '--format', 
                                choices=['json', 'yaml', 'csv'],
                                required=True, help='目标格式')
    convert_parser.add_argument('-o', '--output', help='输出文件')
    convert_parser.add_argument('-v', '--verbose',
                                action='store_true', help='详细输出')
    
    # compress 命令
    compress_parser = subparsers.add_parser('compress', help='压缩文件')
    compress_parser.add_argument('input', nargs='+', help='要压缩的文件')
    compress_parser.add_argument('-o', '--output', default='archive.zip',
                                 help='输出归档文件名')
    compress_parser.add_argument('--method', choices=['zip', 'tar', 'gztar'],
                                 default='zip', help='压缩方法')
    
    # verify 命令
    verify_parser = subparsers.add_parser('verify', help='验证文件完整性')
    verify_parser.add_argument('files', nargs='+', help='待验证的文件')
    verify_parser.add_argument('--algo', choices=['md5', 'sha256'],
                               default='sha256', help='校验算法')
    
    return parser

def handle_convert(args):
    print(f'转换 {args.input} 到 {args.format} 格式')
    if args.output:
        print(f'输出到 {args.output}')
    if args.verbose:
        print('详细模式已启用')

def handle_compress(args):
    print(f'使用 {args.method} 方法压缩 {len(args.input)} 个文件')
    print(f'输出到 {args.output}')

def handle_verify(args):
    print(f'使用 {args.algo} 算法验证 {len(args.files)} 个文件')

def main():
    parser = create_parser()
    args = parser.parse_args()
    
    if args.command == 'convert':
        handle_convert(args)
    elif args.command == 'compress':
        handle_compress(args)
    elif args.command == 'verify':
        handle_verify(args)

if __name__ == '__main__':
    main()
```

测试这个工具：

```bash
$ python fileproc.py convert data.csv -f json -o data.json
转换 data.csv 到 json 格式
输出到 data.json

$ python fileproc.py compress file1.txt file2.txt -o backup.zip
使用 zip 方法压缩 2 个文件
输出到 backup.zip

$ python fileproc.py verify file1.txt file2.txt --algo md5
使用 md5 算法验证 2 个文件

$ python fileproc.py --help
usage: fileproc [-h] command ...

文件处理工具 - 转换、压缩、验证

positional arguments:
  command     要执行的操作

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

示例: fileproc.py convert input.txt -f json -o output.json

命令:
  convert     转换文件格式
  compress    压缩文件
  verify      验证文件完整性

七、最佳实践总结

在实际项目中，建议遵循以下原则：始终为每个参数编写清晰的帮助说明，这不仅帮助他人理解工具用法，还能让用户通过 --help 快速上手。为用户提供合理的默认值，减少必须手动指定的参数数量。使用互斥组和子命令来组织复杂功能，保持命令行界面的清晰和一致性。在关键参数上实现类型验证，防止无效输入导致的程序错误。

掌握 argparse 模块后，你就能为自己的 Python 工具添加专业、友好的命令行界面，让程序的使用体验大幅提升。