Упаковщик (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 элементов (<префикс каталога данных>,<путь к файлам данных>) пути к файлам данных, где префикс каталога данных по умолчанию равен каталогу пакета.

Примечания

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

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

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 был инициализирован.

Примечания

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

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

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

Именованное правило повторения полезно, когда один и тот же набор повторений должен использоваться несколько раз в блоке. Оно задаётся с помощью <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**/ “на отдельной строке отмечает предыдущую строку как последнюю строку блока, который должен быть повторён.