客户一行命令就能装好,脚本才算交付
用 Typer 和 uv 五步把零散脚本打包成 CLI,帮助信息和自动补全无需额外代码。
要点速览
- Typer 基于标准的 Python 类型注解构建 CLI,自带帮助信息,以及 Bash、Zsh、Fish 和 PowerShell 的自动补全。
- 命令在 [project.scripts] 中声明,指向 app 对象。[build-system] 表必须始终存在。
- pipx 和 uv tool install 为每个工具建立独立环境,uvx 则在临时环境中运行工具,客户团队因此不会遇到依赖冲突。
在客户项目上做到第三周,你写了一个脚本 check_csv.py,用来在数据文件加载进数据管道之前做检查。
客户的运维团队问怎么运行,你回了一大段说明:装哪个 Python 版本、pip install 哪些包、文件放在哪里。
两天后他们报错,原因是他们机器上某个库的版本和你的不一样。
代码没有问题,出问题的是交付。前线部署工程师(FDE)应该留下的,是工程师离场后客户能自己运行的工具;对于命令行运行的东西,这意味着一个正确打包的 CLI。下面五个步骤会把零散脚本变成一个 check-data 命令,客户团队一行命令就能装好。
要做什么,需要准备什么
最终产物是一个名为 check-data 的 Python 包。它只有一个命令,接收一个 CSV 文件路径和一个 --max-rows 选项,把结果打印到屏幕上,文件不合格时返回错误码。你的机器上需要有 Python 和 uv。示例中省略了校验逻辑,换成你自己的即可。
主要工具是 Typer。按它自己的介绍,这是一个基于 Python 类型注解、用来构建好用又好写的 CLI 的库。
Typer 依靠标准的 Python 类型注解,所以声明参数的方式和写普通函数一样。帮助信息以及 Bash、Zsh、Fish 和 PowerShell 的自动补全都是内置的。
客户团队能拿到这些功能,而你不用多写一行代码。
第 1–2 步:创建包,编写命令
Typer 的打包教程用 uv 搭建包结构:
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。下面是最简版本:命令骨架完整,只留下校验逻辑由你填写。
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 生成的默认行,而不是再加一行同名命令:
[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 运行(它会先把包安装到项目环境,再执行):
uv run check-data --help
uv run check-data broken_data.csv
echo $? # 预期为 1,而不是 0
第 4–5 步:构建 wheel,交付得让客户省心
uv build
这会在 dist/ 中生成两个文件:一个 sdist .tar.gz 和一个 wheel .whl。wheel 就是你发给客户或推送到客户内部包索引的文件。到这里,问题已经不在技术层面:客户团队的机器是怎么配置的?
这一点很重要,因为本文开头的故障正是装进共享系统 Python 导致的。
uv 文档解释说,uv tool install 会把每个工具放进独立环境,工具、脚本和项目的依赖互不冲突。pipx 对面向终端用户的 Python 应用做的事情类似:每个应用有自己的 virtualenv,命令则放到 PATH 上。
uvx 则不同,它在临时的隔离环境中运行工具,用户无需事先安装任何东西。对于刚构建好的 wheel,两种调用方式如下:
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
永久安装(pipx、uv tool install)
- 运维团队每天都用这个命令
- 命令位于 PATH 上,可从 cron 或脚本调用
- 发布新版本时需要一套升级流程
临时运行(uvx)
- 分析师只是偶尔运行
- 不在机器上留下任何东西
- 适合演示或让客户试用
在客户那边定一条规则:每天用这个命令的人永久安装,只是试用的人用 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,让客户运维团队每天自行运行,并写明谁在用它。
第一个该打包的脚本,就是这周你被问“怎么运行”次数最多的那个。
这篇文章对你有帮助吗?
感谢你的反馈!