Упаковщик (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]

Добавляет файлы данных в данные configuration data_files.

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

Примечания

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

Это базовое поведение можно дополнить, передавая пару из 2-х элементов в качестве аргумента файла. Первый элемент кортежа должен указать относительный путь (внутри директории установки пакета), куда нужно установить оставшуюся последовательность файлов (это не имеет отношения к именам файлов в дистрибутиве исходного кода). Второй элемент кортежа — последовательность файлов, которые должны быть установлены. Файлы в этой последовательности могут быть именами файлов, относительными путями или абсолютными путями. Для абсолютных путей файл будет установлен в директорию установки пакета верхнего уровня (независимо от первого аргумента). Имена файлов и относительные пути будут установлены в директории установки пакета по указанному имени пути, являющемуся первым элементом кортежа.

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

1. file.txt -> (., file.txt)-> родитель/file.txt
2. foo/file.txt -> (foo, foo/file.txt) -> родитель/foo/file.txt
3. /foo/bar/file.txt -> (., /foo/bar/file.txt) -> родитель/file.txt
4. *.txt -> родитель/a.txt, родитель/b.txt
5. foo/*.txt -> родитель/foo/a.txt, родитель/foo/b.txt
6. /.txt -> (, */.txt) -> родитель/c/a.txt, родитель/d/b.txt
7. (sun, file.txt) -> родитель/sun/file.txt
8. (sun, bar/file.txt) -> родитель/sun/file.txt
9. (sun, /foo/bar/file.txt) -> родитель/sun/file.txt
10. (sun, *.txt) -> родитель/sun/a.txt, родитель/sun/b.txt
11. (sun, bar/*.txt) -> родитель/sun/a.txt, родитель/sun/b.txt
12. (sun/, */.txt) -> родитель/sun/c/a.txt, родитель/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) -> родитель/foo/bar (gun, foo/bar) -> родитель/gun foo/* -> (foo/a, foo/a), (foo/b, foo/b) -> родитель/foo/a, родитель/foo/b (gun, foo/) -> (gun, foo/a), (gun, foo/b) -> gun (gun/, foo/) -> родитель/gun/a, родитель/gun/b /foo/bar -> (bar, /foo/bar) -> родитель/bar (gun, /foo/bar) -> родитель/gun (fun//gun/*, sun/foo/bar) -> родитель/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]

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

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

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

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 или list dict или список словарей с ключевыми словами, которые нужно добавить к ключевым словам.

Примечания

Метод 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_compiler_args extra_f90_compiler_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_compiler_args extra_f90_compiler_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

Этот преобразователь шаблонов будет дублировать все блоки функций и подпрограмм в файле с именами, содержащими ‘<...>’, согласно правилам в ‘<...>’. Число запятыми разделённых слов в ‘<...>’ определяет количество повторений блока. Сами слова указывают, на что должно быть заменено данное правило повторения ‘<...>’ в каждом блоке. Все правила повторения в блоке должны содержать одинаковое количество запятыми разделённых слов, указывающих на количество повторений этого блока. Если слово в правиле повторения содержит запятую, стрелку влево или вправо, то его необходимо предварять обратной косой чертой «\». Если слово в правиле повторения совпадает со значением «\ <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. Строка «/**end repeat**/» обозначает конец определения расширения переменных. Следующая строка — это первая строка, которая будет повторяться с использованием именованных правил.
5. Внутри повторяющегося блока переменные, которые должны быть расширены, указываются как @name@.
6. Строка «/**end repeat**/» обозначает конец повторяющегося блока.