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

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

Модули в 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(self) [source]

Возвращает словарь, совместимый с именованными аргументами функции distutils setup.

Примеры

>>> setup(**config.todict())                           #doctest: +SKIP

get_distribution(self) [source]

Возвращает объект дистрибутива distutils для self.

get_subpackage(self, 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(self, 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(self, *files) [source]

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

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

Примечания

Форма каждого элемента последовательности файлов очень гибкая, позволяющая множество комбинаций того, где брать файлы из пакета и где они должны быть в конечном итоге установлены в системе. Наиболее распространенное использование - это когда элемент последовательности аргумента файлов является простым именем файла. Это приведет к тому, что этот файл из локального пути будет установлен в установочный путь пакета 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')                   #doctest: +SKIP

установит эти файлы данных в:

<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(self, data_path) [source]

Рекурсивно добавить файлы из data_path в список data_files.

Рекурсивно добавляет файлы из data_path в список файлов data_files, которые должны быть установлены (и распространяются). data_path может быть либо относительным именем пути, либо абсолютным именем пути, либо 2-кортежем, где первый аргумент показывает, куда в установочном каталоге должен быть установлен каталог данных.

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

Примечания

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

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')                       #doctest: +SKIP
>>> self.add_data_dir(('sun', 'fun'))              #doctest: +SKIP
>>> self.add_data_dir(('gun', '/full/path/to/fun'))#doctest: +SKIP

Установит файлы данных в следующие места:

<package install directory>/
  fun/
    foo.dat
    bar/
      car.dat
  sun/
    foo.dat
    bar/
      car.dat
  gun/
    foo.dat
    car.dat

add_include_dirs(self, *paths) [source]

Добавить пути к каталогам include конфигурации.

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

add_headers(self, *files) [source]

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

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

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

add_extension(self, 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(self, 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(self, *files) [source]

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

Добавляет последовательность файлов в начало списка скриптов. Скрипты будут установлены в каталог <prefix>/bin/.

add_installed_library(self, 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(self, 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(self, *paths, **kws) [source]

Применение glob к путям и добавление local_path при необходимости.

Применяет glob.glob(…) к каждому пути в последовательности (при необходимости) и добавляет local_path при необходимости. Поскольку это вызывается для всех списков исходных файлов, это позволяет указывать символы подстановки в списках исходных файлов для модулей расширения, библиотек и скриптов и позволяет использовать имена путей относительно каталога исходных файлов.

get_config_cmd(self) [source]

Возвращает экземпляр команды конфигурации numpy.distutils.

get_build_temp_dir(self) [source]

Возвращает путь к временному каталогу, где должны размещаться временные файлы.

have_f77c(self) [source]

Проверка наличия компилятора Fortran 77.

Используйте её внутри функции генерации исходного кода, чтобы убедиться, что экземпляр распределения setup был инициализирован.

Примечания

True, если компилятор Fortran 77 доступен (потому что простой код Fortran 77 был успешно скомпилирован).

have_f90c(self) [source]

Проверка наличия компилятора Fortran 90.

Используйте её внутри функции генерации исходного кода, чтобы убедиться, что экземпляр распределения setup был инициализирован.

Примечания

True, если компилятор Fortran 90 доступен (потому что простой код Fortran 90 был успешно скомпилирован).

get_version(self, 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(self, delete=True) [source]

Добавляет функцию данных в список data_files, которая сгенерирует файл __svn_version__.py в текущем каталоге пакета.

Генерирует файл пакета __svn_version__.py из номера SVN-ревизии. Он будет удалён после выхода интерпретатора Python, но будет доступен при выполнении команд sdist и т.д.

Примечания

Если __svn_version__.py существовал ранее, ничего не делается.

Это предназначено для работы с каталогами исходных кодов, находящимися в репозитории SVN.

make_config_py(self, name='__config__') [source]

Генерирует файл пакета __config__.py, содержащий информацию system_info, используемую при сборке пакета.

Этот файл устанавливается в каталог установки пакета.

get_info(self, *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). Второй тип используется для всех остальных случаев. См. Преобразование файлов .src с использованием шаблонов.