Упаковщики (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

Класс Configuration

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 или 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.

Параметры

filesпоследовательность

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

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

Примечания

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

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

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

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_pathпоследовательность или 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(*paths)[source]

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

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

add_headers(*files)[source]

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

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

Параметры

filesstr или seq

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

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

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 или list

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

Примечания

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

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

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

Параметры

namestr

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

sourcesпоследовательность

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

build_infodict, необязательно

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

• 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

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

sourcesпоследовательность

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

install_dirstr

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

build_infodict, необязательно

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

• 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 с использованием шаблонов.