[!info] 关联笔记

• 所属 MOC：标准库 · 学习路线
• 前置：程序结构 · 错误处理
• 后续：打包（console_scripts）

使用 argparse 构建 CLI

目标

交付一个可本地运行的命令行工具：解析参数、调用纯业务函数、以退出码表达成功/失败。

这个场景为什么出现

运维与数据同学需要“一条命令完成任务”。把解析与业务混在一起会导致无法单测。

[!abstract] 一句话理解 argparse 负责 argv → 结构化参数；业务函数可测；main 映射到退出码。

最小可运行示例

场景：订单号规范化小工具

# normalize_order_cli.py
# 业务意图：CLI 规范化订单号。
# 教学点：ArgumentParser；业务纯函数；退出码。

from __future__ import annotations

import argparse
import sys


def normalize_order_id(raw: str) -> str:
    value = raw.strip().upper()
    if not value:
        raise ValueError("order id is empty")
    return value


def build_parser() -> argparse.ArgumentParser:
    p = argparse.ArgumentParser(description="Normalize order id")
    p.add_argument("order_id", help="raw order id")
    return p


def main(argv: list[str] | None = None) -> int:
    args = build_parser().parse_args(argv)
    try:
        print(normalize_order_id(args.order_id))
        return 0
    except ValueError as exc:
        print(f"error: {exc}", file=sys.stderr)
        return 2


if __name__ == "__main__":
    raise SystemExit(main())

建议运行：

python normalize_order_cli.py " ab-1 "
python normalize_order_cli.py "   "; echo exit:$?

期望输出：

AB-1
error: order id is empty
exit:2

结合场景再看三个关注点

1. main(argv) 便于测试注入。
2. 退出码给 shell/CI 用。
3. 复杂 CLI 可迁 Typer/click，但标准库足够多场景。

步骤清单

1. 抽纯函数
2. 定义 parser
3. main 映射错误
4. 可选打包入口

验收标准

• --help 可读
• 成功输出与失败退出码正确
• 业务函数可无 argv 单测

本节总结

CLI 是函数的外壳。标准库 argparse 足够起步。

自测题

1. 为何 main 返回 int？
2. 业务异常如何呈给用户？

参考答案

1. 表达进程退出码。
2. 捕获后写 stderr 并返回非 0。

延伸阅读与资料来源

资料	类型	支撑内容
argparse	文档	官方