`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 提供的构建后端)，并且你希望使用一个设计良好、现代且可靠的构建系统，我们建议

  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 位 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` 构建要求设置一个上限，以避免未来的问题 - 请参阅 对于下游包作者。

本页内容