`numpy.distutils` 的状态和迁移建议#

numpy.distutils 在 NumPy 1.23.0 中已被弃用.它将在 Python 3.12 中被移除;对于 Python <= 3.11,它将在 Python 3.12 发布后的两年内不会被移除（2025年10月）.

警告

numpy.distutils 仅在 setuptools < 60.0 版本下测试,新版本可能会导致问题.详情请参见 numpy.distutils 与 setuptools 的交互.

迁移建议#

有几个构建系统是迁移的好选择.假设你的包中有编译代码（如果没有,你有几个好选项,例如 Poetry、Hatch 或 PDM 提供的构建后端）,并且你想使用一个设计良好、现代且可靠的构建系统,我们推荐:

Meson, 以及 meson-python 构建后端
CMake 和 scikit-build-core 构建后端

如果你有适度的需求（只需要简单的 Cython/C 扩展;不需要 Fortran、BLAS/LAPACK、嵌套的 setup.py 文件或其他 numpy.distutils 的功能）并且到目前为止对 numpy.distutils 感到满意,你也可以考虑切换到 setuptools.请注意,``numpy.distutils`` 的大部分功能不太可能移植到 setuptools.

迁移到 Meson#

SciPy 已经为其 1.9.0 版本迁移到 Meson 和 meson-python.在此过程中,解决了 Meson 的 Python 支持及其与 numpy.distutils 功能对等性的剩余问题.*注意:对等性意味着一个大的超集（因为 Meson 是一个好的通用构建系统）;只有少数 BLAS/LAPACK 库选择细节缺失*.SciPy 几乎使用了 numpy.distutils 提供的所有功能,因此如果 SciPy 成功使用 Meson 作为构建系统发布,应该没有剩余的迁移障碍,SciPy 将成为其他迁移包的良好参考.有关 SciPy 迁移的更多详细信息,请参见:

NumPy 将在 1.26 版本中迁移到 Meson.

迁移到 CMake / scikit-build#

下一代的 scikit-build 被称为 scikit-build-core.旧版的 scikit-build 在底层使用了 setuptools,而重写版则没有.像 Meson 一样,CMake 是一个很好的通用构建系统.

迁移到 `setuptools`#

对于仅出于历史原因使用 numpy.distutils 的项目,并且实际上不使用超出 setuptools 也支持的功能,迁移到 setuptools 可能是最少努力的解决方案.要评估这一点,以下是 numpy.distutils 中不存在于 setuptools 中的功能:

嵌套的 setup.py 文件
Fortran 构建支持
BLAS/LAPACK 库支持 (OpenBLAS, MKL, ATLAS, Netlib LAPACK/BLAS, BLIS, 64位 ILP 接口等)
支持一些其他科学计算库,如 FFTW 和 UMFPACK
更好的 MinGW 支持
每个编译器的构建标志定制（例如,`-O3` 和 SSE2 标志是默认的）
一个简单的用户构建配置系统,参见 site.cfg.example
SIMD 内在函数支持
支持 NumPy 特定的 .src 模板格式用于 .c/.h 文件

最广泛使用的功能是嵌套的 setup.py 文件.这个功能可能在未来还会被移植到 setuptools 中（虽然需要一个志愿者,查看 gh-18588 了解状态）.仅使用该功能的项目可以在完成后迁移到 setuptools.如果一个项目只使用几个 setup.py 文件,也可以将这些文件的内容聚合到一个 setup.py 文件中,然后迁移到 setuptools.这涉及到删除所有 Configuration 实例,并使用 Extension 代替.例如,:

from distutils.core import setup
from distutils.extension import Extension
setup(name='foobar',
      version='1.0',
      ext_modules=[
          Extension('foopkg.foo', ['foo.c']),
          Extension('barpkg.bar', ['bar.c']),
          ],
      )

更多详情,请参见 setuptools 文档

`numpy.distutils` 与 `setuptools` 的交互#

建议使用 setuptools < 60.0 .较新的版本可能可以工作,但不保证.这样做的原因是 setuptools 60.0 启用了一个 distutils 的 vendored 副本,包括影响 numpy.distutils 中某些功能的后向不兼容更改.

如果你仅使用简单的 Cython 或 C 扩展,并且最小限度地使用 numpy.distutils 功能（除了嵌套的 setup.py 文件之外,这是其最受欢迎的功能,见 配置）,那么最新的 setuptools 可能会继续工作.如果遇到问题,你也可以尝试 SETUPTOOLS_USE_DISTUTILS=stdlib 以避免 setuptools 中的向后不兼容更改.

无论你做什么,建议在 pyproject.toml 中为你的 setuptools 构建需求设置一个上限,以避免未来的破坏 - 见对于下游包作者.

numpy.distutils 的状态和迁移建议#