Пакетное создание (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 or 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 : sequence Аргумент(ы) могут быть либо 2-последовательность (<префикс каталога данных>,<путь к файлу данных>) пути к файлам данных, где префикс каталога данных Python по умолчанию устанавливается в каталог пакета.

Примечания

Формат каждого элемента последовательности файлов очень гибкий, позволяя множество комбинаций того, откуда получать файлы из дистрибутива пакета и куда их в конечном итоге установить в системе. Самое простое использование состоит в том, чтобы элемент последовательности аргументов файлов был простым именем файла. Это приведет к установке этого файла из локального пути в каталог установки пакета 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 : seq or 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 or 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 словарь или список словарей с ключевыми словами, которые нужно добавить к ключевым словам.

Примечания

Метод 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 config из шаблона.

Файл конфигурации, сгенерированный из template, устанавливается в указанную директорию установки, используя subst_dict для подстановки переменных.

Параметры:

template : str путь к шаблону, относительно пути к текущему пакету. install_dir : str место установки файла npy-pkg config, относительно пути к текущему пакету. 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 был инициализирован.

Примечания

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

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

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

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