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

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

Модули в 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_name обрабатывается как символ подстановки.

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

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

standalonebool

add_data_files(self, *files) [source]

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

Параметры

filessequence

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

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

Примечания

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

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

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

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-последовательность (<суффикс каталога данных>, <путь к каталогу данных>)
• путь к каталогу данных, где суффикс каталога данных 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(self, *paths) [source]

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

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

add_headers(self, *files) [source]

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

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

Параметры

filesstr or seq

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

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

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 аргумента:

>>> 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 = 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 с помощью шаблонов.