Упаковка#

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

numpy.distutils устарел и будет удален для Python >= 3.12. Подробнее см. Статус numpy.distutils и рекомендации по миграции

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

Обратите внимание, что setuptools делает основные выпуски часто, и они могут содержать изменения, которые нарушают numpy.distutils, который будет не больше не будет обновляться для новых setuptools версиях. Поэтому рекомендуется установить верхнюю границу версии в вашей конфигурации сборки для последней известной версии setuptools который работает с вашей сборкой.

NumPy предоставляет расширенную функциональность distutils, чтобы упростить сборку и установку подпакетов, автоматическую генерацию кода и расширенных модулей, использующих библиотеки, скомпилированные на Fortran. Полезный Configuration класс также предоставляется в numpy.distutils.misc_util что может упростить построение именованных аргументов для передачи в функцию setup (путем передачи словаря, полученного из метода todict() класса). Дополнительная информация доступна в руководство пользователя numpy.distutils.

Выбор и расположение связанных библиотек, таких как BLAS и LAPACK, а также путей включения и других параметров сборки могут быть указаны в site.cfg файл, расположенный в корневом репозитории NumPy или .numpy-site.cfg файл в вашем домашнем каталоге. См. site.cfg.example пример файла, включенного в репозиторий NumPy или sdist для документации.

Модули в numpy.distutils#

ccompiler

ccompiler_opt

Предоставляет CCompilerOpt класс, используемый для обработки оптимизации CPU/оборудования, начиная с разбора аргументов командной строки, управления связью между базовой линией CPU и диспетчеризуемыми функциями, также генерации необходимых C-заголовков и заканчивая компиляцией исходников с правильными флагами компилятора.

cpuinfo.cpu

core.Extension(name, sources[, ...])

Параметры:

exec_command

exec_command

log.set_verbosity(v[, force])

system_info.get_info(name[, notfound_action])

notfound_action:

system_info.get_standard_file(fname)

Возвращает список файлов с именем 'fname' из 1) Системного каталога (расположение каталога этого модуля) 2) Домашнего каталога пользователя (os.environ['HOME']) 3) Локального каталога

Класс конфигурации#

класс numpy.distutils.misc_util.Конфигурация(package_name=None, parent_name=None, top_path=None, package_path=None, **attrs)[источник]#

Создать экземпляр конфигурации для данного имени пакета. Если parent_name не None, то создать пакет как подпакет parent_name пакет. Если top_path и package_path равны None, то они считаются равными пути к файлу, в котором был создан этот экземпляр. Файлы setup.py в дистрибутиве numpy являются хорошими примерами того, как использовать Configuration экземпляр.

todict()[источник]#

Возвращает словарь, совместимый с ключевыми аргументами функции distutils setup.

Примеры

>>> setup(**config.todict())
get_distribution()[источник]#

Возвращает объект дистрибутива distutils для self.

get_subpackage(subpackage_name, subpackage_path=None, parent_name=None, caller_level=1)[источник]#

Вернуть список конфигураций подпакетов.

Параметры:
subpackage_namestr или None

Имя подпакета для получения конфигурации. '*' в subpackage_name обрабатывается как подстановочный знак.

subpackage_pathstr

Если None, то путь предполагается как локальный путь плюс имя подпакета. Если файл setup.py не найден в subpackage_path, то используется конфигурация по умолчанию.

parent_namestr

Имя родителя.

add_subpackage(subpackage_name, subpackage_path=None, автономный=False)[источник]#

Добавить подпакет к текущему экземпляру Configuration.

Это полезно в скрипте setup.py для добавления подпакетов в пакет.

Параметры:
subpackage_namestr

имя подпакета

subpackage_pathstr

если указан, путь к подпакету, такой что подпакет находится в subpackage_path / subpackage_name. Если None, предполагается, что подпакет расположен в локальном пути / subpackage_name.

автономныйbool
add_data_files(*файлы)[источник]#

Добавьте файлы данных в конфигурацию data_files.

Параметры:
файлыпоследовательность

Аргумент(ы) могут быть либо

  • 2-последовательность (<префикс datadir>,<путь к файлу(ам) данных>)

  • пути к файлам данных, где префикс python datadir по умолчанию указывает на каталог пакета.

Примечания

Форма каждого элемента последовательности файлов очень гибкая, позволяя множество комбинаций того, откуда брать файлы из пакета и куда они должны быть в конечном итоге установлены в системе. Наиболее простое использование — когда элемент последовательности аргумента files является простым именем файла. Это приведёт к установке этого файла из локального пути в путь установки пакета self.name (путь пакета). Аргумент file также может быть относительным путём, в этом случае весь относительный путь будет установлен в каталог пакета. Наконец, файл может быть абсолютным путём, в этом случае файл будет найден по абсолютному пути, но установлен в путь пакета.

Это базовое поведение может быть дополнено путем передачи 2-кортежа в качестве аргумента file. Первый элемент кортежа должен указывать относительный путь (в каталоге установки пакета), куда должна быть установлена оставшаяся последовательность файлов (это не связано с именами файлов в исходном дистрибутиве). Второй элемент кортежа — это последовательность файлов, которые должны быть установлены. Файлы в этой последовательности могут быть именами файлов, относительными путями или абсолютными путями. Для абсолютных путей файл будет установлен в корневом каталоге установки пакета (независимо от первого аргумента). Имена файлов и относительные пути будут установлены в каталоге установки пакета под именем пути, указанным в качестве первого элемента кортежа.

Правила для путей установки:

  1. file.txt -> (., file.txt)-> parent/file.txt

  2. foo/file.txt -> (foo, foo/file.txt) -> parent/foo/file.txt

  3. /foo/bar/file.txt -> (., /foo/bar/file.txt) -> parent/file.txt

  4. *.txt -> parent/a.txt, parent/b.txt

  5. foo/*.txt`` -> parent/foo/a.txt, parent/foo/b.txt

  6. */*.txt -> (*, */*.txt) -> parent/c/a.txt, parent/d/b.txt

  7. (sun, file.txt) -> parent/sun/file.txt

  8. (sun, bar/file.txt) -> parent/sun/file.txt

  9. (sun, /foo/bar/file.txt) -> parent/sun/file.txt

  10. (солнце, *.txt) -> parent/sun/a.txt, parent/sun/b.txt

  11. (sun, bar/*.txt) -> parent/sun/a.txt, parent/sun/b.txt

  12. (sun/*, */*.txt) -> parent/sun/c/a.txt, parent/d/b.txt

Дополнительная особенность заключается в том, что путь к файлу данных может быть функцией, которая не принимает аргументов и возвращает фактический путь(и) к файлам данных. Это полезно, когда файлы данных генерируются во время сборки пакета.

Примеры

Добавить файлы в список data_files для включения в пакет.

>>> self.add_data_files('foo.dat',
...     ('fun', ['gun.dat', 'nun/pun.dat', '/tmp/sun.dat']),
...     'bar/cat.dat',
...     '/full/path/to/can.dat')

установит эти файлы данных в:

<package install directory>/
 foo.dat
 fun/
   gun.dat
   nun/
     pun.dat
 sun.dat
 bar/
   car.dat
 can.dat

где <каталог установки пакета> - это каталог пакета (или подпакета), например '/usr/lib/python2.4/site-packages/mypackage' ('C:\Python2.4\Lib\site-packages\mypackage') или '/usr/lib/python2.4/site-packages/mypackage/mysubpackage' ('C:\Python2.4\Lib\site-packages\mypackage\mysubpackage').

add_data_dir(data_path)[источник]#

Рекурсивно добавляет файлы из data_path в список data_files.

Рекурсивно добавляет файлы под data_path в список data_files для установки (и распространения). data_path может быть либо относительным путем, либо абсолютным путем, либо 2-кортежем, где первый аргумент показывает, куда в директории установки должна быть установлена директория данных.

Параметры:
data_pathseq или str

Аргумент может быть либо

  • 2-последовательность (<суффикс datadir>, <путь к каталогу данных>)

  • путь к каталогу данных, где суффикс python datadir по умолчанию соответствует каталогу пакета.

Примечания

Правила для путей установки:

foo/bar -> (foo/bar, foo/bar) -> parent/foo/bar
(gun, foo/bar) -> parent/gun
foo/* -> (foo/a, foo/a), (foo/b, foo/b) -> parent/foo/a, parent/foo/b
(gun, foo/*) -> (gun, foo/a), (gun, foo/b) -> gun
(gun/*, foo/*) -> parent/gun/a, parent/gun/b
/foo/bar -> (bar, /foo/bar) -> parent/bar
(gun, /foo/bar) -> parent/gun
(fun/*/gun/*, sun/foo/bar) -> parent/fun/foo/gun/bar

Примеры

Например, предположим, что исходный каталог содержит fun/foo.dat и fun/bar/car.dat:

>>> self.add_data_dir('fun')                       
>>> self.add_data_dir(('sun', 'fun'))              
>>> self.add_data_dir(('gun', '/full/path/to/fun'))

Установит файлы данных в следующие местоположения:

<package install directory>/
  fun/
    foo.dat
    bar/
      car.dat
  sun/
    foo.dat
    bar/
      car.dat
  gun/
    foo.dat
    car.dat
add_include_dirs(*paths)[источник]#

Добавить пути к каталогам конфигурационных заголовочных файлов.

Добавить заданную последовательность путей в начало списка include_dirs. Этот список будет виден всем модулям расширения текущего пакета.

добавить_заголовки(*файлы)[источник]#

Добавить устанавливаемые заголовки в конфигурацию.

Добавить заданную последовательность файлов в начало списка заголовков. По умолчанию заголовки будут установлены в каталоге //. Если элемент files является кортежем, то его первый аргумент указывает фактическое местоположение установки относительно пути .

Параметры:
файлыstr или seq

Аргумент(ы) могут быть либо:

  • 2-последовательность (<суффикс includedir>,<путь к файлам заголовков>)

  • путь(и) к файлу(ам) заголовков, где суффикс python includedir по умолчанию будет именем пакета.

add_extension(имя, источники, **kw)[источник]#

Добавить расширение к конфигурации.

Создайте и добавьте экземпляр Extension в список ext_modules. Этот метод также принимает следующие необязательные ключевые аргументы, которые передаются в конструктор Extension.

Параметры:
имяstr

имя расширения

источникиseq

список источников. Список источников может содержать функции (называемые генераторами источников), которые должны принимать экземпляр расширения и каталог сборки в качестве входных данных и возвращать исходный файл или список исходных файлов, или None. Если возвращается None, то источники не генерируются. Если у экземпляра расширения нет источников после обработки всех генераторов источников, то модуль расширения не строится.

include_dirs
define_macros
undef_macros
library_dirs
библиотеки
runtime_library_dirs
extra_objects
extra_compile_args
extra_link_args
extra_f77_compile_args
extra_f90_compile_args
export_symbols
swig_opts
зависит

Список depends содержит пути к файлам или каталогам, от которых зависят исходные коды модуля расширения. Если любой путь в списке depends новее модуля расширения, то модуль будет пересобран.

язык
f2py_options
module_dirs
extra_infoсловарь или список

словарь или список словарей ключевых слов для добавления к ключевым словам.

Примечания

Метод self.paths(…) применяется ко всем спискам, которые могут содержать пути.

add_library(имя, источники, **build_info)[источник]#

Добавить библиотеку в конфигурацию.

Параметры:
имяstr

Имя расширения.

источникипоследовательность

Список источников. Список источников может содержать функции (называемые генераторами источников), которые должны принимать экземпляр расширения и каталог сборки в качестве входных данных и возвращать исходный файл или список исходных файлов или None. Если возвращается None, то источники не генерируются. Если у экземпляра Extension нет источников после обработки всех генераторов источников, то модуль расширения не строится.

build_infodict, optional

Допустимы следующие ключи:

  • зависит

  • макросы

  • include_dirs

  • extra_compiler_args

  • extra_f77_compile_args

  • extra_f90_compile_args

  • f2py_options

  • язык

add_scripts(*файлы)[источник]#

Добавить скрипты в конфигурацию.

Добавьте последовательность файлов в начало списка скриптов. Скрипты будут установлены в каталоге /bin/.

add_installed_library(имя, источники, install_dir, build_info=None)[источник]#

Аналогично add_library, но указанная библиотека устанавливается.

Большинство библиотек C, используемых с distutils используются только для сборки расширений Python, но библиотеки, собранные этим методом, будут установлены так, чтобы их можно было повторно использовать сторонними пакетами.

Параметры:
имяstr

Название установленной библиотеки.

источникипоследовательность

Список исходных файлов библиотеки. См. add_library подробности.

install_dirstr

Путь для установки библиотеки относительно текущего подпакета.

build_infodict, optional

Допустимы следующие ключи:

  • зависит

  • макросы

  • include_dirs

  • extra_compiler_args

  • extra_f77_compile_args

  • extra_f90_compile_args

  • f2py_options

  • язык

Возвращает:
None

Смотрите также

add_library, add_npy_pkg_config, get_info

Примечания

Лучший способ закодировать параметры, необходимые для линковки с указанными библиотеками C, — использовать файл "libname.ini" и применить get_info для получения требуемых опций (см. add_npy_pkg_config для получения дополнительной информации).

add_npy_pkg_config(шаблон, install_dir, subst_dict=None)[источник]#

Сгенерировать и установить файл конфигурации npy-pkg из шаблона.

Файл конфигурации, сгенерированный из шаблон установлен в заданном каталоге установки, используя subst_dict для подстановки переменных.

Параметры:
шаблонstr

Путь к шаблону относительно текущего пути пакета.

install_dirstr

Где установить файл конфигурации npy-pkg относительно текущего пути пакета.

subst_dictdict, optional

Если задано, любая строка вида @key@ будет заменено на subst_dict[key] в файле шаблона при установке. Префикс установки всегда доступен через переменную @prefix@, поскольку префикс установки нелегко надежно получить из setup.py.

Смотрите также

add_installed_library, get_info

Примечания

Это работает как для стандартных установок, так и для сборок на месте, т.е. @prefix@ обратитесь к исходному каталогу для сборок на месте.

Примеры

config.add_npy_pkg_config('foo.ini.in', 'lib', {'foo': bar})

Предполагая, что файл foo.ini.in имеет следующее содержимое:

[meta]
Name=@foo@
Version=1.0
Description=dummy description

[default]
Cflags=-I@prefix@/include
Libs=

Сгенерированный файл будет иметь следующее содержание:

[meta]
Name=bar
Version=1.0
Description=dummy description

[default]
Cflags=-Iprefix_dir/include
Libs=

Эта функция может быть экспоненциально медленной для некоторых входных данных, если только

При кросскомпиляции с numpy distutils может потребоваться использовать модифицированные файлы npy-pkg-config. Использование файлов по умолчанию/сгенерированных приведет к линковке с библиотеками хоста (например, libnpymath.a). Для кросскомпиляции вам, конечно, нужно линковаться с целевыми библиотеками, используя установку Python на хосте.

Вы можете скопировать каталог numpy/_core/lib/npy-pkg-config, добавить значение pkgdir в файлы .ini и установить переменную окружения NPY_PKG_CONFIG_PATH, указывающую на каталог с изменёнными файлами npy-pkg-config.

Пример npymath.ini, изменённый для кросскомпиляции:

[meta]
Name=npymath
Description=Portable, core math library implementing C99 standard
Version=0.1

[variables]
pkgname=numpy._core
pkgdir=/build/arm-linux-gnueabi/sysroot/usr/lib/python3.7/site-packages/numpy/_core
prefix=${pkgdir}
libdir=${prefix}/lib
includedir=${prefix}/include

[default]
Libs=-L${libdir} -lnpymath
Cflags=-I${includedir}
Requires=mlib

[msvc]
Libs=/LIBPATH:${libdir} npymath.lib
Cflags=/INCLUDE:${includedir}
Requires=mlib
paths(*paths, **kws)[источник]#

Применить glob к путям и добавить local_path при необходимости.

Применяет glob.glob(…) к каждому пути в последовательности (если необходимо) и добавляет local_path при необходимости. Поскольку это вызывается для всех списков исходных кодов, это позволяет указывать подстановочные символы в списках источников для модулей расширения, библиотек и скриптов, а также позволяет использовать относительные пути к исходному каталогу.

get_config_cmd()[источник]#

Возвращает экземпляр команды конфигурации numpy.distutils.

get_build_temp_dir()[источник]#

Вернуть путь к временному каталогу, где должны размещаться временные файлы.

have_f77c()[источник]#

Проверить наличие компилятора Fortran 77.

Используйте внутри функции-генератора исходного кода, чтобы гарантировать, что экземпляр дистрибутива setup был инициализирован.

Примечания

True, если доступен компилятор Fortran 77 (потому что простой код Fortran 77 удалось успешно скомпилировать).

have_f90c()[источник]#

Проверить наличие компилятора Fortran 90.

Используйте внутри функции-генератора исходного кода, чтобы гарантировать, что экземпляр дистрибутива setup был инициализирован.

Примечания

True, если доступен компилятор Fortran 90 (потому что простой код Fortran 90 смог быть успешно скомпилирован)

get_version(version_file=None, version_variable=None)[источник]#

Попытаться получить строку версии пакета.

Возвращает строку версии текущего пакета или None, если информацию о версии не удалось определить.

Примечания

Этот метод сканирует файлы с именами __version__.py, _version.py, version.py и __svn_version__.py для строковых переменных version, __version__ и _version, пока не будет найден номер версии.

make_svn_version_py(удалить=True)[источник]#

Добавляет функцию данных в список data_files, которая будет генерировать файл __svn_version__.py в текущем каталоге пакета.

Сгенерировать файл __svn_version__.py пакета из номера ревизии SVN, он будет удалён после завершения работы Python, но будет доступен при выполнении команд sdist и т.д.

Примечания

Если __svn_version__.py существовал ранее, ничего не делается.

Это предназначено для работы с исходными каталогами, которые находятся в репозитории SVN.

make_config_py(имя='__config__')[источник]#

Сгенерировать файл __config__.py пакета, содержащий информацию system_info, используемую при сборке пакета.

Этот файл устанавливается в каталог установки пакета.

get_info(*names)[источник]#

Получить информацию о ресурсах.

Возвращает информацию (из system_info.get_info) для всех имен в списке аргументов в одном словаре.

Создание устанавливаемых C-библиотек#

Обычные библиотеки C (установленные через add_library) не установлены и используются только во время сборки (они статически линкуются). Устанавливаемая C-библиотека - это чистая C-библиотека, которая не зависит от C-рантайма Python и устанавливается так, что может использоваться сторонними пакетами. Чтобы собрать и установить C-библиотеку, вы просто используете метод add_installed_library вместо add_library, который принимает те же аргументы, за исключением дополнительного install_dir аргумент:

.. hidden in a comment so as to be included in refguide but not rendered documentation
  >>> import numpy.distutils.misc_util
  >>> config = np.distutils.misc_util.Configuration(None, '', '.')
  >>> with open('foo.c', 'w') as f: pass

>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')

файлы npy-pkg-config#

Чтобы сделать необходимые параметры сборки доступными для сторонних лиц, вы можете использовать npy-pkg-config механизм, реализованный в numpy.distutilsравно None (по умолчанию), тогда результаты из [1,

[meta]
Name: foo
Version: 1.0
Description: foo library

[variables]
prefix = /home/user/local
libdir = ${prefix}/lib
includedir = ${prefix}/include

[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo

Обычно файл необходимо генерировать во время сборки, поскольку требуется некоторая информация, известная только во время сборки (например, префикс). Это в основном автоматизировано, если используется Configuration метод add_npy_pkg_config. Предположим, у нас есть файл шаблона foo.ini.in следующим образом:

[meta]
Name: foo
Version: @version@
Description: foo library

[variables]
prefix = @prefix@
libdir = ${prefix}/lib
includedir = ${prefix}/include

[default]
cflags = -I${includedir}
libs = -L${libdir} -lfoo

и следующий код в setup.py:

>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')
>>> subst = {'version': '1.0'}
>>> config.add_npy_pkg_config('foo.ini.in', 'lib', subst_dict=subst)

Это установит файл foo.ini в каталог package_dir/lib, и файл foo.ini будет сгенерирован из foo.ini.in, где каждый @version@ будет заменен на subst_dict['version']. Словарь имеет дополнительное правило подстановки префикса, автоматически добавленное, которое содержит префикс установки (поскольку его нелегко получить из setup.py).

Повторное использование библиотеки C из другого пакета#

Информация легко извлекается из get_info функция в numpy.distutils.misc_util:

>>> info = np.distutils.misc_util.get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=info)

Дополнительный список путей для поиска .ini файлов может быть передан get_info.

Преобразование .src файлы#

NumPy distutils поддерживает автоматическое преобразование исходных файлов с именами .src. Эта возможность может использоваться для поддержания очень похожих блоков кода, требующих лишь простых изменений между блоками. На этапе сборки setup, если встречается файл-шаблон с именем .src, новый файл с именем создаётся из шаблона и помещается в каталог сборки для использования вместо него. Поддерживаются две формы преобразования шаблонов. Первая форма применяется для файлов с именами .ext.src, где ext — это распознаваемое расширение Fortran (f, f90, f95, f77, for, ftn, pyf). Вторая форма используется во всех остальных случаях. См. Преобразование файлов .src с использованием шаблонов.