R / Richie全部文章 ↑

Python · 3 分钟阅读

`argparse`：解析命令行参数

目录

argparse 是 Python 标准库 的命令行参数解析器：自动生成 --help、
自动转换类型、丰富的子命令支持。写 CLI 工具时它就是首选。

1. 最小示例

import argparse


def parse_args():
    p = argparse.ArgumentParser(
        description="处理 Kafka 错误码并输出到 Excel",
    )
    p.add_argument("--interval", required=True, help="时间间隔，例如 1d")
    p.add_argument("--file_path", required=True, help="输出 Excel 文件路径")
    return p.parse_args()


if __name__ == "__main__":
    args = parse_args()
    print(f"interval: {args.interval}")
    print(f"file    : {args.file_path}")

python script.py --interval 1d --file_path ./out.xlsx
python script.py -h         # 自动生成的帮助

2. 常用参数

2.1 位置参数与可选参数

p.add_argument("input")                       # 位置，必填
p.add_argument("-o", "--output", default="out.txt")  # 可选

2.2 类型与默认值

p.add_argument("--port", type=int, default=8080)
p.add_argument("--host", type=str, default="127.0.0.1")
p.add_argument("--enable-cache", action="store_true")   # flag，默认 False
p.add_argument("--verbose", "-v", action="count", default=0)  # -v -vv -vvv

2.3 多个值 / list

p.add_argument("--tag", nargs="+", default=[])         # 一次多个
p.add_argument("--from-to", nargs=2, metavar=("A", "B")) # 固定 2 个

2.4 互斥 / 必填组

g = p.add_mutually_exclusive_group()
g.add_argument("--quiet", action="store_true")
g.add_argument("--verbose", action="store_true")

3. 子命令（subparsers）

类似 git commit / git push 的子命令结构：

p = argparse.ArgumentParser(prog="mytool")
sub = p.add_subparsers(dest="cmd", required=True)

p_get = sub.add_parser("get")
p_get.add_argument("name")

p_set = sub.add_parser("set")
p_set.add_argument("name")
p_set.add_argument("value", type=int)

args = p.parse_args(["set", "x", "1"])
print(args)        # Namespace(cmd='set', name='x', value=1)

4. 进阶选项

4.1 自定义 type

def port(s: str) -> int:
    n = int(s)
    if not (1 <= n <= 65535):
        raise argparse.ArgumentTypeError(f"port out of range: {n}")
    return n


p.add_argument("--port", type=port, default=8080)

4.2 choices

p.add_argument("--level", choices=["debug", "info", "warn", "error"])

4.3 metavar / help 改善帮助文本

p.add_argument("--log", metavar="FILE", help="日志文件路径")

4.4 从文件读配置

p.add_argument("--config", type=argparse.FileType("r"))
config = yaml.safe_load(args.config)

5. 与“主函数”配合的常用骨架

def main() -> int:
    args = parse_args()
    if args.verbose:
        print(f"[debug] {args}", file=sys.stderr)
    try:
        run(args)
    except KeyboardInterrupt:
        return 130
    return 0


if __name__ == "__main__":
    sys.exit(main())

6. 替代品

库 特点
argparse 标准库，够用就好
click 装饰器风格、子命令舒服、生态丰富
typer 基于类型注解 + click，几乎零样板代码
fire Google 出品，自动从函数签名生成 CLI
docopt 用 docstring 写 CLI 规范

新项目如果参数较多 / 有子命令，推荐 typer 或 click；只是几个
简单 flag 的话 argparse 已经够用。

7. 常见问题

  • -h 已经默认给 --help 用：别再把 -h 分配给别的参数。
  • required=True 与位置参数：位置参数本来就是必填；不要重复 required=True。
  • nargs="?" + default：要给 default，否则不传时是 None。
  • 错误退出码：argparse 在参数错误时自动 sys.exit(2)；业务异常
    记得自己 return 1。

8. 小结

  • argparse 是 Python CLI 的标准起点，0 依赖。
  • 用 add_argument 一次描述一个参数；type= 自动转换。
  • 子命令用 add_subparsers；互斥用 add_mutually_exclusive_group。
  • 帮助文本 / 错误信息是 argparse 自动生成的，写好 description 和 help 就能拿到
    漂亮的 --help。