# 客户一行命令就能装好，脚本才算交付

> 用 Typer 和 uv 五步把零散脚本打包成 CLI，帮助信息和自动补全无需额外代码。

原文: https://fdetimes.net/zh/guides/package-python-script-cli-typer/

在客户项目上做到第三周，你写了一个脚本 `check_csv.py`，用来在数据文件加载进数据管道之前做检查。

客户的运维团队问怎么运行，你回了一大段说明：装哪个 Python 版本、`pip install` 哪些包、文件放在哪里。

两天后他们报错，原因是他们机器上某个库的版本和你的不一样。

代码没有问题，出问题的是交付。前线部署工程师（FDE）应该留下的，是工程师离场后客户能自己运行的工具；对于命令行运行的东西，这意味着一个正确打包的 CLI。下面五个步骤会把零散脚本变成一个 `check-data` 命令，客户团队一行命令就能装好。

## 要做什么，需要准备什么

最终产物是一个名为 `check-data` 的 Python 包。它只有一个命令，接收一个 CSV 文件路径和一个 `--max-rows` 选项，把结果打印到屏幕上，文件不合格时返回错误码。你的机器上需要有 Python 和 [uv](https://docs.astral.sh/uv/)。示例中省略了校验逻辑，换成你自己的即可。

主要工具是 Typer。按它自己的介绍，这是一个基于 Python 类型注解、用来构建好用又好写的 CLI 的库。

Typer 依靠标准的 Python 类型注解，所以声明参数的方式和写普通函数一样。帮助信息以及 Bash、Zsh、Fish 和 PowerShell 的自动补全都是内置的。

客户团队能拿到这些功能，而你不用多写一行代码。

## 第 1–2 步：创建包，编写命令

Typer 的打包教程用 uv 搭建包结构：

```bash
uv init --package check-data
cd check-data
```

这会生成 `pyproject.toml`、一个带有打印问候语的 `main()` 函数的 `src/check_data/__init__.py` 文件，以及 `[project.scripts]` 下的默认条目 `check-data = "check_data:main"`。第 3 步会替换这个条目。

检查：打开 `pyproject.toml`，找到 `[build-system]` 表。Python Packaging User Guide 指出，无论使用哪种构建后端，这张表都应始终存在。

接着运行 `uv add typer` 把 Typer 加入依赖，然后创建 `src/check_data/main.py`。下面是最简版本：命令骨架完整，只留下校验逻辑由你填写。

```python
from pathlib import Path
import typer

app = typer.Typer()

@app.command()
def check(path: Path, max_rows: int = 1000):
    """在加载进数据管道之前检查 CSV 文件。"""
    ok = True  # 替换为真实的校验逻辑
    if not ok:
        raise typer.Exit(code=1)
    typer.echo(f"{path}：通过")
```

类型注解 `Path` 和 `int` 告诉 Typer 每个参数的类型。哪些参数必填，遵循普通 Python 函数的规则：`path` 没有默认值，必须提供；`max_rows` 有 `= 1000`，可以省略。运行 `--help` 就能看到 Typer 如何展示这两个参数。

## 第 3 步：声明命令，最容易出错的一步

根据 Python Packaging User Guide，会安装命令的包必须在 `[project.scripts]` 表中声明命令。Typer 的示例写法是 `rick-portal-gun = "rick_portal_gun.main:app"`。对于你的包，应直接修改 `uv init` 生成的默认行，而不是再加一行同名命令：

```toml
[project.scripts]
check-data = "check_data.main:app"
```

左边是用户要输入的命令名，用连字符；右边是导入路径，用下划线，而且必须指向 `app` 对象，而不是 `check` 函数。

原因在于入口点的工作方式。Packaging Guide 解释说，运行命令相当于导入被引用的对象、调用它，再把返回值传给 `sys.exit`。

这次调用不传任何参数。所以如果直接指向 `check`，命令很可能因为缺少参数而立刻失败，根本不会经过 Typer 解析命令行。

这个机制还说明了另一件事：CLI 的退出码是你和客户系统之间的契约。客户的 cron 任务、CI 或编排脚本会读取这个数字，决定是否继续执行。

**要点:** 命令行工具的退出码，是对每个调用它的系统的承诺。

检查：临时把 `ok = True` 改成 `ok = False` 模拟一个坏文件，然后通过 `uv run` 运行（它会先把包安装到项目环境，再执行）：

```bash
uv run check-data --help
uv run check-data broken_data.csv
echo $?   # 预期为 1，而不是 0
```

## 第 4–5 步：构建 wheel，交付得让客户省心

```bash
uv build
```

这会在 `dist/` 中生成两个文件：一个 sdist `.tar.gz` 和一个 wheel `.whl`。wheel 就是你发给客户或推送到客户内部包索引的文件。到这里，问题已经不在技术层面：客户团队的机器是怎么配置的？

这一点很重要，因为本文开头的故障正是装进共享系统 Python 导致的。

uv 文档解释说，`uv tool install` 会把每个工具放进独立环境，工具、脚本和项目的依赖互不冲突。pipx 对面向终端用户的 Python 应用做的事情类似：每个应用有自己的 virtualenv，命令则放到 PATH 上。

`uvx` 则不同，它在临时的隔离环境中运行工具，用户无需事先安装任何东西。对于刚构建好的 wheel，两种调用方式如下：

```bash
uv tool install ./dist/check_data-0.1.0-py3-none-any.whl
uvx --from ./dist/check_data-0.1.0-py3-none-any.whl check-data data.csv
```

在客户那边定一条规则：每天用这个命令的人永久安装，只是试用的人用 `uvx`。两种方式都写进 README，各一行命令。不要让他们去读 Python 安装说明。

## 你离场后会让工具失效的错误

第一个错误是给命令起 `check` 或 `run` 这类通用名称，结果和客户机器上已有的东西冲突。应选一个和业务任务挂钩的名字，比如 `check-orders`。

第二个是代码始终以 0 退出，即使发现了坏数据。屏幕前的人看得到警告，客户的数据管道却照样加载坏文件。

第三个是让客户把 wheel 直接装进系统 Python，正是开头那个场景。这样你的工具会和机器上的其他程序共用库，一次升级就可能让它出错。README 里只应列出 pipx、`uv tool install` 或 `uvx` 命令，绝不写裸的 `pip install`。

最后一个是只在自己机器上测试，而那里所有依赖早已齐全。发出之前，在一台干净的机器或容器上，严格按 README 中的命令安装 wheel。

## 这项技能在 FDE 工作中如何体现

在客户现场，“演示能跑”和“客户能自己跑”之间的差距，往往就取决于这类小事。一个 `--help` 清晰、带自动补全、退出码正确的 CLI，能大幅减少你离场后“这个怎么运行”的消息。客户也可以把它放进 cron 或 CI，不用再找你。

阅读 FDE 岗位描述时，留意内部工具开发，或把工作交给客户团队自行运行的相关要求：这项技能就用在那里。

简历上不要写“熟悉 Python 打包”。要写你把一个数据校验工具打包成 CLI，让客户运维团队每天自行运行，并写明谁在用它。

第一个该打包的脚本，就是这周你被问“怎么运行”次数最多的那个。

**本周动手试试:**

- 找一个你常通过聊天发给客户的脚本，按本文五个步骤打包，再在一台干净的机器上用 uv tool install 亲自安装一遍。
- 写一份正好一屏长的 README，包含安装命令、一条示例命令和各退出码的含义，然后请一位不写代码的人照着操作。
- 在简历上加一行，描述你交付过的一个内部工具，并写明有多少人或团队在自行使用它。

## 信源

- [Typer](https://typer.tiangolo.com/)

- [Building a Package - Typer](https://typer.tiangolo.com/tutorial/package/)

- [Writing your pyproject.toml](https://packaging.python.org/en/latest/guides/writing-pyproject-toml/)

- [pipx](https://pipx.pypa.io/stable/)

- [Using tools](https://docs.astral.sh/uv/guides/tools/)
