Упаковщики (numpy.distutils)

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

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

Модули в numpy.distutils

• distutils.misc_util

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

class numpy.distutils.misc_util.Configuration(package_name=None, parent_name=None, top_path=None, package_path=None, **attrs) [source]

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

todict(self) [source]

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

Примеры

>>> setup(**config.todict())                           

get_distribution(self) [source]

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

get_subpackage(self, subpackage_name, subpackage_path=None, parent_name=None, caller_level=1) [source]

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

Параметры

subpackage_namestr or None

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

subpackage_pathstr

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

parent_namestr

Имя родительского пакета.

add_subpackage(self, subpackage_name, subpackage_path=None, standalone=False) [source]

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

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

Параметры

subpackage_namestr

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

subpackage_pathstr

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

standalonebool

add_data_files(self, *files) [source]

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

Параметры

filessequence

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

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

Примечания

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

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

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

1. file.txt -> (., file.txt)-> родительский/file.txt
2. foo/file.txt -> (foo, foo/file.txt) -> родительский/foo/file.txt
3. /foo/bar/file.txt -> (., /foo/bar/file.txt) -> родительский/file.txt
4. *.txt -> родительский/a.txt, родительский/b.txt
5. foo/*.txt`` -> родительский/foo/a.txt, родительский/foo/b.txt
6. */*.txt -> (*, */*.txt) -> родительский/c/a.txt, родительский/d/b.txt
7. (sun, file.txt) -> родительский/sun/file.txt
8. (sun, bar/file.txt) -> родительский/sun/file.txt
9. (sun, /foo/bar/file.txt) -> родительский/sun/file.txt
10. (sun, *.txt) -> родительский/sun/a.txt, родительский/sun/b.txt
11. (sun, bar/*.txt) -> родительский/sun/a.txt, родительский/sun/b.txt
12. (sun/*, */*.txt) -> родительский/sun/c/a.txt, родительский/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(self, data_path) [source]

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

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

Параметры

data_pathseq or str

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

• 2-последовательностью (<суффикс каталога данных>, <путь к каталогу данных>)
• путь к каталогу данных, где суффикс каталога данных по умолчанию – директория пакета.

Примечания

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

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(self, *paths) [source]

Добавляет пути в директории включения конфигурации.

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

add_headers(self, *files) [source]

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

Добавляет заданную последовательность файлов в начало списка headers. По умолчанию, заголовки будут установлены в директории <python- include>/<self.name.replace(‘.’,’/’)>/ . Если элемент files – кортеж, то его первый аргумент определяет фактическое место установки относительно пути <python-include>.

Параметры

filesstr or seq

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

• 2-последовательностью (<суффикс директории включения>,<путь к файлу заголовка(ов)>)
• путь(и) к файлу(ам) заголовка(ов), где суффикс директории включения по умолчанию – имя пакета.

add_extension(self, name, sources, **kw) [source]

Добавление расширения в конфигурацию.

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

Параметры

namestr

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

sourcesseq

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

include_dirs :

define_macros :

undef_macros :

library_dirs :

libraries :

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 содержит пути к файлам или каталогам, от которых зависят исходные файлы модуля расширения. Если любой путь в списке depends новее, чем модуль расширения, то модуль будет перестроен.

language :

f2py_options :

module_dirs :

extra_infodict or list

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

Примечания

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

add_library(self, name, sources, **build_info) [source]

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

Параметры

namestr

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

sourcessequence

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

build_infodict, optional

Разрешены следующие ключи:

• depends
• macros
• include_dirs
• extra_compiler_args
• extra_f77_compile_args
• extra_f90_compile_args
• f2py_options
• language

add_scripts(self, *files) [source]

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

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

add_installed_library(self, name, sources, install_dir, build_info=None) [source]

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

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

Параметры

namestr

Имя устанавливаемой библиотеки.

sourcessequence

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

install_dirstr

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

build_infodict, optional

Разрешены следующие ключи:

• depends
• macros
• include_dirs
• extra_compiler_args
• extra_f77_compile_args
• extra_f90_compile_args
• f2py_options
• language

Возвращает

None

См. также

add_library, add_npy_pkg_config, get_info

Примечания

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

add_npy_pkg_config(self, template, install_dir, subst_dict=None) [source]

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

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

Параметры

templatestr

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

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=

и будет установлен как foo.ini в подпути ‘lib’.

При кросс-компиляции с помощью 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(self, *paths, **kws) [source]

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

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

get_config_cmd(self) [source]

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

get_build_temp_dir(self) [source]

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

have_f77c(self) [source]

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

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

Примечания

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

have_f90c(self) [source]

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

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

Примечания

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

get_version(self, version_file=None, version_variable=None) [source]

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

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

Примечания

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

make_svn_version_py(self, delete=True) [source]

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

Генерирует файл пакета __svn_version__.py из номера SVN-ревизии, он будет удалён после выхода интерпретатора Python, но будет доступен при выполнении команд sdist и т. п.

Примечания

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

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

make_config_py(self, name='__config__') [source]

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

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

get_info(self, *names) [source]

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

Возвращает информацию (из 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. Этот механизм основан на файле .ini, который содержит все параметры. Файл .ini очень похож на файлы .pc, используемые утилитой pkg-config в Unix:

[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). Файлы npy-pkg-config также можно установить в том же месте, что и для numpy, используя путь, возвращаемый функцией get_npy_pkg_dir.

Использование библиотеки 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 поддерживает автоматическое преобразование файлов исходного кода с именами <somefile>.src. Эта возможность может использоваться для поддержания очень похожих блоков кода, требующих только простых изменений между блоками. Во время фазы сборки setup, если встречается шаблонный файл с именем <somefile>.src, новый файл с именем <somefile> создаётся на основе шаблона и помещается в каталог сборки для использования вместо него. Поддерживаются два вида преобразования шаблонов. Первый вид происходит для файлов с именем <file>.ext.src, где ext — это известное фортран-расширение (f, f90, f95, f77, for, ftn, pyf). Второй вид используется для всех остальных случаев. См. Преобразование файлов .src с использованием шаблонов.