pip Changelog（更新日志）指南：读懂 NEWS.rst 与 news 片段的工作机制

pip Changelog更新日志指南读懂 NEWS.rst 与 news 片段的工作机制【免费下载链接】pipThe Python package installer项目地址: https://gitcode.com/gh_mirrors/pi/pippip 是 Python 生态中最核心的包安装工具本仓库即其源码仓库项目描述为 The Python package installer。本文以仓库中的 docs/html/news.rst 与根目录 NEWS.rst 为骨架系统讲解 pip 更新日志的组织方式由 Sphinx 指令pip-news-include自动嵌入的完整发布历史自 19.0 到 26.2.1 共 4900 行由 towncrier 维护、位于news/目录下的未发布变更片段以及它们的分类体系Features、Bug Fixes、Vendored Libraries 等。读完本文你将掌握如何读懂任何 pip 版本的功能演进脉络、如何在提交中编写规范的 news 片段以及如何从更新日志反查对应源码实现。更新日志的入口与组装机制docs/html/news.rst全文极短是一个典型的入口 指令型文档 Changelog .. attention:: Major and minor releases of pip also include changes listed within prior beta releases. .. towncrier-draft-entries:: Not yet released .. pip-news-include:: ../../NEWS.rst它只承担三件事标题与提示用.. attention::提醒读者pip 的主要major和次要minor版本发布内容中也包含此前所有 beta 版本中列出的变更——即更新日志是累积的查阅某个正式版本时应连同上一个正式版本之后的 beta 条目一起看。未发布草稿条目.. towncrier-draft-entries:: Not yet released由 Sphinx 的 towncrier 扩展生成展示尚未正式发布版本的变更片段即 news/ 目录下的内容。发布历史嵌入.. pip-news-include:: ../../NEWS.rst是 pip 自定义的 Sphinx 指令实现位于 docs/pip_sphinxext.py 中的PipNewsInclude类。它读取相对该文档上级目录的 NEWS.rst并对每个版本标题自动生成稳定的锚点def _iter_lines_with_refs(self, lines: Iterable[str]) - Iterator[str]: Transform the input lines to add a ref before each section title. Dots in the version is converted into dash, and a v is prefixed. This makes Sphinx use them as HTML id verbatim without generating auto numbering (which would make the anchors unstable). 即版本号26.2.1会被转换为v26-2-1形式的 HTML 锚点从而保证跨文档引用的稳定性。任何其他文档需要引用某个 pip 版本的更新日志时均可借助该锚点精确定位。注意这条指令中的../../NEWS.rst是文档内部相对路径在仓库中实际指向根目录的 NEWS.rst。发布历史的结构版本、分类与条目NEWS.rst 是 pip 的官方 Changelog 主体按版本倒序组织——最新版本在最上方。每个版本区块采用一致的骨架版本号 (发布日期) 分类标题 ---------- - 变更条目附 issue 链接以当前最新版本 26.2.12026-08-04为例26.2.1 (2026-08-04) Bug Fixes --------- - Reallow keyring installed in a (non-activated) virtual environment to be be used via the import provider method while installing build dependencies. (#14227 https://github.com/pypa/pip/issues/14227_)从源码结构看pip 更新日志沿用了 PEP 8 风格的文档分类惯例历史上出现过以下几类标题分类标题含义典型示例NEWS.rst 行号Features新功能/新选项--only-deps、--no-require-hashes、pylock 支持等Bug Fixes缺陷修复安全修复CVE、崩溃修复、行为修正Deprecations and Removals弃用与移除丢弃旧 Python 版本、移除废弃参数Vendored Libraries内嵌依赖升级certifi、urllib3、packaging 等版本升级Improved Documentation文档改进修正文档链接、补充说明Process开发流程变化CI/CD、SBOM、AI 政策等Enhancements性能与体验增强26.1 中的解析提速、内存优化需要说明的是Enhancements类目只在少数版本如 26.1中出现多数版本将其合并进Features或Bug Fixes这是 pip 更新日志在不同时期分类口径的差异阅读历史版本时不必惊讶。条目书写规范每个条目都有两个硬性要求必须描述用户可感知的行为变化而不是内部实现细节必须附带 GitHub issue/PR 编号链接形如(#14227 https://github.com/pypa/pip/issues/14227_)方便读者回溯讨论与实现。文件开头还有一段面向维护者的说明NEWS.rst 第 1–10 行不要在 NEWS.rst 中直接新增条目该文件由 towncrier 工具管理新增变更应写在news/目录下的片段文件中。news/ 目录towncrier 片段机制news/ 目录是未发布变更的暂存区当前仓库中共有 14 个片段文件命名遵循 towncrier 约定issue编号.类型.rst13084.bugfix.rst 14160.trivial.rst 14171.bugfix.rst 14177.trivial.rst 14235.feature.rst 14237.bugfix.rst 8573.bugfix.rst 9456.bugfix.rst certifi.vendor.rst distlib.vendor.rst msgpack.vendor.rst packaging.vendor.rst platformdirs.vendor.rst例如news/14235.feature.rstSpeed up installing a wheel with console scripts by not resolving every PATH entry.—— 这是编号 14235 的新功能条目news/13084.bugfix.rstFix pips self version check reporting an outdated version from the environment instead of the running pip when run as a zipapp.—— 修复以 zipapp 方式运行时自检版本误报的缺陷news/9456.bugfix.rstKeep --version available only for pip and prevent its use in subcommands.形如certifi.vendor.rst的片段用于记录 vendor内嵌依赖升级对应的发布分类是Vendored Libraries。这些片段在发布时由 towncrier 合并进 NEWS.rst同时片段文件被清空。合并行为由 pyproject.toml 中的[tool.towncrier]配置控制[tool.towncrier] # 片段存放目录 directory news/ # 片段渲染模板 template tools/news/template.rst片段模板位于 tools/news/template.rst它定义了每个版本区块的分类顺序与标题样式。此外pyproject.toml 还约束了文档构建时使用的 towncrier 相关依赖towncrier 24与sphinxcontrib-towncrier 0.2.0a0sphinxcontrib-towncrier正是.. towncrier-draft-entries::指令的提供者。从更新日志反查源码以 26.2 的索引缓存刷新为例更新日志最大的价值在于每个条目都能在源码中找到对应实现。以 26.2 引入的索引响应缓存刷新机制为例Cache simple responses in accordance to theirCache-Controlheader instead of always revalidating on every request. To refresh cached package index responses and ensure newly published packages are found, use--refresh-package package.在 src/pip/_internal/cli/cmdoptions.py 中可以看到对应的选项定义约第 1027–1032 行def refresh_package() - Option: ... --refresh-package, destrefresh_package, ...其回调_handle_refresh_package会校验参数个数refresh_package随后被注册到索引相关选项组第 1392 行附近。这印证了 NEWS 中--refresh-package package用于刷新某个包的索引缓存的用法——该选项正是为配合 26.2 的Cache-Control缓存语义而新增。同一版本的另一个相关条目也与之呼应Newly published packages will no longer be immediately visible to pip if the index uses caching. To install a newly published package, use--refresh-package.这意味着升级到 26.2 后如果索引启用了缓存新发布包不会立即可见需要显式--refresh-package才能强制刷新这是更新日志中Deprecations and Removals类目下的一条重要行为变更值得所有依赖内部索引或私有源的用户留意。版本演进的时间线速览26.x 与 25.x 重点从 NEWS.rst 可梳理出近年 pip 的演进主线26.2.1 / 26.22026-07 ~ 2026-08支持 Python 3.15#14208新增--only-deps、--no-require-hashes、--no-proxy-env选项索引响应按Cache-Control缓存配合--refresh-package使用约束文件含PIP_CONSTRAINT不再影响隔离构建环境改用--build-constraint/PIP_BUILD_CONSTRAINT实验性--use-featurevenv-isolation以标准虚拟环境隔离构建子进程修复 CVE-2026-13346链接文件名 URL 路径双重解码问题支持pylock.toml的upload-time字段--uploaded-prior-to可配合-r pylock.toml。26.1 / 26.1.1 / 26.1.22026-04 ~ 2026-05放弃 Python 3.9#13795实验性支持从标准化pylock.toml读取需求-r pylock.tomlPEP 751 方向--uploaded-prior-to支持天数时长如P3D复杂的依赖冲突场景下解析提速、大依赖树内存占用下降。26.0 / 26.0.12026-01 ~ 2026-02命令行帮助输出彩色化支持 PEP 723 内联脚本元数据安装--requirements-from-script新增--all-releases、--only-final、--uploaded-prior-to选项实验性--use-feature inprocess-build-deps同进程安装构建依赖更快且可靠支持--no-clean、--no-cache-dir删除 egg 片段中非裸项目名的支持。25.32025-10移除setup.py develop旧式 editable 支持要求 setuptools 64移除--global-option/--build-option--config-settings成为唯一入口新增--build-constraint构建约束pip 自身构建改用 flit-core不影响用户安装行为。25.2 / 25.1 / 25.1.12025-04 ~ 2025-07声明支持 Python 3.14下载断点续传与重试默认开启--resume-retries控制重试次数新增--groupPEP 735 Dependency Groups 安装新增实验性pip lock命令PEP 751放弃 Python 3.8Python 3.14 不再允许使用pkg_resources元数据后端支持 PEP 738 Android wheels、iOS wheelsPEP 73024.3。更早的重要里程碑24.xpip 自身以 GitHub Actions 可信发布 PEP 740 数字签名系统证书与 certifi 证书同时用于 HTTPS 校验--use-deprecatedlegacy-certs可回退http-v2新磁盘缓存格式内存占用更低。23.x--break-system-packagesPEP 668 EXTERNALLY-MANAGED--keyring-providerper-requirement--config-settings新增-C短选项。22.x--dry-run、pip inspect、PEP 691 JSON 索引、truststore 后端、--report安装报告、PEP 723。21.xPython 2 支持移除21.0新 resolver 默认启用20.3 起PEP 610 editable 检测。20.xpip cache命令、pip debug命令、新 resolver2020-resolverbeta 到默认的演进、manylinux2010/2014 支持。内嵌依赖Vendored Libraries的变更记录pip 将大量第三方库以 vendor 方式内嵌在 src/pip/_vendor/ 下每次升级都会在更新日志的Vendored Libraries分类中列出。以 26.2 为例Vendored Libraries ------------------ - Upgrade certifi to 2026.6.17 - Upgrade distlib to 0.4.2 - Upgrade idna to 3.18 - Upgrade platformdirs to 4.10.0 - Upgrade pygments to 2.20.0 - Upgrade requests to 2.34.2 - Upgrade tomli to 2.4.1 - Upgrade urllib3 to 2.7.0内嵌依赖的完整清单记录在 src/pip/_vendor/vendor.txt而各依赖的补丁位于 tools/vendoring/patches/如certifi.patch、requests.patch、urllib3.patch等。26.2 还新增了一项流程性变更在 vendored 库旁附带 CycloneDX SBOM软件物料清单文件仓库中可找到 src/pip/_vendor/bom.cdx.json。结合更新日志与这些文件可以完整审计 pip 内嵌依赖的来源、版本与修补情况。如何利用更新日志排查升级影响升级 pip 前建议按以下顺序阅读更新日志看Deprecations and Removals确认自己依赖的选项、环境变量或行为是否被移除。典型例子26.2 起PIP_CONSTRAINT不再影响隔离构建环境25.3 移除--global-option26.1 放弃 Python 3.9。看Features中带experimental或use-feature的条目这些功能尚未默认启用若希望提前体验可显式打开如--use-featurevenv-isolation、--use-featureinprocess-build-deps。看Bug Fixes中的安全条目带 CVE 编号的修复如 26.2 的 CVE-2026-13346应优先升级。看Vendored Libraries若你所在环境依赖特定 CA 证书或 HTTP 行为certifi / requests / urllib3 的升级值得关注。对照测试仓库 tests/ 下有大量与更新日志条目对应的回归测试如test_refresh_package.py、test_lock.py、test_utils_pylock.py需要深入了解某条变更的实现细节时可据此反查验证逻辑。总结pip 的更新日志体系由三层组成docs/html/news.rst入口 指令、NEWS.rst已发布的完整历史由 towncrier 管理与news/未发布片段。理解这套机制后你既可以快速追踪 pip 的功能演进索引缓存刷新、pylock、venv-isolation 等都是近年主线也能规范地参与贡献——为新变更在news/目录添加符合命名规范的片段而非直接修改 NEWS.rst。更新日志是通往源码的最佳索引配合 docs/pip_sphinxext.py 的指令实现、src/pip/_internal/cli/cmdoptions.py 的选项定义与 tests/ 中的回归测试你可以对任何一条历史变更做到文档可读、源码可查、测试可验。【免费下载链接】pipThe Python package installer项目地址: https://gitcode.com/gh_mirrors/pi/pip创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考