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

numpy.distutils 已在 NumPy 1.23.0 中被弃用.它将在 Python 3.12 中移除;对于 Python <= 3.11,它将在 Python 3.12 发布后 2 年(2025 年 10 月)才会移除.

警告

numpy.distutils 仅使用 setuptools < 60.0 进行测试,更新的版本可能会中断.有关详细信息,请参阅 numpy.distutils 与 setuptools 的交互 .

迁移建议#

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

  1. Meson 和 meson-python 构建后端

  2. 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-bit 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 documentation

numpy.distutils 与 setuptools 的交互#

建议使用 setuptools < 60.0 .更新的版本可能有效,但不保证.原因是 setuptools 60.0 启用了一个 vendored 版本的 distutils ,其中包括影响 numpy.distutils 中某些功能的不向后兼容的更改.

如果您仅仅是使用简单的带有少量 numpy.distutils 功能(嵌套 setup.py 文件是最常用的功能, 参见 Configuration )的Cython或者C扩展,那么最新的 setuptools 很可能继续工作.如果遇到问题,您也可以尝试 SETUPTOOLS_USE_DISTUTILS=stdlib 来避免 setuptools 中向后不兼容的更改.

无论您做什么,都建议在您的 pyproject.toml 中为您的 setuptools 构建要求设置一个上限,以避免将来出现中断 - 请参阅 对于下游软件包的作者 .