Статус numpy.distutils и рекомендации по миграции

numpy.distutils устарел в NumPy 1.23.0. Он будет удалён для Python 3.12; для Python <= 3.11 он не будет удалён до двух лет после выпуска Python 3.12 (октябрь 2025 года).

Предупреждение

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 перешла на Meson и meson-python для своего выпуска 1.9.0. В этом процессе были решены оставшиеся проблемы с поддержкой Python в Meson и соответствием функциональности с numpy.distutils. Примечание: соответствие означает большой суперсет (поскольку Meson — хорошая универсальная система сборки); отсутствуют лишь несколько полезностей при выборе библиотек BLAS/LAPACK. SciPy использует почти всю функциональность, которую предлагает numpy.distutils, поэтому, если SciPy успешно выпустила релиз с Meson в качестве системы сборки, никаких препятствий для миграции не должно остаться, и SciPy будет хорошей ссылкой для других пакетов, которые мигрируют. Подробнее о миграции SciPy см.:

NumPy перейдёт на Meson для версии 1.26.

Переход на 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.

В любом случае рекомендуется установить верхнюю границу для вашего требования к сборке setuptools в pyproject.toml, чтобы избежать будущих проблем — см. Для авторов пакетов-потребителей.

© 2005–2024 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/2.0/reference/distutils_status_migration.html