Python 命令行参数：argparse 模块的使用

在日常开发中，我们经常需要编写支持命令行参数的工具。比如指定输入文件、设置输出路径、开启调试模式等。Python 标准库中的 argparse 模块提供了强大且易用的命令行参数解析功能，完全可以满足这类需求。

这篇文章将带你从零开始学习 argparse，掌握其核心用法。

理解命令行参数

在运行 Python 脚本时，可以在脚本名后面附加一些信息，这些信息就是命令行参数。

python script.py input.txt output.txt --verbose

在上面的命令中：

• input.txt 和 output.txt 是位置参数，它们的含义由参数在命令中的位置决定。
• --verbose 是可选参数，通常用于开启某个功能。

argparse 的基本用法

第一步：创建解析器

使用 argparse.ArgumentParser() 创建解析器对象。这个对象负责处理所有命令行参数。

import argparse

parser = argparse.ArgumentParser(description="处理文件的工具")

description 参数会在帮助信息中显示脚本的简要说明。

第二步：定义参数

通过 add_argument() 方法添加参数。有两种主要类型：位置参数和可选参数。

# 添加位置参数
parser.add_argument('input_file', help='输入文件路径')

# 添加可选参数
parser.add_argument('--output', '-o', help='输出文件路径')
parser.add_argument('--verbose', '-v', action='store_true', help='显示详细信息')

关键参数说明：

第三步：解析参数

调用 parse_args() 方法执行解析。它会读取 sys.argv 并返回命名空间对象。

args = parser.parse_args()

第四步：使用参数

通过命名空间对象的属性访问参数值。

print(f"输入文件: {args.input_file}")
print(f"输出文件: {args.output}")
print(f"详细模式: {args.verbose}")

完整示例

下面是一个完整的脚本，展示了 argparse 的典型用法：

#!/usr/bin/env python3
import argparse

def main():
    parser = argparse.ArgumentParser(description='文件处理工具')
    parser.add_argument('input_file', help='输入文件路径')
    parser.add_argument('--output', '-o', default='output.txt',
                       help='输出文件路径（默认: output.txt）')
    parser.add_argument('--verbose', '-v', action='store_true',
                       help='开启详细输出')
    parser.add_argument('--count', '-c', type=int, default=1,
                       help='处理次数（默认: 1）')

    args = parser.parse_args()

    if args.verbose:
        print(f"配置参数:")
        print(f"  输入: {args.input_file}")
        print(f"  输出: {args.output}")
        print(f"  次数: {args.count}")

    # 实际处理逻辑
    print(f"正在处理: {args.input_file}")

if __name__ == '__main__':
    main()

保存为 tool.py 后，运行测试：

# 显示帮助信息
python tool.py --help

# 基本使用
python tool.py data.csv

# 指定输出文件
python tool.py data.csv --output result.csv

# 使用短选项和 verbose
python tool.py data.csv -o result.csv -v

# 传递数值参数
python tool.py data.csv -c 5

常用参数类型

argparse 支持多种参数类型，确保命令行输入被正确转换。

字符串类型（默认）

parser.add_argument('--name', help='用户名')

整数类型

parser.add_argument('--port', type=int, help='端口号')
parser.add_argument('--count', type=int, default=10, help='数量')

如果用户输入的不是合法整数，程序会报错并提示。

浮点类型

parser.add_argument('--rate', type=float, help='速率值')

文件路径类型

使用 argparse.FileType('r') 可以自动验证文件是否存在并打开：

parser.add_argument('--config', type=argparse.FileType('r'),
                   help='配置文件路径')

choices 限制取值范围

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

设置默认值

使用 default 参数为可选参数指定默认值：

parser.add_argument('--port', type=int, default=8080, help='端口号')
parser.add_argument('--debug', action='store_true', default=False,
                   help='调试模式')

对于必填的位置参数，不应设置默认值。如果希望某个可选参数必须有值，使用 required=True：

parser.add_argument('--api-key', required=True, help='API 密钥')

互斥参数

当某些参数不能同时使用时，add_mutually_exclusive_group() 创建互斥组：

group = parser.add_mutually_exclusive_group()
group.add_argument('--text', help='输入文本')
group.add_argument('--file', help='输入文件')

parser.add_argument('--output', help='输出方式')

这样用户只能选择 --text 或 --file 中的一个。

自定义帮助信息

修改帮助信息的格式

parser = argparse.ArgumentParser(
    description='数据处理工具',
    formatter_class=argparse.RawDescriptionHelpFormatter,
    epilog='''
示例:
  %(prog)s input.csv --output result.txt
  %(prog)s --help
'''
)

RawDescriptionHelpFormatter 允许在 description 中使用换行符。epilog 用于添加使用示例。

隐藏某些参数

如果某些参数仅供内部使用但又必须定义，可以通过 help=argparse.SUPPRESS 隐藏：

parser.add_argument('--debug', help=argparse.SUPPRESS)

这样 --help 不会显示该参数，但程序仍然可以正常使用。

子命令支持

复杂的命令行工具通常支持子命令（如 git commit、docker run）。argparse 通过 subparsers 实现：

parser = argparse.ArgumentParser(description='管理工具')
subparsers = parser.add_subparsers(title='命令', dest='command')

# 添加子命令 'start'
start_parser = subparsers.add_parser('start', help='启动服务')
start_parser.add_argument('--port', type=int, default=8080)

# 添加子命令 'stop'
stop_parser = subparsers.add_parser('stop', help='停止服务')

# 添加子命令 'restart'
restart_parser = subparsers.add_parser('restart', help='重启服务')
restart_parser.add_argument('--force', action='store_true')

args = parser.parse_args()

print(f"命令: {args.command}")
if hasattr(args, 'port'):
    print(f"端口: {args.port}")
if hasattr(args, 'force'):
    print(f"强制重启: {args.force}")

使用方式：

python manager.py start --port 9000
python manager.py stop
python manager.py restart --force

实际应用场景示例

批量文件重命名工具

#!/usr/bin/env python3
import argparse
import os
import re

def main():
    parser = argparse.ArgumentParser(description='批量文件重命名工具')
    parser.add_argument('directory', help='目标目录')
    parser.add_argument('--pattern', '-p', required=True,
                       help='文件名匹配模式（正则表达式）')
    parser.add_argument('--replace', '-r', default='',
                       help='替换为的字符串')
    parser.add_argument('--dry-run', '-n', action='store_true',
                       help='仅预览，不实际执行')

    args = parser.parse_args()

    pattern = re.compile(args.pattern)

    for filename in os.listdir(args.directory):
        if pattern.search(filename):
            new_name = pattern.sub(args.replace, filename)
            if args.dry_run:
                print(f"将重命名: {filename} -> {new_name}")
            else:
                os.rename(
                    os.path.join(args.directory, filename),
                    os.path.join(args.directory, new_name)
                )
                print(f"已重命名: {filename}")

if __name__ == '__main__':
    main()

HTTP 服务器配置工具

#!/usr/bin/env python3
import argparse

def main():
    parser = argparse.ArgumentParser(description='简易 HTTP 服务器')
    parser.add_argument('--host', default='127.0.0.1',
                       help='绑定地址（默认: 127.0.0.1）')
    parser.add_argument('--port', type=int, required=True,
                       help='监听端口（必填）')
    parser.add_argument('--directory', '-d', default='.',
                       help='服务根目录（默认: 当前目录）')
    parser.add_argument('--threads', type=int, default=4,
                       help='工作线程数（默认: 4）')
    parser.add_argument('--cache', action='store_true',
                       help='启用缓存')
    parser.add_argument('--verbose', '-v', action='count', default=0,
                       help='详细输出，可多次使用增加级别')

    args = parser.parse_args()

    print("服务器配置:")
    print(f"  地址: {args.host}")
    print(f"  端口: {args.port}")
    print(f"  根目录: {args.directory}")
    print(f"  线程数: {args.threads}")
    print(f"  缓存: {'开启' if args.cache else '关闭'}")
    print(f"  日志级别: {args.verbose}")

if __name__ == '__main__':
    main()

注意 --verbose 使用了 action='count'，这样每次使用 -v 都会让值加 1。

最佳实践总结

1. 始终提供 help 描述：这不仅帮助用户理解参数用途，还能自动生成完整的帮助文档。

2. 合理使用短选项：常用参数提供短选项（如 -v、-o、-c）可以显著提升使用体验。

3. 设置合适的类型：对数值类参数使用 type=int 或 type=float，让 argparse 自动完成类型检查和转换。

4. 提供合理的默认值：可选参数应该有明确的默认值，让脚本在不加参数时也能正常运行。

5. 使用 action 参数：store_true、store_false、count 等 action 可以简化开关类参数的处理。

6. 添加 dry-run 模式：对于可能造成不可逆操作（删除、重命名等）的工具，提供预览模式让用户确认。

掌握 argparse 的这些用法，你就能轻松构建出专业、易用的命令行工具。