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

Модули в numpy.distutils

• distutils.misc_util
  • all_strings
  • allpath
  • appendpath
  • as_list
  • blue_text
  • cyan_text
  • cyg2win32
  • default_config_dict
  • dict_append
  • dot_join
  • exec_mod_from_location
  • filter_sources
  • generate_config_py
  • get_build_architecture
  • get_cmd
  • get_data_files
  • get_dependencies
  • get_ext_source_files
  • get_frame
  • get_info
  • get_language
  • get_lib_source_files
  • get_mathlibs
  • get_num_build_jobs
  • get_numpy_include_dirs
  • get_pkg_info
  • get_script_files
  • gpaths
  • green_text
  • has_cxx_sources
  • has_f_sources
  • is_local_src_dir
  • is_sequence
  • is_string
  • mingw32
  • minrelpath
  • njoin
  • red_text
  • sanitize_cxx_flags
  • terminal_has_colors
  • yellow_text

Класс конфигурации

класс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_namestr или None

Имя подпакета для получения конфигурации. ‘*’ в subpackage_name обрабатывается как символ подстановки.

subpackage_pathstr

Если None, то путь предполагается равным локальному пути плюс subpackage_name. Если файл setup.py не найден в subpackage_path, то используется конфигурация по умолчанию.

parent_namestr

Родительское имя.

add_subpackage(subpackage_name, subpackage_path=None, standalone=False)[source]

Добавляет подпакет в текущий экземпляр Configuration.

Это полезно в скрипте setup.py для добавления подпакетов к пакету.

Параметры:

subpackage_namestr

Имя подпакета

subpackage_pathstr

Если задано, путь к подпакету, например, подпакет находится в subpackage_path / subpackage_name. Если None, подпакет предполагается расположенным в локальном пути / subpackage_name.

standalonebool

add_data_files(*files)[source]

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

Параметры:

filesпоследовательность

Аргумент(ы) может быть:

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

Заметки

Формат каждого элемента последовательности 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последовательность или 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(‘.’,’/’)>/. Если элемент files является кортежем, то его первый аргумент указывает фактическое место установки относительно пути <python-include>.

Параметры:

filesстрока или последовательность

Аргумент(ы) могут быть:

• последовательность из 2 элементов (<приставка к пути include>,<путь к заголовочному файлу(ам)>)
• путь(и) к заголовочному файлу(ам), где приставка к пути include по умолчанию устанавливается равной имени пакета.

add_extension(name, sources, **kw)[source]

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

Создать и добавить экземпляр Extension в список ext_modules. Этот метод также принимает следующие необязательные ключевые аргументы, которые передаются конструктору Extension.

Параметры:

nameстрока

имя расширения

sourcesпоследовательность

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

словарь или список словарей с ключевыми словами, которые будут добавлены к ключевым словам.

Примечания

Метод self.paths(…) применяется ко всем спискам, которые могут содержать пути.

add_library(name, sources, **build_info)[source]

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

Параметры:

nameстрока

Имя расширения.

sourcesпоследовательность

Список исходных файлов. Список исходных файлов может содержать функции (называемые генераторами исходных файлов), которые должны принимать экземпляр расширения и каталог сборки в качестве входных данных и возвращать исходный файл или список исходных файлов или None. Если возвращается None, то исходные файлы не генерируются. Если у экземпляра Extension нет исходных файлов после обработки всех генераторов исходных файлов, то модуль расширения не создается.

build_infoсловарь, необязательно

Разрешены следующие ключи:

• 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строка

Имя устанавливаемой библиотеки.

sourcesпоследовательность

Список файлов исходного кода библиотеки. См. add_library для получения подробной информации.

install_dirстрока

Путь для установки библиотеки, относительно текущего подпакета.

build_infoсловарь, необязательно

Разрешены следующие ключи:

• 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 для подстановки переменных.

Параметры:

templatestr

Путь к шаблону, относительно текущего пути к пакету.

install_dirstr

Место установки файла конфигурации npy-pkg, относительно текущего пути к пакету.

subst_dictdict, необязательно

Если задано, любая строка вида @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».

При кросс-компиляции с помощью numpy distutils, возможно, потребуется использовать изменённые файлы npy-pkg-config. Использование стандартных/сгенерированных файлов приведет к линковке с библиотеками хоста (например, libnpymath.a). Для кросс-компиляции, конечно, необходимо слинковать с целевыми библиотеками, используя установку хост-Python.

Вы можете скопировать каталог numpy/_core/lib/npy-pkg-config, добавить значение pkgdir в файлы .ini и установить переменную среды NPY_PKG_CONFIG_PATH, чтобы она указывать на каталог с изменёнными файлами npy-pkg-config.

Пример npymath.ini, изменённый для кросс-компиляции:

[meta]
Name=npymath
Description=Portable, core math library implementing C99 standard
Version=0.1

[variables]
pkgname=numpy._core
pkgdir=/build/arm-linux-gnueabi/sysroot/usr/lib/python3.7/site-packages/numpy/_core
prefix=${pkgdir}
libdir=${prefix}/lib
includedir=${prefix}/include

[default]
Libs=-L${libdir} -lnpymath
Cflags=-I${includedir}
Requires=mlib

[msvc]
Libs=/LIBPATH:${libdir} npymath.lib
Cflags=/INCLUDE:${includedir}
Requires=mlib

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.

.. hidden in a comment so as to be included in refguide but not rendered documentation
  >>> import numpy.distutils.misc_util
  >>> config = np.distutils.misc_util.Configuration(None, '', '.')
  >>> with open('foo.c', 'w') as f: pass

>>> config.add_installed_library('foo', sources=['foo.c'], install_dir='lib')

[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

[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

>>> 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)

>>> info = np.distutils.misc_util.get_info('npymath')
>>> config.add_extension('foo', sources=['foo.c'], extra_info=info)
<numpy.distutils.extension.Extension('foo') at 0x...>

Преобразование файлов .src

NumPy distutils поддерживает автоматическое преобразование исходных файлов с именем <somefile>.src. Это средство можно использовать для поддержания очень похожих блоков кода, требующих только небольших изменений между блоками. Во время фазы сборки setup, если встречается шаблонный файл с именем <somefile>.src, новый файл с именем <somefile> создаётся из шаблона и помещается в каталог сборки для использования вместо него. Поддерживаются два вида преобразования шаблонов. Первый вид происходит для файлов с именем <file>.ext.src, где ext — это распознаваемое расширение Fortran (f, f90, f95, f77, for, ftn, pyf). Второй вид используется для всех остальных случаев. См. Преобразование файлов .src с помощью шаблонов.