`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 可能是成本最低的解决方案。为了评估这一点，以下列出了 setuptools 中不具备的 numpy.distutils 功能：

嵌套的 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 副本，其中包括影响 numpy.distutils 某些功能的向后不兼容更改。

如果您仅使用简单的 Cython 或 C 扩展，并且对 numpy.distutils 的功能使用程度有限，仅限于嵌套的 setup.py 文件（这是其最受欢迎的功能，请参阅 Configuration），那么最新版本的 setuptools 很可能仍然有效。如果遇到问题，您还可以尝试设置 SETUPTOOLS_USE_DISTUTILS=stdlib 以避免 setuptools 中的向后不兼容更改。

无论如何，建议在 pyproject.toml 中为您的 setuptools 构建要求设置一个上限，以避免未来出现问题 - 请参阅对于下游包作者。

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