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

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

Модули в numpy.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_name : str или None Имя подпакета для получения конфигурации. ‘*’ в subpackage_name обрабатывается как подстановка. subpackage_path : str Если None, то предполагается, что путь совпадает с локальным путем плюс subpackage_name. Если файл setup.py не найден в subpackage_path, то используется конфигурация по умолчанию. parent_name : str Родительское имя.

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

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

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

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

add_data_files(*files) [source]

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

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

Примечания

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

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

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

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

Параметры:	data_path : последовательность или 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]

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

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

Параметры:	files : str или seq Аргумент(ы) могут быть либо: 2-последовательность (<суффикс каталога заголовков>,<путь к файлу заголовка>) путь(и) к файлам заголовка(ов), где суффикс каталога заголовков Python по умолчанию будет равен имени пакета.

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

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

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

Параметры:

name : str имя расширения sources : seq список исходных файлов. Список исходных файлов может содержать функции (называемые генераторами исходных файлов), которые должны принимать экземпляр расширения и директорию сборки в качестве входных данных и возвращать исходный файл или список исходных файлов, или 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_info : dict or list dict или список dict со словами, которые нужно добавить к ключевым словам.

Примечания

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

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

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

Параметры:

name : str Имя расширения. sources : sequence Список исходных файлов. Список исходных файлов может содержать функции (называемые генераторами исходных файлов), которые должны принимать экземпляр расширения и директорию сборки в качестве входных данных и возвращать исходный файл или список исходных файлов, или None. Если возвращается None, то исходные файлы не генерируются. Если у экземпляра Extension нет исходных файлов после обработки всех генераторов исходных файлов, то модуль расширения не будет скомпилирован. build_info : dict, optional Разрешены следующие ключи: depends macros include_dirs extra_compiler_args extra_f77_compiler_args extra_f90_compiler_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, но библиотеки, созданные с помощью этого метода, будут установлены, чтобы их можно было повторно использовать сторонними пакетами.

Параметры:

name : str Имя устанавливаемой библиотеки. sources : sequence Список исходных файлов библиотеки. Смотрите add_library для получения подробностей. install_dir : str Путь для установки библиотеки, относительно текущего подпакета. build_info : dict, optional Разрешены следующие ключи: depends macros include_dirs extra_compiler_args extra_f77_compiler_args extra_f90_compiler_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 для подстановки переменных.

Параметры:

template : str Путь к шаблону, относительно текущего пути пакета. install_dir : str Куда установить файл npy-pkg конфигурации, относительно текущего пути пакета. subst_dict : dict, 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’.

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

>>> 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). Второй тип используется для всех остальных случаев.

Файлы Fortran

Этот преобразователь шаблонов будет дублировать все блоки функции и подпрограммы в файле с именами, содержащими ‘<...>’, в соответствии с правилами в ‘<...>’. Количество слов, разделённых запятыми в ‘<...>’, определяет количество повторений блока. Эти слова указывают, чем следует заменить эту строку замены, ‘<...>’, в каждом блоке. Все правила повторения в блоке должны содержать одинаковое количество слов, разделённых запятыми, указывающих количество повторений блока. Если слову в правиле повторения нужна запятая, стрелка влево или вправо, то её следует предварять обратной косой чертой «\». Если слово в правиле повторения соответствует «\ <индекс>», то оно будет заменено на <индекс>-е слово в том же правиле повторения. Существуют два типа правил повторения: именованные и короткие.

Именованное правило повторения

Именованное правило повторения полезно, когда тот же набор повторений должен быть использован несколько раз в блоке. Оно задаётся с помощью <правило1=элемент1, элемент2, элемент3,..., элементN>, где N — количество повторений блока. При каждом повторении блока всё выражение ‘<...>’ будет заменено сначала на элемент1, затем на элемент2 и так далее, пока не будет выполнено N повторений. После введения именованного правила повторения то же правило повторения может быть использовано в текущем блоке, ссылаясь только на имя (т. е. <правило1>).

Короткое правило повторения

Короткое правило повторения выглядит так: <элемент1, элемент2, элемент3, ..., элементN>. Правило указывает, что всё выражение ‘<...>’ должно быть заменено сначала на элемент1, затем на элемент2 и так далее, пока не будет выполнено N повторений.

Предопределённые имена

Доступны следующие предопределённые именованные правила повторения:

• <префикс=s,d,c,z>
• <_c=s,d,c,z>
• <_t=вещественный, двойная точность, комплексный, комплексный двойной>
• <тип_f=вещественный, двойная точность, комплексный, комплексный двойной>
• <тип_с=float, double, complex_float, complex_double>
• <ftypereal=float, double precision, \0, \1>
• <ctypereal=float, double, \0, \1>

Другие файлы

Файлы, не являющиеся файлами Fortran, используют отдельный синтаксис для определения блоков шаблонов, которые должны быть повторены с использованием расширения переменных, аналогичного именованным правилам повторения для файлов Fortran. Правила шаблонов для этих файлов:

1. Строка «/**begin repeat*/» обозначает начало секции, которая должна быть повторена.
2. Именованные расширения переменных определяются с помощью #имя=элемент1, элемент2, элемент3, ..., элементN# и размещаются в последующих строках. Эти переменные заменяются в каждом повторённом блоке соответствующим словом. Все именованные переменные в одном блоке повторения должны определять одинаковое количество слов.
3. При указании правила повторения для именованной переменной, элемент*N — это сокращение для элемент, элемент, ..., элемент, повторяющегося N раз. Кроме того, круглые скобки в сочетании с *N могут использоваться для группировки нескольких элементов, которые должны быть повторены. Таким образом, #имя=(элемент1, элемент2)*4# эквивалентно #имя=элемент1, элемент2, элемент1, элемент2, элемент1, элемент2, элемент1, элемент2#.
4. Строка «*/» обозначает конец расширения именованных переменных. Следующая строка — это первая строка, которая будет повторена, используя именованные правила.
5. Внутри блока, который должен быть повторён, переменные, которые должны быть расширены, задаются как @имя@.
6. Строка «/**end repeat**/» обозначает предыдущую строку как последнюю строку блока, который должен быть повторён.