Tautulli 仓库中 Bleach 的 vendored library 治理实践:依赖锁定、升级流程与源码级校验
Tautulli 仓库中 Bleach 的 vendored library 治理实践:依赖锁定、升级流程与源码级校验
本指南以 Tautulli 仓库内置 Bleach 库的 lib/bleach/_vendor/README.rst 为核心文档,系统讲解该仓库如何通过 "vendoring"(源码内嵌依赖)策略管理 html5lib 等第三方纯 Python 库,包括五项准入规则、添加/升级/移除三个操作流程,以及基于 pip install 与 git diff 的可复现校验方法。读完本文,你将掌握一套不依赖构建服务、可在任意分支上重复执行的依赖快照维护与审查工作流,并了解 Tautulli 实际如何使用被 vendored 的 Bleach 完成通知消息的 HTML 白名单清洗。
一、什么是 vendored library,Bleach 为何要这么做
Vendoring(供应商内嵌)是一种把第三方库的完整源码直接放入自身仓库的做法。Bleach 在简化自身开发流程的考虑下,将依赖的若干库直接内嵌进仓库:不再每次构建时从 PyPI 动态拉取,而是把"固定版本 + 完整源码 + 许可证 + 哈希"全部提交进代码库,形成可审计、可复现的依赖快照。
在 Tautulli 仓库中,这套快照落在 lib/bleach/_vendor/ 目录下,当前内嵌的是 html5lib 1.1。其目录结构如下:
lib/bleach/_vendor/
├── README.rst # 本策略文档(本文核心依据)
├── __init__.py # 空文件,标记该目录为 Python 包
├── vendor.txt # 依赖清单:库名、版本与 SHA256 哈希
├── vendor_install.sh # 可复现的安装脚本
├── parse.py # 取自 CPython 3.6.14 的 urllib.parse,用于 #536 修复
├── parse.py.SHA256SUM # parse.py 的哈希校验文件
├── html5lib/ # 被内嵌的 html5lib 1.1 完整源码
└── html5lib-1.1.dist-info/ # pip 生成的发行元数据
该策略的核心动机是简化 Bleach 的开发与发布:Bleach 的 HTML 清洗能力建立在对 HTML5 解析器的深度依赖之上,而 html5lib 的接口演进较快。通过把 html5lib 锁定为固定版本并内嵌,Bleach 团队可以在 lib/bleach/html5lib_shim.py 中维护一个"shim(适配层)",将 Bleach 与 html5lib 的具体接口解耦。该文件头部的注释明确写道:"Shim module between Bleach and html5lib. This makes it easier to upgrade the html5lib library without having to change a lot of code."——升级 html5lib 时只需调整这一层,无需大范围改动 Bleach 主体。
二、五项准入规则:什么库才有资格被内嵌
README.rst 规定了所有被 vendored 的库必须遵守的五条硬性规则:
- 必须是纯 Python,无需编译:vendored 库不能包含 C 扩展等需要现场编译的代码,否则内嵌后在不同平台无法直接导入。
- 库的源码必须完整包含在本目录中:不允许只放一个指向外部的引用,必须是可直接 import 的完整包。本仓库中 html5lib 的完整包体即位于 lib/bleach/_vendor/html5lib/。
- 许可证必须同时包含在本仓库与 Bleach 发行包中:这是合规底线。当前 html5lib 1.1 的 MIT 许可证即保留在 lib/bleach/_vendor/html5lib-1.1.dist-info/LICENSE 中。
- 该库的依赖自动成为 Bleach 的依赖:vendoring 不消除传递依赖,只是把直接依赖固定下来。html5lib 的元数据 lib/bleach/_vendor/html5lib-1.1.dist-info/METADATA 声明了
six (>=1.9)与webencodings两个运行时依赖,因此在 Bleach 的安装要求中同样需要它们存在。 - 禁止对被内嵌的库做任何修改:vendored 代码必须与上游一致,以保证升级时可复现、可 diff。
规则 5 的严格性在 Tautulli 仓库中得到了一次特例体现:Bleach 为了修复上游问题(issue #536),在 lib/bleach/_vendor/vendor_install.sh 中额外下载了 Python 3.6.14 标准库的 urllib.parse 源码,以 parse.py 形式放入 _vendor 目录,并生成 lib/bleach/_vendor/parse.py.SHA256SUM 做完整性校验;lib/bleach/parse_shim.py 再通过 from bleach._vendor.parse import urlparse 引用它。这条路径说明:在"不修改上游"的前提下,允许以独立补丁文件的形式替换特定模块。
三、添加或升级一个 vendored library:四步标准流程
README.rst 给出了一套可复现的操作流程,配合仓库中的 vendor.txt 与 vendor_install.sh 形成完整闭环:
第 1 步:更新 vendor.txt,写入版本与哈希
以当前内嵌的 html5lib 1.1 为例,vendor.txt 的实际内容为:
html5lib==1.1 \
--hash=sha256:0d78f8fde1c230e99fe37986a60526d7049ed4bf8a9fadbad5f00e22e58e041d \
--hash=sha256:b2e5b40261e20f354d198eae92afc10d750afb487ed5e50f9c4eaf07c184146f
格式为标准的 库名==版本 加 pip 的 --hash 哈希锁定(这里同时列出了 wheel 与 sdist 两套 SHA256)。文档建议使用 hashin 工具来生成这些哈希行,确保来源可信。
第 2 步:删除旧版本的残留文件
将旧版本的全部文件与目录(包括旧的 html5lib-*.dist-info)从 _vendor 中移除,保证目录与 vendor.txt 严格对应。
第 3 步:运行 vendor_install.sh 并检查产物
执行脚本,并逐项检查它产出的所有内容,特别是 .dist-info 目录及其内容。仓库中实际的脚本 vendor_install.sh 展示了完整细节:
#!/bin/bash
set -e
set -u
set -o pipefail
BLEACH_VENDOR_DIR=${BLEACH_VENDOR_DIR:-"."}
DEST=${DEST:-"."}
# Install with no dependencies
pip install --no-binary all --no-compile --no-deps -r "${BLEACH_VENDOR_DIR}/vendor.txt" --target "${DEST}"
# Apply patches
(cd "${DEST}" && patch -p2 < 01_html5lib_six.patch)
(cd "${DEST}" && patch -p2 < 02_html5lib_wbr.patch)
(cd "${DEST}" && patch -p2 < 03_html5lib_formaction.patch)
# install Python 3.6.14 urllib.urlparse for #536
curl --proto '=https' --tlsv1.2 -o "${DEST}/parse.py" https://raw.githubusercontent.com/python/cpython/v3.6.14/Lib/urllib/parse.py
(cd "${DEST}" && sha256sum parse.py > parse.py.SHA256SUM)
几个值得注意的实现要点:
--no-binary all强制从 sdist 源码安装,呼应了"必须纯 Python、无编译"的规则;--no-compile禁止现场生成.pyc,避免把二进制产物带进仓库;--no-deps不自动拉取传递依赖,vendored 只包含清单中列出的库本身;--target "${DEST}"指定安装目标目录,即_vendor;- 脚本通过
patch -p2依次应用三个补丁(01_html5lib_six.patch、02_html5lib_wbr.patch、03_html5lib_formaction.patch),用于替换 html5lib 对six的依赖、补充wbr标签等。仓库中 lib/bleach/six_shim.py 正是这些补丁落地的产物——它以text_type = str、unichr = chr等别名替代了 html5lib 原代码中对six的引用,相关源码(如 lib/bleach/_vendor/html5lib/_inputstream.py、lib/bleach/_vendor/html5lib/_tokenizer.py)均改为from bleach.six_shim import ...。
提示:当前仓库中的补丁文件本体并未保留在
lib/bleach/_vendor/下,脚本引用它们说明该流程面向 Bleach 上游仓库;在 Tautulli 仓库中,补丁的最终效果已经体现在html5lib源码与six_shim.py中,升级时需以源码 diff 为准。
第 4 步:在下一个发布中递增 Bleach 的 minor 版本号
README 明确要求:任何 vendored 库的变更都要伴随一次 Bleach minor 版本提升,以标记依赖快照的变化。当前仓库中 Bleach 版本号为 6.4.0(见 lib/bleach/init.py 的 __version__),该字段即为此流程的产出之一。
四、审查一个涉及 vendored library 的变更:可复现的四步校验
README.rst 同时提供了针对代码评审场景的校验流程,其核心思想是让内嵌依赖可以被独立重建并 diff:
- 拉取目标分支:
git checkout <branch>获取包含变更的分支; - 删除旧版本全部文件与目录:清空
_vendor下旧 html5lib 相关内容; - 重新运行
pip_install_vendor.sh(即仓库中的vendor_install.sh)按vendor.txt重建依赖; - 执行
git diff并确认没有任何差异。
若重建结果与提交内容完全一致,说明内嵌快照真实、可复现;若出现差异,则说明提交过程中存在手工改动或未记录的步骤,应退回修正。这是一套轻量、无需 CI 的"构建即校验"机制,任何审查者都可以在本地复现。
此外 README 特别提醒:当前 vendor.txt 是由 pip 20.2.3 生成的。由于 .dist-info 目录的生成格式随 pip 版本变化,若想精确复现相同的 dist-info 内容,需要使用与生成时一致的 pip 版本(或至少意识到版本差异带来的 diff 噪音)。
五、移除(Unvendoring)一个库:何时做、怎么做
README 列举了触发移除的三种典型场景:
- 违反 vendoring 政策:例如上游许可证发生不兼容变更,使其不再符合规则 3;
- 找到了合适的替代库:有更优方案取代原库;
- Bleach 有能力对多版本进行回归测试:当团队资源足以在发布前对多个版本的替代库做 QA 时,就可以从"锁定单版本"回归"跟随上游多版本"。
移除流程同样标准清晰:
- 从
vendor.txt中删除该库及其哈希; - 从
_vendor目录中删除该库的全部文件与目录; - 运行
install_vendor.sh,检查此前被 vendored 的库(含.dist-info目录)确实没有被安装,确认已彻底解绑; - 在下一个发布中递增 Bleach 的 minor 版本号。
值得对比的是:规则 4 规定"被内嵌库的依赖会成为 Bleach 的依赖",因此 unvendoring 之后,这些传递依赖的安装责任也随之回到正常的依赖管理流程,而非仓库内嵌快照。
六、从策略到实战:Tautulli 如何消费被 vendored 的 Bleach
本仓库是 Tautulli,Bleach 的 vendoring 策略在这里有具体的消费场景。Tautulli 在发送通知消息时,需要把可能包含用户自定义 HTML 的正文做安全清洗,其实现分布在 plexpy/notification_handler.py 与 plexpy/notifiers.py 中:
import bleach
# 按 agent 维护 HTML 白名单
whitelist = {'b': [], 'i': [], 'u': [], 'a': ['href'], 'font': ['color']}
data = bleach.clean(data, tags=whitelist.keys(), attributes=whitelist, strip=True)
bleach.clean() 的签名(见 lib/bleach/init.py)为:
def clean(text, tags=ALLOWED_TAGS, attributes=ALLOWED_ATTRIBUTES,
protocols=ALLOWED_PROTOCOLS, strip=False,
strip_comments=True, css_sanitizer=None):
其底层调用链是:clean() → bleach.sanitizer.Cleaner → html5lib 解析器(经 lib/bleach/html5lib_shim.py 适配)→ 白名单过滤 → 序列化输出。这一整条安全链的基石,正是 _vendor 中内嵌的 html5lib 1.1——它是仓库内唯一被 vendored 的库。Tautulli 对不同通知渠道(Pushover、Telegram 等)定制了不同标签白名单,例如 Telegram 允许 b/strong/em/u/a<a href="https://link.gitcode.com/i/635edcfbc8d32efdd4b1d13f2bbf26b0" target="_blank">href]/code/pre 等(见 [plexpy/notification_handler.py),这正体现了"固定内嵌版本 + 上层灵活白名单"的组合价值。
七、总结:这套策略的可复用要点
回到 lib/bleach/_vendor/README.rst 本身,可以将整套 vendoring 治理提炼为四条可迁移的工程原则:
- 准入约束前置:用"纯 Python、含源码、含许可证、依赖上提、不改上游"五项规则,从源头控制内嵌依赖的维护成本;
- 清单即真相:
vendor.txt的版本 + SHA256 哈希是全流程的单一事实来源; - 脚本保证可复现:
vendor_install.sh以--no-binary all --no-compile --no-deps等参数确保任何环境都能重建出字节级一致的快照; - diff 即验收:无论升级还是审查,都以
git diff零差异作为最终验收标准,辅以"生成时 pip 版本一致"的约束,避免工具版本导致的伪差异。
这套"固定快照 + 可重建 + 可 diff"的方法,不依赖任何外部构建服务,特别适合像 Tautulli 这样将 Bleach 及其 html5lib 解析链作为安全基础设施的 Python 项目。