PyBuilder：一个专门给 Python 项目准备的构建神器

兄弟姐妹们，写了几天代码，总算把业务功能敲完了，结果一想到要打包、跑单元测、生成报告，脑子里立刻冒出“又要折腾构建工具了？”的恐慌。别慌，今天给大家安利一个 PyBuilder，它是专门给 Python 项目准备的构建神器，轻轻一装，省去一堆手动脚本的麻烦。下面咱们用口语化的方式，聊聊它到底是个啥、解决了哪些痛点、怎么装、怎么用，最后再掰扯掰扯它的优缺点，帮你快速上手。

PyBuilder 是什么玩意儿？
PyBuilder 用 纯 Python 写成，定位就是“Python 项目全自动化”。它的核心思路是 基于依赖的编程——先声明好任务之间的依赖关系，工具会自动按顺序跑完。再加上插件机制，几乎能把 单元测试、代码覆盖率、文档生成、发布到 PyPI 这些常见环节全部串起来，跟 Maven、Gradle 那套 Java 架子差不多，只是专门为咱们 Python 量身定制。

功能	插件名称	备注
核心构建	python.core	基础跑起来的必备
单元测试	python.unittest	支持 unittest/pytest
代码覆盖率	python.coverage	自动生成 coverage 报告
打包发布	python.distutils	生成 wheel、sdist
文档生成	python.sphinx	直接跑 Sphinx 文档
静态检查	python.flake8	代码风格检查插件

小提示：插件都是 pip 安装的，想要啥功能直接 use_plugin(“python.xxx”) 就行。

它解决了哪些让人抓狂的痛点？

1. 手写脚本太繁琐：以前我们常常写一堆 setup.py、tox.ini、makefile，改一点点配置得翻来覆去。PyBuilder 把这些都搬进了 build.py，一个文件搞定。
2. 任务顺序容易出错：列如想先跑测试再生成报告，手动写顺序容易写错。PyBuilder 用 依赖图 自动排队，省心。
3. 插件生态散落：单独跑 coverage、flake8，每次都要记命令。插件把它们统一入口，pyb 命令一键搞定。
4. 跨 Python 版本兼容：官方已经在 3.9‑3.13 以及 PyPy 上跑通，基本不担心版本冲突。
5. CI 集成简单：只要在 CI 脚本里装了 pybuilder，后面直接 pyb，输出的报告还能直接喂给 GitHub Actions、GitLab CI。

装装装，怎么上手？

# 用 pip 安装（推荐使用虚拟环境）
pip install pybuilder

# 想玩预发布版本？加上 --pre
pip install --pre pybuilder

装好后，在项目根目录 新建 build.py，写上最基础的配置：

# build.py
from pybuilder.core import use_plugin, init

# 必备插件
use_plugin("python.core")
use_plugin("python.unittest")
use_plugin("python.coverage")
use_plugin("python.distutils")

# 默认任务：打包并发布
default_task = "publish"

@init
def set_properties(project):
    # 项目信息
    project.build_depends_on('mock')
    project.set_property('coverage_break_build', False)

只要目录结构遵循 src/main/python（源码）和 src/unittest/python（测试），pyb 就能自动发现代码，跑单元测、生成 coverage、打包成 wheel。

常用命令速查

命令	作用
pyb	执行默认任务（上面例子是 publish）
pyb clean	清理构建产物
pyb run_unit_tests	只跑单元测试
pyb analyze	运行代码质量检查（需要插件）
pyb install_dependencies	安装 build.depends 中声明的依赖

优点 & 缺点，实话实说

优点	缺点
全 Python 实现，跨平台、易上手	插件文档相对分散，初次查找可能要翻几页
依赖驱动，任务顺序自动管理	对于超级复杂的自定义流程，需要自己写插件
统一入口，pyb 命令搞定所有	与 poetry、flit 等现代打包工具竞争激烈
插件丰富，覆盖测试、覆盖率、文档等	社区活跃度不如 Maven/Gradle 那样大，更新慢
兼容多 Python 版本，官方已经准备好	对新手来说，build.py 的 DSL 需要适应一下

小结
如果你正被 “手写构建脚本+跑不完的 CI 命令” 逼得快疯了，或者你的项目已经有点规模，需要统一的构建、测试、发布流程，PyBuilder 是一个值得尝试的选项。它把一堆零碎的工具整合进 build.py，用插件把功能点点插上，省时省力。缺点就是社区相对小，文档不够聚焦，但只要你掌握了基本的插件写法，基本上能满足大多数中小型项目的需求。

项目地址：https://github.com/pybuilder/pybuilder