[Feature] 支持最新 pip 打包规范(PEP 517/518),补全 pyproject.toml 并移除 distutils 依赖
Author: diaoyunxiCreated Jul 9, 2026Updated Jul 10, 2026
描述
pygame 2.6.1 的源码仓库根目录缺少 pyproject.toml 文件,构建流程仍完全依赖传统的 setup.py + setup.cfg,并大量使用已在 Python 3.12 中移除的 distutils 模块。随着 pip 25.3 强制启用 PEP 517 构建模式并移除 --no-use-pep517 选项,以及非 PEP 660 的 setup.py develop 可编辑安装方式被废弃,pygame 在新版本 pip 与新版本 Python 下的源码安装/构建体验持续恶化。建议 pygame 补全 pyproject.toml、完整声明 build-system.requires,并彻底移除对 distutils 的依赖,以符合最新 pip 打包规范。
复现步骤
- 确认安装最新版 pip:
python -m pip install --upgrade pip(当前为 pip 25.3) - 在没有预编译 wheel 的环境(如较新 Python 版本或非主流平台)下执行源码安装:或从源码构建:
pip install pygame==2.6.1git clone https://github.com/pygame/pygame.git cd pygame pip install . - 在 Python 3.12+ 环境下,构建过程中
buildconfig/vstools.py等模块会尝试导入distutils.msvccompiler/setuptools._distutils.msvccompiler,触发ModuleNotFoundError。 - 尝试可编辑安装
pip install -e .时,因缺少 PEP 660 支持,pip 25.3 不再回退到setup.py develop。
预期行为
- 项目根目录包含符合 PEP 518 规范的
pyproject.toml,其中[build-system]表完整声明构建后端及构建期依赖(如setuptools、cython等)。 - 构建流程完全遵循 PEP 517 接口,不依赖任何已废弃的
distutils模块。 - 在 pip 25.3+ 及 Python 3.12+ 环境下,源码安装与可编辑安装均可正常完成。
实际行为
- 仓库根目录不存在
pyproject.toml文件(已通过 GitHub API 确认 main 分支根目录文件列表,仅有setup.py、setup.cfg)。 setup.py(约 34KB)及buildconfig/目录中仍存在多处distutils导入,在 Python 3.12+(distutils 已移除)下导致构建失败。- 此前的迁移尝试 PR #4198("Phasing Out Distutils And Bringing the Build System Up To PEP 517")和 PR #4212("Compliance with PEP517 and PEP632")均处于关闭/草稿状态,尚未合并。
- 已有用户在 Issue #4755 中报告 Python 3.14 下因
distutils.msvccompiler缺失导致的安装失败。
️ 环境信息
- pygame 版本:2.6.1(最新稳定版)
- pip 版本:25.3(最新版,强制 PEP 517 构建模式)
- Python 版本:3.12+(distutils 已移除;3.14 彻底移除)
- 操作系统:跨平台(Windows / macOS / Linux 均受影响)
- 相关依赖:
setuptools、cython(构建期),当前未通过pyproject.toml的build-system.requires声明
背景与参考
说明:本 Issue 为规范合规性请求,无单一具体报错日志。以下为公开的相关 issue 中记录的典型错误与权威规范参考。
pip 25.3 关键变更:
- 强制启用 PEP 517 构建模式,移除
--no-use-pep517参数,未适配 PEP 517 的项目会触发构建失败 - 移除非 PEP 660 的 legacy
setup.py develop可编辑安装方式,需setuptools >= 64支持 PEP 660 - 新增
--build-constraint选项用于构建期约束
相关 issue / PR:
- PR #4198:Phasing Out Distutils And Bringing the Build System Up To PEP 517(草稿,已关闭)
- PR #4212:Compliance with PEP517 and PEP632(已关闭)
- Issue #4755:[CRITICAL] Python 3.14 Pygame Installation Failure(已关闭,记录了
ModuleNotFoundError: No module named 'distutils.msvccompiler'的完整堆栈)
典型错误片段(摘自公开 Issue #4755,非本提交者私有日志):
File ".../buildconfig/vstools.py", line 6, in <module>
from setuptools._distutils.msvccompiler import MSVCCompiler, get_build_architecture
ModuleNotFoundError: No module named 'setuptools._distutils.msvccompiler'权威规范参考:
补充说明
建议的改进方向:
- 在仓库根目录新增
pyproject.toml,声明[build-system]表:[build-system] requires = ["setuptools>=64", "cython>=3.0", "wheel"] build-backend = "setuptools.build_meta" - 彻底移除
setup.py与buildconfig/中所有distutils导入,替换为setuptools对应实现或现代替代方案。 - 确保
setup.py的build_meta后端正确实现 PEP 517 钩子(build_wheel、build_sdist、get_requires_for_build_wheel等)。 - 支持 PEP 660 可编辑安装(
pip install -e .),需setuptools >= 64。 - 在 CI 中使用
pip wheel/python -m build替代直接调用setup.py,与 PEP 517 构建模式对齐。
感谢 pygame 维护团队的长期付出!理解 pygame 的构建系统涉及大量 C 扩展与跨平台预编译依赖,迁移工作量较大,但这对于项目在 Python 生态中的长期可维护性至关重要。
Source: pygame/pygame