argparse

argparse 把命令行文本解析为 Python 对象，并自动生成帮助信息。它适合脚本、批处理工具和命令行应用。

最小程序

import argparse

parser = argparse.ArgumentParser(description="统计文件行数")
parser.add_argument("path", help="要读取的文件")
parser.add_argument("-v", "--verbose", action="store_true", help="显示详细信息")
args = parser.parse_args()
print(args.path, args.verbose)

运行 python count.py -h 会显示用法、参数说明和示例。位置参数按顺序传入，选项参数通常使用 --长名称，可同时提供短名称。

类型、默认值和选择

parser.add_argument("-n", "--number", type=int, default=10)
parser.add_argument("--format", choices=["text", "json"], default="text")
parser.add_argument("--ratio", type=float, required=True)
parser.add_argument("files", nargs="+", help="至少一个文件")

type 在解析阶段转换并校验；转换失败会得到友好的错误。常见 nargs：? 可选一个、* 任意多个、+ 至少一个。required=True 适用于选项参数，但不宜滥用，优先设计合理默认值。

布尔开关与互斥参数

parser.add_argument("--dry-run", action="store_true")
parser.add_argument("--tag", action="append", default=[])
mode = parser.add_mutually_exclusive_group(required=True)
mode.add_argument("--fast", action="store_true")
mode.add_argument("--safe", action="store_true")

store_true 出现即为 True；append 可重复传入并收集列表。互斥组保证用户不能同时选择冲突选项。

子命令

parser = argparse.ArgumentParser()
subparsers = parser.add_subparsers(dest="command", required=True)

add = subparsers.add_parser("add", help="新增记录")
add.add_argument("text")
list_cmd = subparsers.add_parser("list", help="列出记录")
args = parser.parse_args()
if args.command == "add":
    print(f"新增：{args.text}")
else:
    print("列出记录")

大型程序可为每个子命令绑定函数：add.set_defaults(func=handle_add)，解析后调用 args.func(args)，避免堆积 if 分支。

自定义校验与配置建议

def positive(value):
    number = int(value)
    if number <= 0:
        raise argparse.ArgumentTypeError("必须是正整数")
    return number

parser.add_argument("--workers", type=positive, default=1)

解析器默认遇到错误会打印帮助并以状态码 2 退出。库代码不要直接调用 parse_args()，应把解析放在 main() 中，便于测试；需要解析列表时使用 parse_args(["..."])。