psutil 7.0.0 告别 Python 2.7:从 0.36% 下载占比到 1500 行兼容代码清理的完整决策记录

原创2026-09-22 20:58:151,854 阅读
文章标签:可观测性系统编程

psutil 7.0.0 告别 Python 2.7:从 0.36% 下载占比到 1500 行兼容代码清理的完整决策记录

本文基于 psutil 官方博客《Letting go of Python 2.7》(docs/blog/2025/drop-py27.rst)撰写。该博客记录了 psutil 于 7.0.0(2025-02-13 发布)正式移除 Python 2.7 支持的决策依据、维护代价与拆除过程。读完本文,你将掌握:psutil 放弃 Python 2.7 的完整数据链条、为兼容旧版本付出的工程成本、移除时如何处理旧版本分支与安装提示,以及当前仓库中 Python 版本支持的源码级现状(MIN_PY_VERSION = (3, 8) 与 abi3 单 wheel 策略)。

一、背景:三年前的"不可能"承诺

在 psutil 的版本历史上,Python 2.7 支持问题最早可以追溯到 2017 年 6 月的 issue #1053(Python 2.7 支持议题)。彼时作者 Giampaolo Rodola 在 3 年前面对"何时放弃 Python 2.7"的提问时,态度非常坚决:

Not a chance, for many years to come. [Python 2.7] currently represents 7-10% of total downloads, meaning around 70k / 100k downloads per day.

——"绝无可能,未来很多年都不会。Python 2.7 目前占总下载量的 7-10%,相当于每天 7 万到 10 万次下载。"

当时的判断并非没有道理:近十分之一的用户在依赖 Python 2.7,贸然放弃会直接切断这一大批用户。然而仅仅 3 年之后,市场数据给出了截然不同的答案——Python 2.7 的下载占比骤降至 0.36%。这也正是 psutil 7.0.0 最终决定放手的原因。

二、数据说话:Python 2.7 三年间的断崖式下跌

博客给出了使用 pypinfo 统计的 psutil 各 Python 版本月度下载数据(命令与完整输出如下):

$ pypinfo --percent psutil pyversion
Served from cache: False
Data processed: 4.65 GiB
Data billed: 4.65 GiB
Estimated cost: $0.03
python_version percent download_count
3.10 23.84% 26,354,506
3.8 18.87% 20,862,015
3.7 17.38% 19,217,960
3.9 17.00% 18,798,843
3.11 13.63% 15,066,706
3.12 7.01% 7,754,751
3.13 1.15% 1,267,008
3.6 0.73% 803,189
2.7 0.36% 402,111
3.5 0.03% 28,656
Total 110,555,745

几个值得注意的读数:

  • Python 2.7 仅剩 0.36%,月度下载约 40 万次,仅为 3.10 版本(23.84%)的六十分之一左右;
  • 按照 pypistats.org 的独立统计口径,Python 2.7 下载占比为 0.28%,约合每天 1.5 万次下载;
  • 头部版本高度集中在 3.7~3.11 之间(合计超过 90%),而 3.13 作为当时最新版本已经显现上升势头(1.15%)。

对于维护者而言,当某个运行环境的用户占比跌破 1% 时,继续为其维持完整的兼容工作已经很难再被证明是合理的投入。

三、"维持 2.7 还能跑"背后的真实代价

在放弃之前,psutil 仍然通过"旧 PyPI backports + 定制化的 GitHub Actions workflow(Linux/macOS)+ 第三方 Appveyor 服务(Windows)"维持着 Python 2.7 的测试与发布。用作者的话说,"让 2.7 存活变得越来越困难,但依然可行"。而"可行"二字背后,是一长串逐年堆积的工程债:

1. 双重兼容层:Python 与 C 代码同时打补丁

  • 仓库中存在一个专门的 Python 兼容层 psutil/_compat.py,用来抹平 Python 2/3 在字符串、异常、迭代器等方面的行为差异;
  • C 源码中散落着大量 #if PY_MAJOR_VERSION <= 3 之类的条件编译分支;
  • Python 侧与 C 侧同时进行 str-vs-unicode 的类型反复切换(当前仓库中 psutil/arch/windows/proc_peb.c、psutil/arch/windows/services.c 仍能见到 PyUnicode_FromWideChar 这类 unicode 转换逻辑,正是这一历史负担的痕迹)。

2. 语言特性被冻结

  • 不能使用 f-string(Python 3.6+ 语法),字符串拼接只能退回 format() / %;
  • 不能自由使用标准库 enum 模块定义常量,导致常量 API 的形状在 Python 2 与 Python 3 上不一致(这一影响在今天依然能观察到:直到 8.0.0 规划中才引入统一的 enum 常量类,见 docs/changelog.rst)。

3. 工具链与依赖被冻结

  • 需要锁定过时的 pip 版本以及过时的依赖版本,才能保证在 Python 2.7 环境中正常安装运行。

4. CI 成本翻倍

  • 每个 commit 需要额外跑 4 个 Python 2.7 专属 CI job(Linux、macOS、Windows 32 位、Windows 64 位),直接拖慢整个流水线并显著提高 flaky(不稳定)概率。

5. 每次发版多出 7 个 wheel

以 psutil 6.1.1 为例,每次发布都要额外构建并上传如下 7 个 cp27 wheel:

psutil-6.1.1-cp27-cp27m-macosx_10_9_x86_64.whl
psutil-6.1.1-cp27-none-win32.whl
psutil-6.1.1-cp27-none-win_amd64.whl
psutil-6.1.1-cp27-cp27m-manylinux2010_i686.whl
psutil-6.1.1-cp27-cp27m-manylinux2010_x86_64.whl
psutil-6.1.1-cp27-cp27mu-manylinux2010_i686.whl
psutil-6.1.1-cp27-cp27mu-manylinux2010_x86_64.whl

涵盖 macOS、Windows 32/64 位、Linux manylinux2010 的 i686/x86_64 双 ABI(cp27m 与 cp27mu)组合。对比当前仓库的发布策略(见下文第五节),这 7 个 wheel 恰恰是旧时代"多平台 × 多 ABI 逐一构建"的缩影。

四、拆除过程:一次"令人解放"的瘦身

移除工作由 PR #2481 完成,一次性删除了约 1500 行代码。作者在博客中形容这次删除"令人感到解放(It felt liberating)"。

拆除的同时,psutil 为存量 Python 2.7 用户做了两项明确安排:

1. 6.1.x 系列进入"仅关键修复"维护模式

  • 6.1.* 系列将继续支持 Python 2.7,但只接收关键 bug 修复,不再增加新功能;
  • 该系列维护在专门的 release-6.1.1 分支上。

2. setup.py 保留 Python 2.7 语法兼容,输出可读的错误提示

作者刻意让 setup.py 在语法层面保持与 Python 2.7 兼容,这样当用户在 Python 2.7 环境中从 PyPI 拉取 tarball 并执行 pip install psutil 时,不会因为语法错误而输出一串令人困惑的 traceback,而是看到明确指引:

$ pip2 install psutil
As of version 7.0.0 psutil no longer supports Python 2.7.
Latest version supporting Python 2.7 is psutil 6.1.X.
Install it with: "pip2 install psutil==6.1.*".

这一设计思路非常值得借鉴:版本移除不是简单地把门槛抬高,而是要在"被移除方"最容易遇到错误的位置,放置清晰、可执行的下一步指引。

五、仓库现状:Python 2.7 移除后的源码级佐证

在当前的 psutil 仓库中,Python 2.7 的痕迹已经从各个层面被清除干净,这些都可以直接阅读源码验证:

1. 包级元数据:最低版本锁定 Python 3.8

  • setup.py 中定义了 MIN_PY_VERSION = (3, 8),并据此生成 python_requires=">={}.{}".format(*MIN_PY_VERSION),直接向 pip 声明安装门槛;
  • psutil/init.py 的模块 docstring 明确写着:"Supported Python versions are cPython 3.8+ and PyPy."
  • pyproject.toml 中 black 与 ruff 的 target-version 均为 "py38",测试依赖也按 python_version 条件拆分(如 pytest 在 3.10 以下用旧版、以上用 pytest>=9)。

2. 发布策略:从 7 个 cp27 wheel 到单一 abi3 wheel

对比第六节中列出的 7 个 cp27 wheel,当前 setup.py 采用 Py_LIMITED_API 策略:在 CPython 且非 free-threaded(无 GIL)构建下,启用 py_limited_api 并生成 cp38-abi3 标签的 wheel——一个 wheel 即可覆盖 Python 3.8 及之后的全部版本(含尚未发布的新版本)。这正是摆脱 Python 2.7 之后,构建与发布链路得以大幅简化的直接红利。

3. 分类器:明确 "Python 3 Only"

setup.py 的 classifiers 中包含了:

'Programming Language :: Python :: 3 :: Only',
'Programming Language :: Python :: Implementation :: CPython',
'Programming Language :: Python :: Implementation :: PyPy',
'Programming Language :: Python :: Free Threading',

同时保留对 CPython、PyPy 以及 free-threaded Python(无 GIL 构建)的声明,说明 psutil 在放弃 Python 2.7 之后,将兼容重心转向了新解释器形态。

4. Changelog 中的官方记录

  • docs/changelog.rst 的 7.0.0(2025-02-13)条目在 "Dropped support" 一节正式记录:"drop Python 2.7 support. Latest version supporting it is psutil 6.1.X (pip2 install psutil==6.1.*)";
  • 更值得注意的是,处于开发中的 8.0.0 条目里仍有一条:":gh:2766: remove remaining Python 2.7 compatibility shims"——说明即便在 7.0.0 完成主体移除后,仓库深处仍残留少量 2.7 兼容垫片,直到 8.0.0 才被彻底清空。这也印证了兼容性债务清理往往不是一次 PR 就能终结的。

六、迁移指引:如果你还在 Python 2.7 上

  • 如果你仍运行在 Python 2.7 环境,psutil 官方给出的落地方案是固定使用 6.1.x 系列:pip2 install psutil==6.1.*;
  • 6.1.x 仅接收关键 bug 修复,不再引入新特性,因此不建议基于该分支进行新功能开发;
  • 长期来看,应将运行环境升级到 Python 3.8+(当前 psutil 的最低支持版本),以便获得后续版本的完整 API、性能优化与修复。

七、时间线:psutil 逐版本"割舍"旧 Python 的完整记录

从博客 "Related" 一节可以看到,psutil 对旧版 Python 的放弃是一个循序渐进、有明确节奏的过程:

时间 事件 内容
2017-06 issue #1053 Python 2.7 支持议题首次提出
2022-04 PR #2099 放弃 Python 2.6 支持
2023-04 PR #2246 放弃 Python 3.4 与 3.5 支持
2024-12 PR #2481 放弃 Python 2.7 支持(约 1500 行代码被移除)

值得强调的细节是:在放弃 Python 2.7 之前,psutil 已经先后放弃了更老的 2.6 与 3.4/3.5——每次移除都遵循"先用数据评估用户占比,再为存量用户安排 LTS 式维护分支,最后在安装入口给出可读提示"的成熟流程。这条路径本身就是一份可复用的"Python 版本退役操作手册"。

总结

psutil 告别 Python 2.7 的过程可以浓缩为三个关键词:数据驱动(0.36% 的下载占比)、债务清理(约 1500 行兼容代码与 7 个专属 wheel)、平滑过渡(6.1.x 仅修复分支 + 可读的安装错误提示)。从当前仓库的源码看,这一决策的红利已经显现:构建策略升级为 abi3 单一 wheel,代码库得以使用 f-string、enum 与现代类型注解,CI 与测试矩阵也不再需要为陈年解释器买单。对于仍在维护多 Python 版本兼容层的项目来说,这篇博客与仓库中的落地痕迹(setup.py、pyproject.toml、docs/changelog.rst)共同构成了一份难得的实战样本。

登录后查看全文
psutil