Пакетное создание (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]

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

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

Примечания

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

Это базовое поведение можно дополнить, передав пару из 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_path : seq или 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 конфигурации.

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

add_headers(*files) [source]

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

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

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

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

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

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

Параметры:

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

Примечания

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

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

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

Параметры:

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

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

Параметры:

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

Примечания

Истина, если компилятор 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

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

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

Правило повторения с именем полезно, когда один и тот же набор повторений должен использоваться несколько раз в блоке. Оно задаётся как <rule1=item1, item2, item3,…, itemN>, где N — число повторений блока. При каждом повторении блока всё выражение ‘<…>’ сначала заменяется на item1, затем на item2 и так далее, пока не будет выполнено N повторений. После введения правила повторения с именем, то же правило повторения может быть использовано в текущем блоке, ссылаясь только на имя (т.е. <rule1>.

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

Короткое правило повторения выглядит так: <item1, item2, item3, …, itemN>. Правило указывает, что всё выражение ‘<…>’ сначала должно быть заменено на item1, затем на item2 и так далее, пока не будет выполнено N повторений.

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

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

• <prefix=s,d,c,z>
• <_c=s,d,c,z>
• <_t=вещественное, двойной точности, комплексное, комплексное двойной точности>
• <ftype=вещественное, двойной точности, комплексное, комплексное двойной точности>
• <ctype=float, double, complex_float, complex_double>
• <ftypereal=float, двойной точности, \0, \1>
• <ctypereal=float, double, \0, \1>

Другие файлы

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

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