
Pipbreak 工具可提前发现 Python 依赖更新导致的破坏
来源标题:Show HN: Pipbreak – find what a Python dependency update breaks before merging
开发者发布 pipbreak,能在合并依赖更新前检测出更新会破坏哪些代码。它通过读取已安装包的源码、比对各包之间的实际调用与已安装版本,在 Dependabot PR 中对比更新前后并指出具体断点。在 12 个已记录的「更新破坏未锁版本包」案例中,它标出了 9 个真实破坏中的 8 个(5 个精确到出错行),对 3 个安全更新则未报警。
以下正文由 AI 翻译自 Hacker News 最新(原文版权归原站所有),可能存在偏差,重要内容请以原文为准。
pip install -U werkzeug 执行成功,但你的 Flask 应用已经坏了。pip 只检查包声明的版本范围,而这些范围通常是开放式的——Flask 2.2 要求 Werkzeug>=2.2.2,于是 pip 会愉快地装上 Werkzeug 3,而 Werkzeug 3 已经移除了 Flask 2.2 所调用的那些 API。Dependabot 打开 PR,pip 解析依赖,你直到运行时才发现问题——或者如果测试恰好没走到那段代码,就根本发现不了。
pipbreak 会读取你所安装包的代码,逐一检查一个包对另一个包的每次调用,并对照实际安装的版本进行验证。在依赖升级 PR 上,它会对比升级前后,并准确告诉你这次更新破坏了什么:
这些包在元数据中接受新版本,但会调用新版本已不再提供的 API,因此 pip 安装时毫无怨言,运行时却会失败。要么把它们也一起升级,要么暂缓这次更新。
在线查看:pipbreak-demo 中的一个真实 Dependabot PR,这是一个 Flask 2.2 应用,其全部配置只有一个 workflow 文件。
无需配置,无需类型存根,零依赖。要求 Python 3.10+。
已知破坏:在 12 个有文档记录的「更新破坏了未锁定该依赖的包」案例中,它标出了 9 个真实破坏中的 8 个(其中 5 个精确到出错行),并且对全部 3 个安全更新保持沉默(基准测试)。
真实 Dependabot PR:在 40 个开源升级 PR 上,它捕获了 Flask、Flask-Login 和 Flask-WTF 中的 Werkzeug 3 破坏——每一个存在该问题的 PR 都被检出,包括一个 CI 通过的 PR(研究)。
真实应用:在六个开源应用各自的运行环境中,它发现的 bug 我都复现并报告了:
另外三个应用是 NetBox、FlaskBB 和 healthchecks。在 paperless-ngx(17,000 个文件)上,它报告的每一个错误都是真实的 API 不匹配:Linux 上有 7 个,Windows 上另有一个仅限 Windows 的问题。
它看不到的:通过 **kwargs 转发的参数、类型仅在运行时才确定的对象上的方法、二进制(C 扩展)不兼容性,以及 API 未变但行为改变的情况。它是对你测试的补充,而非替代。
# .github/workflows/pipbreak.yml
name: pipbreak
on: pull_request
permissions:
contents: read
pull-requests: write # for the comment; Dependabot PRs get a read-only token without this
jobs:
dependency-update:
if: github.actor == 'dependabot[bot]' || github.actor == 'renovate[bot]'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v5
- uses: actions/setup-python@v6
with:
python-version: "3.12" # the Python you deploy on
- uses: youssef-elaasri/pipbreak@v0
# with:
# install: pip install -r requirements/prod.txt # default: requirements.txt, else `pip install .`
# working-directory: backend
# fail-on-break: false
该 action 会安装两次依赖——分别从 PR 的 base commit 和 PR 本身——找出哪些包发生了变化,并且只报告这次变更破坏了什么:以 job summary 的形式、以一条它持续更新的 PR 评论的形式,以及以失败的检查的形式。安全的更新保持沉默。
使用 pull_request,而不是 pull_request_target:安装 PR 的依赖会运行它们的构建代码,而这些代码绝不能看到你仓库的写 token。
pip install pipbreak
pip install -U werkzeug
pipbreak --deps --uses werkzeug # what in my environment calls Werkzeug APIs that are gone?
pipbreak --deps # every installed package against every other
pipbreak --deps --python .venv/bin/python # another environment
# before/after, like the action does
python -m pipbreak.compare --base .venv-old/bin/python --head .venv/bin/python --markdown report.md
--uses LIB(可重复;使用 import 名或 distribution 名)将检查范围缩小到导入了 LIB 的包。这只需几秒钟。检查整个环境需要几分钟,大型环境则更久(paperless-ngx 有 17,000 个文件,需要 15 到 30 分钟)。
只有从一个 distribution 到另一个 distribution 的调用才会计数。包自身的内部调用、stdlib、缺失的可选 extras、vendored 副本以及随包发布的测试套件都会被跳过。
存在错误时退出码为 1(--strict 会让警告也导致失败)。
检查你自己的代码
同一个引擎会用你安装的版本检查你项目的代码——对为不同版本库编写的代码很有用(无论是你、教程还是 AI 助手写的):
$ pipbreak examples/
examples/app.py:9:1: error API002 'pydantic.BaseSettings' is not available in pydantic==2.9.2: `BaseSettings` has been moved to the `pydantic-settings` package. ...
examples/app.py:9:1: warning API101 'pydantic.validator' is deprecated in pydantic==2.9.2: Pydantic V1 style `@validator` validators are deprecated. ...
examples/app.py:31:8: error API002 'os.path' has no attribute 'exist' in Python 3.13. Did you mean 'exists'?
examples/app.py:33:27: error API003 shutil.copy() has no parameter 'overwrite' in Python 3.13.
examples/app.py:37:39: error API003 random.choices() has no parameter 'unique' in Python 3.13.
examples/app.py:45:30: error API002 'collections' has no attribute 'Mapping' in Python 3.13. Did you mean 'collections.abc.Mapping'?
examples/app.py:50:12: error API002 'Path' object has no attribute 'exist' in Python 3.13. Did you mean 'exists'?
examples/app.py:52:27: error API003 path.read_text() has no parameter 'encodings' in Python 3.13. Did you mean 'encoding'?
examples/app.py:56:12: warning API101 'User.dict' is deprecated in pydantic==2.9.2: The `dict` method is deprecated; use `model_dump` instead.
examples/app.py:60:12: warning API101 'User.parse_obj' is deprecated in pydantic==2.9.2: The `parse_obj` method is deprecated; use `model_validate` instead.
examples/app.py:71:12: warning API005 'Job' object has no attribute 'retry_count': it is never assigned in the class or its bases.
把同一个文件对着 pydantic 1.10 运行,结果会不同:BaseSettings、.dict() 和 .parse_obj() 都没问题,但 field_validator 还不存在(Did you mean 'validator'?)。
pipbreak src/ # check against the current interpreter
pipbreak --python .venv/bin/python src/ # check against another environment
pipbreak --format github src/ # inline annotations on GitHub PRs
pipbreak --format json src/ # machine-readable
(原文较长,此处译出前 6000 字,完整内容请点「打开原文」。)
正文由 探How 从来源站点 RSS 同步,内容未经改写;遇到排版缺失或需要图片、视频时请以原文为准。