psutil 7.0.0 告别 Python 2.7:从 0.36% 下载占比到 1500 行兼容代码清理的完整决策记录
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)共同构成了一份难得的实战样本。