Упаковщик (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_path : str Если None, то путь предполагается равным локальному пути плюс имя подпакета. Если файл setup.py не найден в подпакете, то используется конфигурация по умолчанию. 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 (путь пакета). Аргумент файла также может быть относительным путем, в котором случае весь относительный путь будет установлен в директорию пакета. Наконец, файл может быть абсолютным именем пути, в котором случае файл будет найден по абсолютному пути, но установлен в путь пакета.

Это базовое поведение можно дополнить передачей кортежа из 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 : последовательность или строка Аргумент может быть 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(‘.’,’/’)>/ . Если элемент files является кортежем, то его первый аргумент задаёт фактическое расположение установки относительно пути <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_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 : sequence Список исходных файлов библиотеки. См. add_library для получения дополнительной информации. install_dir : str Путь для установки библиотеки, относительно текущего подпакета. build_info : dict, 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 для подстановки переменных.

Параметры:

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

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

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

Именованное правило повторения полезно, когда один и тот же набор повторений должен использоваться несколько раз в блоке. Оно задаётся с помощью <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=real, double precision, complex, double complex>
• <ftype=real, double precision, complex, double complex>
• <ctype=float, double, complex_float, complex_double>
• <ftypereal=float, double precision, \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**/ “на отдельной строке обозначает предыдущую строку как последнюю строку блока, подлежащего повторению.