Пакетные файлы (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() [source]

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

Примеры

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

get_distribution() [source]

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

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

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

Параметры

subpackage_namestr or None

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

subpackage_pathstr

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

parent_namestr

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

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

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

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

Параметры

subpackage_namestr

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

subpackage_pathstr

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

standalonebool

add_data_files(*files) [source]

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

Параметры

filessequence

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

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

Примечания

Формат каждого элемента последовательности файлов очень гибкий, позволяя множество комбинаций получения файлов из пакета и их конечной установки в системе. Наиболее простое использование — элемент последовательности аргументов 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. (sun, *.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) [source]

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

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

Параметры

data_pathseq or str

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

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

Примечания

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

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) [source]

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

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

add_headers(*files) [source]

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

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

Параметры

filesstr or seq

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

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

add_extension(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(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(*files) [source]

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

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

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

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

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

get_config_cmd() [source]

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

get_build_temp_dir() [source]

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

have_f77c() [source]

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

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

Примечания

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

have_f90c() [source]

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

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

Примечания

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

get_version(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(delete=True) [source]

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

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

Примечания

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

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

make_config_py(name='__config__') [source]

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

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

get_info(*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 — это распознаваемое расширение Fortran (f, f90, f95, f77, for, ftn, pyf). Второй тип используется для всех остальных случаев. См. Преобразование файлов .src с использованием шаблонов.