#4878·pygame

[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 打包规范。

复现步骤

  1. 确认安装最新版 pip:python -m pip install --upgrade pip(当前为 pip 25.3)
  2. 在没有预编译 wheel 的环境(如较新 Python 版本或非主流平台)下执行源码安装:
    bash
    pip install pygame==2.6.1
    或从源码构建:
    bash
    git clone https://github.com/pygame/pygame.git
    cd pygame
    pip install .
  3. 在 Python 3.12+ 环境下,构建过程中 buildconfig/vstools.py 等模块会尝试导入 distutils.msvccompiler / setuptools._distutils.msvccompiler,触发 ModuleNotFoundError
  4. 尝试可编辑安装 pip install -e . 时,因缺少 PEP 660 支持,pip 25.3 不再回退到 setup.py develop

预期行为

  • 项目根目录包含符合 PEP 518 规范的 pyproject.toml,其中 [build-system] 表完整声明构建后端及构建期依赖(如 setuptoolscython 等)。
  • 构建流程完全遵循 PEP 517 接口,不依赖任何已废弃的 distutils 模块。
  • 在 pip 25.3+ 及 Python 3.12+ 环境下,源码安装与可编辑安装均可正常完成。

实际行为

  • 仓库根目录不存在 pyproject.toml 文件(已通过 GitHub API 确认 main 分支根目录文件列表,仅有 setup.pysetup.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 均受影响)
  • 相关依赖setuptoolscython(构建期),当前未通过 pyproject.tomlbuild-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

典型错误片段(摘自公开 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'

权威规范参考

补充说明

建议的改进方向

  1. 在仓库根目录新增 pyproject.toml,声明 [build-system] 表:
    toml
    [build-system]
    requires = ["setuptools>=64", "cython>=3.0", "wheel"]
    build-backend = "setuptools.build_meta"
  2. 彻底移除 setup.pybuildconfig/ 中所有 distutils 导入,替换为 setuptools 对应实现或现代替代方案。
  3. 确保 setup.pybuild_meta 后端正确实现 PEP 517 钩子(build_wheelbuild_sdistget_requires_for_build_wheel 等)。
  4. 支持 PEP 660 可编辑安装(pip install -e .),需 setuptools >= 64
  5. 在 CI 中使用 pip wheel / python -m build 替代直接调用 setup.py,与 PEP 517 构建模式对齐。

感谢 pygame 维护团队的长期付出!理解 pygame 的构建系统涉及大量 C 扩展与跨平台预编译依赖,迁移工作量较大,但这对于项目在 Python 生态中的长期可维护性至关重要。