9. Ссылка на API¶

9.1. distutils.core — Основные функциональные возможности дистрибутива¶

Модуль distutils.core - это единственный модуль, который необходимо установить для использования дистрибутива. Он предоставляет setup() (который вызывается из сценария установки). Косвенно предоставляет классы distutils.dist.Distribution и distutils.cmd.Command.

distutils.core.setup(arguments)¶

Базовая функция do-everything, которая выполняет практически все, что вы когда-либо могли запросить от метода Distutils.

Функция настройки принимает большое количество аргументов. Они представлены в следующей таблице.

имя аргумента	ценность	тип
имя	Название пакета	строка
версия	Номер версии пакета; смотрите distutils.version	строка
описание	Одна строка, описывающая пакет	строка
длинное описание	Более подробное описание упаковки	строка
автор	Имя автора пакета	строка
электронная почта автора	Адрес электронной почты автора пакета	строка
сопровождающий	Имя текущего сопровождающего, если оно отличается от имени автора. Обратите внимание, что если указан сопровождающий, distutils будет использовать его в качестве автора в PKG-INFO	строка
электронная почта сопровождающего	Адрес электронной почты текущего сопровождающего, если он отличается от адреса автора	строка
url-адрес	URL-адрес пакета (домашняя страница)	строка
загрузка_url	URL-адрес для загрузки пакета	строка
пакеты	Список пакетов Python, которыми будет управлять distutils	список строк
py_modules (модульные модули)	Список модулей Python, которыми будет управлять distutils	список строк
сценарии	Список автономных файлов скриптов, которые должны быть созданы и установлены	список строк
ext_modules (дополнительные модули)	Список расширений Python, которые будут созданы	список экземпляров distutils.core.Extension
классификаторы	Список категорий для пакета	список строк; допустимые классификаторы указаны в PyPI.
распределенный класс	используемый класс Distribution	подкласс distutils.core.Distribution
имя скрипта	Имя скрипта setup.py по умолчанию равно sys.argv[0]	строка
скрипт_арги	Аргументы, которые необходимо указать в сценарии установки	список строк
варианты	параметры по умолчанию для сценария установки	словарь
лицензия	Лицензия на пакет	строка
ключевые слова	Описательные метаданные, см. PEP 314	список строк или строка, разделенная запятыми
платформы		список строк или строка, разделенная запятыми
командный класс	Сопоставление имен команд с подклассами Command	словарь
файлы данных	Список файлов данных для установки	список
каталог упаковок	Сопоставление пакетов с именами каталогов	словарь

distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])¶

Запустите установочный скрипт в некоторой степени контролируемой среде и верните экземпляр distutils.dist.Distribution, который управляет всеми процессами. Это полезно, если вам нужно найти метаданные распространения (передаваемые в виде аргументов ключевых слов из script в setup()) или содержимое конфигурационных файлов или командной строки.

имя_скрипта - это файл, который будет прочитан и запущен с помощью exec(). sys.argv[0] будет заменен на script на время выполнения вызова. script_args - это список строк; если он указан, sys.argv[1:] будет заменен на script_args на время вызова.

stop_after указывает setup(), когда следует прекратить обработку; возможные значения:

ценность	описание
инициализация	Остановитесь после того, как экземпляр Distribution будет создан и заполнен ключевыми аргументами setup()
конфигурация	Остановитесь после того, как конфигурационные файлы будут проанализированы (и их данные будут сохранены в экземпляре Distribution).
командная строка	Остановитесь после того, как командная строка (sys.argv[1:] или script_args) будут проанализированы (и данные, сохраненные в экземпляре Distribution).
запуск	Остановка после выполнения всех команд (аналогично тому, как если бы setup() был вызван обычным способом). Это значение по умолчанию.

Кроме того, модуль distutils.core предоставил доступ к ряду классов, которые находятся в другом месте.

• Extension из distutils.extension

• Command из distutils.cmd

• Distribution из distutils.dist

Ниже приводится краткое описание каждого из них, но полную информацию смотрите в соответствующем модуле.

class distutils.core.Extension¶

Класс Extension описывает отдельный модуль расширения C или C++ в сценарии установки. В своем конструкторе он принимает следующие аргументы ключевого слова:

имя аргумента	ценность	тип
имя	полное имя расширения, включая все пакеты, — т.е.. не имя файла или путь к нему, а имя с точкой в Python	строка
источники	список имен исходных файлов, относящихся к корневому каталогу дистрибутива (где находится установочный скрипт), в форме Unix (через косую черту) для удобства переноса. Исходными файлами могут быть C, C++, SWIG (.i), файлы ресурсов для конкретной платформы или любые другие файлы, которые распознаются командой build_ext как исходные для расширения Python.	список строк
include_dirs (включать в себя )	список каталогов для поиска заголовочных файлов C/C++ (в формате Unix для удобства переноса)	список строк
определить_макросы	список макросов для определения; каждый макрос определяется с использованием 2-х кортежей (name, value), где value - это либо строка для его определения, либо None для его определения без определенного значения (эквивалент #define FOO в исходном коде или -DFOO в командной строке компилятора Unix C)	список кортежей
макросы undef_macros	список макросов, которые нужно явно отменить	список строк
библиотечные каталоги	список каталогов для поиска библиотек C/C++ во время ссылки	список строк
библиотеки	список имен библиотек (не имен файлов и не путей к ним) для привязки к	список строк
runtime_library_dirs время выполнения	список каталогов для поиска библиотек C/C++ во время выполнения (для общих расширений это происходит при загрузке расширения)	список строк
дополнительные объекты	список дополнительных файлов для связи (например, объектные файлы, не подразумеваемые в «источниках», статическая библиотека, которая должна быть явно указана, двоичные файлы ресурсов и т.д.)	список строк
дополнительные параметры компиляции	любая дополнительная информация, относящаяся к конкретной платформе и компилятору, для использования при компиляции исходных файлов в разделе «исходные тексты». Для платформ и компиляторов, где имеет смысл использовать командную строку, обычно это список аргументов командной строки, но для других платформ это может быть что угодно.	список строк
дополнительные ссылки	любая дополнительная информация, относящаяся к конкретной платформе и компилятору, для использования при объединении объектных файлов для создания расширения (или для создания нового статического интерпретатора Python). Аналогичная интерпретация для „extra_compile_args“.	список строк
экспорт_символов	список символов, которые должны быть экспортированы из общего расширения. Используется не на всех платформах и, как правило, не требуется для расширений Python, которые обычно экспортируют только один символ: init + имя_расширения.	список строк
зависит от	список файлов, от которых зависит расширение	список строк
язык	язык расширения (т.е. 'c', 'c++', 'objc'). Будет определен из исходных расширений, если не указан.	строка
опционально	указывает, что ошибка сборки в расширении не должна прерывать процесс сборки, а просто пропускать расширение.	логическое значение

Изменено в версии 3.8: В Unix расширения C больше не связаны с libpython, за исключением Android и Cygwin.

class distutils.core.Distribution¶

В Distribution описано, как создать, установить и упаковать программный пакет Python.

Список аргументов ключевых слов, принимаемых конструктором дистрибутива, приведен в функции setup(). setup() создает экземпляр дистрибутива.

Изменено в версии 3.7: Distribution теперь предупреждает, если поля classifiers, keywords и platforms не указаны в виде списка или строки.

class distutils.core.Command¶

Класс Command (или, скорее, экземпляр одного из его подклассов) реализует одну команду distutils.

9.2. distutils.ccompiler — Базовый класс компилятора C¶

Этот модуль предоставляет абстрактный базовый класс для классов CCompiler. Экземпляр CCompiler можно использовать для всех этапов компиляции и компоновки, необходимых для создания одного проекта. Предоставляются методы для настройки параметров компилятора - определения макросов, включая каталоги, пути ссылок, библиотеки и тому подобное.

Этот модуль предоставляет следующие функции.

distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)¶

Создайте параметры компоновщика для поиска в библиотечных каталогах и привязки к конкретным библиотекам. libraries и library_dirs - это, соответственно, списки имен библиотек (не имен файлов!) и каталогов поиска. Возвращает список параметров командной строки, подходящих для использования с каким-либо компилятором (в зависимости от двух переданных строк формата).

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)¶

Сгенерируйте параметры препроцессора C (-D, -U, -I) которые используются, по крайней мере, двумя типами компиляторов: типичным Unix-компилятором и Visual C++. макросы - это обычная вещь, список из 1 или 2 кортежей, где (name,) означает неопределить (-U) имя макроса*, а (name, value) означает определить (-D) преобразуйте имя макроса в значение. include_dirs - это просто список имен каталогов, которые должны быть добавлены в путь поиска заголовочного файла (-I). Возвращает список параметров командной строки, подходящих как для компиляторов Unix, так и для Visual C++.

distutils.ccompiler.get_default_compiler(osname, platform)¶

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

osname должно быть одним из стандартных имен ОС Python (т.е. тех, которые возвращаются с помощью os.name), а platform - общим значением, возвращаемым с помощью sys.platform для рассматриваемой платформы.

Значениями по умолчанию являются os.name и sys.platform в случае, если параметры не заданы.

distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)¶

Фабричная функция для создания экземпляра некоторого подкласса компилятора C для поставляемой комбинации платформа/компилятор. plat по умолчанию имеет значение os.name (например,. 'posix', 'nt'), а compiler по умолчанию - компилятор по умолчанию для этой платформы. В настоящее время поддерживаются только 'posix' и 'nt', а компиляторами по умолчанию являются «традиционный интерфейс Unix» (класс UnixCCompiler) и Visual C++ (класс MSVCCompiler). Обратите внимание, что вполне возможно запросить объект компилятора Unix в Windows и объект компилятора Microsoft в Unix- если вы укажете значение для compiler, plat будет проигнорирован.

distutils.ccompiler.show_compilers()¶

Распечатать список доступных компиляторов (используемых параметрами --help-compiler для build, build_ext, build_clib).

class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])¶

Абстрактный базовый класс CCompiler определяет интерфейс, который должен быть реализован реальными классами компилятора. Класс также содержит некоторые служебные методы, используемые несколькими классами компилятора.

Основная идея, лежащая в основе класса абстракции компилятора, заключается в том, что каждый экземпляр может использоваться для всех этапов компиляции/компоновки при создании одного проекта. Таким образом, атрибуты, общие для всех этих этапов компиляции и компоновки, включая каталоги, определяемые макросы, библиотеки для создания ссылок и т.д., являются атрибутами экземпляра компилятора. Чтобы обеспечить вариативность в обработке отдельных файлов, большинство этих атрибутов могут варьироваться в зависимости от компиляции или ссылки.

Конструктор для каждого подкласса создает экземпляр объекта компилятора. Флагами являются verbose (показывать подробный вывод), dry_run (фактически не выполнять шаги) и force (перестраивать все, независимо от зависимостей). Все эти флаги по умолчанию имеют значение 0 (выключено). Обратите внимание, что вы, вероятно, не захотите создавать экземпляр CCompiler или один из его подклассов напрямую - вместо этого используйте заводскую функцию distutils.CCompiler.new_compiler().

Следующие методы позволяют вам вручную изменять параметры компилятора для экземпляра класса Compiler.

add_include_dir(dir)¶

Добавьте dir в список каталогов, в которых будет производиться поиск заголовочных файлов. Компилятору предлагается выполнять поиск в каталогах в том порядке, в котором они указаны при последовательных вызовах add_include_dir().

set_include_dirs(dirs)¶

Задайте для списка каталогов, в которых будет производиться поиск, значение dirs (список строк). Переопределяет все предыдущие вызовы add_include_dir(); последующие вызовы add_include_dir() добавляются к списку, переданному в set_include_dirs(). Это не влияет ни на один список стандартных каталогов include, в которых компилятор может выполнять поиск по умолчанию.

add_library(libname)¶

Добавьте libname в список библиотек, которые будут включены во все ссылки, управляемые этим объектом компилятора. Обратите внимание, что libname должно быть не именем файла, содержащего библиотеку, а именем самой библиотеки: фактическое имя файла будет определено компоновщиком, компилятором или классом компилятора (в зависимости от платформы).

Компоновщику будет предложено выполнить привязку к библиотекам в том порядке, в котором они были предоставлены в add_library() и/или set_libraries(). Дублирование имен библиотек вполне допустимо; компоновщику будет дано указание создавать ссылки на библиотеки столько раз, сколько они упоминаются.

set_libraries(libnames)¶

Задайте для списка библиотек, которые будут включены во все ссылки, управляемые этим объектом компилятора, значение libnames (список строк). Это не влияет на стандартные системные библиотеки, которые компоновщик может включать по умолчанию.

add_library_dir(dir)¶

Добавьте dir в список каталогов, в которых будет производиться поиск библиотек, указанных в add_library() и set_libraries(). Компоновщику будет предложено выполнить поиск библиотек в том порядке, в котором они указаны в add_library_dir() и/или set_library_dirs().

set_library_dirs(dirs)¶

Установите для списка каталогов поиска в библиотеке значение dirs (список строк). Это не влияет на стандартный путь поиска в библиотеке, который компоновщик может выполнять по умолчанию.

add_runtime_library_dir(dir)¶

Добавьте dir в список каталогов, в которых будет выполняться поиск общих библиотек во время выполнения.

set_runtime_library_dirs(dirs)¶

Задайте для списка каталогов для поиска разделяемых библиотек во время выполнения значение dirs (список строк). Это не влияет на стандартный путь поиска, который компоновщик среды выполнения может выполнять по умолчанию.

define_macro(name[, value=None])¶

Определите макрос препроцессора для всех компиляций, выполняемых этим объектом компилятора. Необязательный параметр value должен быть строкой; если он не указан, то макрос будет определен без явного значения, и точный результат зависит от используемого компилятора.

undefine_macro(name)¶

Отмените определение макроса препроцессора для всех компиляций, выполняемых этим объектом компилятора. Если один и тот же макрос определен с помощью define_macro() и не определен с помощью undefine_macro(), последний вызов имеет приоритет (включая несколько переопределений или неопределений). Если макрос переопределяется/не определяется для каждой компиляции (т.е. при вызове compile()), то это имеет приоритет.

add_link_object(object)¶

Добавьте object в список объектных файлов (или аналогов, таких как явно именованные библиотечные файлы или выходные данные «компиляторов ресурсов»), которые будут включены в каждую ссылку, управляемую этим объектом компилятора.

set_link_objects(objects)¶

Установите список объектных файлов (или аналогов), которые должны включаться в каждую ссылку на objects. Это не влияет на стандартные объектные файлы, которые компоновщик может включать по умолчанию (например, системные библиотеки).

Следующие методы реализуют методы автоматического определения параметров компилятора, предоставляя некоторую функциональность, аналогичную GNU autoconf.

detect_language(sources)¶

Определяет язык данного файла или списка файлов. Для выполнения задания используются атрибуты экземпляра language_map (словарь) и language_order (список).

find_library_file(dirs, lib[, debug=0])¶

Найдите в указанном списке каталогов статический файл или файл общей библиотеки lib и верните полный путь к этому файлу. Если значение debug равно true, найдите версию для отладки (если это имеет смысл для текущей платформы). Верните None, если lib не был найден ни в одном из указанных каталогов.

has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])¶

Возвращает логическое значение, указывающее, поддерживается ли funcname на текущей платформе. Необязательные аргументы могут быть использованы для расширения среды компиляции путем предоставления дополнительных включаемых файлов и путей, а также библиотек и путей к ним.

library_dir_option(dir)¶

Верните параметр компилятора, чтобы добавить dir в список каталогов, в которых выполняется поиск библиотек.

library_option(lib)¶

Верните параметр компилятора, чтобы добавить lib в список библиотек, связанных с общей библиотекой или исполняемым файлом.

runtime_library_dir_option(dir)¶

Верните параметр компилятора, чтобы добавить dir в список каталогов, в которых выполняется поиск библиотек времени выполнения.

set_executables(**args)¶

Определите исполняемые файлы (и параметры для них), которые будут запускаться для выполнения различных этапов компиляции. Точный набор исполняемых файлов, который может быть указан здесь, зависит от класса компилятора (через атрибут класса „executables“), но большинство из них будут иметь:

атрибут	описание
компилятор	компилятор C/C++
компоновщик_со	компоновщик, используемый для создания общих объектов и библиотек
компоновщик_exe	компоновщик, используемый для создания двоичных исполняемых файлов
архиватор	создатель статической библиотеки

На платформах с командной строкой (Unix, DOS/Windows) каждая из них представляет собой строку, которая будет разделена на имя исполняемого файла и (необязательный) список аргументов. (Разделение строки выполняется аналогично тому, как работают оболочки Unix: слова разделяются пробелами, но кавычки и обратная косая черта могут заменить это. Смотрите distutils.util.split_quoted().)

Следующие методы вызывают этапы процесса сборки.

compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])¶

Скомпилируйте один или несколько исходных файлов. Генерирует объектные файлы (например, преобразует файл .c в файл .o).

sources должен быть списком имен файлов, скорее всего, файлов на C/C++, но на самом деле все, что может быть обработано определенным компилятором и классом компилятора (например, MSVCCompiler может обрабатывать файлы ресурсов в sources). Возвращает список имен файлов объектов, по одному для каждого исходного файла в sources. В зависимости от реализации, не все исходные файлы обязательно будут скомпилированы, но будут возвращены все соответствующие имена файлов объектов.

Если задан параметр output_dir, объектные файлы будут помещены под ним, сохраняя при этом свой исходный путь к компоненту. То есть, foo/bar.c обычно компилируется в foo/bar.o (для реализации Unix); если output_dir равен build, то он будет компилироваться в build/foo/bar.o.

макросы, если они заданы, должны быть списком макроопределений. Макроопределение - это либо (name, value) 2-кортеж, либо (name,) 1-кортеж. Первый определяет макрос; если значение равно None, макрос определяется без явного значения. Случай с 1 кортежем отменяет определение макроса. Более поздние определения/переопределения/неопределяемости имеют приоритет.

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

debug - логическое значение; если оно равно true, компилятору будет предложено вывести символы отладки в объектных файлах(ах) (или рядом с ними).

extra_preargs и extra_postargs зависят от реализации. На платформах, где есть понятие командной строки (например, Unix, DOS/Windows), это, скорее всего, списки строк: дополнительные аргументы командной строки для добавления в командную строку компилятора. На других платформах обратитесь к документации по классу реализации. В любом случае, они предназначены в качестве запасного выхода для тех случаев, когда абстрактный фреймворк компилятора не подходит.

depends, если указано, - это список имен файлов, от которых зависят все целевые объекты. Если исходный файл старше любого файла в depends, то исходный файл будет перекомпилирован. Это поддерживает отслеживание зависимостей, но только с высокой степенью детализации.

Выдает CompileError при сбое.

create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])¶

Свяжите кучу материалов вместе, чтобы создать статический библиотечный файл. «Набор материалов» состоит из списка объектных файлов, предоставляемых в виде objects, дополнительных объектных файлов, предоставляемых в add_link_object() и/или set_link_objects(), библиотек, предоставляемых в add_library() и/или set_libraries(), а также библиотеки, поставляемые как библиотеки (если таковые имеются).

output_libname должно быть именем библиотеки, а не именем файла; имя файла будет выводиться из имени библиотеки. output_dir - это каталог, в который будет помещен файл библиотеки.

debug - логическое значение; если true, то отладочная информация будет включена в библиотеку (обратите внимание, что на большинстве платформ это имеет значение на этапе компиляции: флаг debug включен здесь только для обеспечения согласованности).

target_lang - это целевой язык, для которого компилируются данные объекты. Это позволяет использовать определенное время привязки для определенных языков.

Выдает LibError при сбое.

link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])¶

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

«Куча всего» состоит из списка объектных файлов, представленных как objects. output_filename должно быть именем файла. Если указан output_dir, то output_filename относится к нему (т.е. output_filename может предоставить компоненты каталога, если это необходимо).

библиотеки - это список библиотек, на которые можно установить ссылки. Это имена библиотек, а не имена файлов, поскольку они преобразуются в имена файлов в зависимости от платформы (например, foo становится libfoo.a в Unix и foo.lib в DOS/Windows). Однако они могут включать компонент каталога, что означает, что компоновщик будет искать в этом конкретном каталоге, а не во всех обычных местах.

library_dirs, если указан, должен быть списком каталогов для поиска библиотек, которые были указаны как простые имена библиотек (т.е. без компонента каталога). Они дополняют системные значения по умолчанию и те, которые указаны в add_library_dir() и/или set_library_dirs(). runtime_library_dirs - это список каталогов, которые будут встроены в общую библиотеку и использоваться для поиска других разделяемых библиотек, от которых это зависит во время выполнения. (Это может быть актуально только в Unix.)

export_symbols - это список символов, которые будет экспортировать общая библиотека. (Похоже, это актуально только для Windows).

debug используется как для compile(), так и для create_static_lib(), с небольшим отличием, что это действительно имеет значение на большинстве платформ (в отличие от create_static_lib(), который включает флаг debug в основном для формы).

extra_preargs и extra_postargs соответствуют compile() (за исключением, конечно, того, что они предоставляют аргументы командной строки для конкретного используемого компоновщика).

target_lang - это целевой язык, для которого компилируются данные объекты. Это позволяет использовать определенное время привязки для определенных языков.

Выдает LinkError при сбое.

link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])¶

Связать исполняемый файл. output_progname - это имя исполняемого файла, в то время как objects - это список имен файлов объектов, которые нужно связать. Остальные аргументы относятся к методу link().

link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])¶

Свяжите общую библиотеку. output_libname - это имя выходной библиотеки, в то время как objects - это список имен файлов объектов, которые нужно связать. Другие аргументы относятся к методу link().

link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])¶

Свяжите общий объект. output_filename - это имя общего объекта, который будет создан, в то время как objects - это список имен файлов объектов, которые нужно связать. Другие аргументы относятся к методу link().

preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])¶

Предварительно обработайте один исходный файл C/C++ с именем source. Выходные данные будут записаны в файл с именем output_file или stdout, если output_file не указан. макросы - это список определений макросов для compile(), которые дополнят набор макросов define_macro() и undefine_macro(). include_dirs - это список имен каталогов, которые будут добавлены в список по умолчанию таким же образом, как и add_include_dir().

Выдает PreprocessError при сбое.

Следующие служебные методы определены классом CCompiler для использования различными конкретными подклассами.

executable_filename(basename[, strip_dir=0, output_dir=''])¶

Возвращает имя исполняемого файла для заданного базового имени. Обычно для платформ, отличных от Windows, это то же самое, что и базовое имя, в то время как для Windows будет добавлено .exe.

library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])¶

Возвращает имя файла для заданного имени библиотеки на текущей платформе. В Unix библиотека с lib_type из 'static' обычно будет иметь вид liblibname.a, в то время как lib_type из 'dynamic' будет иметь вид liblibname.so.

object_filenames(source_filenames[, strip_dir=0, output_dir=''])¶

Возвращает имена объектных файлов для заданных исходных файлов. source_filenames должно быть списком имен файлов.

shared_object_filename(basename[, strip_dir=0, output_dir=''])¶

Возвращает имя общего объектного файла для заданного имени файла basename.

execute(func, args[, msg=None, level=1])¶

Вызывает distutils.util.execute(). Этот метод вызывает функцию Python func с заданными аргументами args, после регистрации и с учетом флага dry_run.

spawn(cmd)¶

Вызывает distutils.util.spawn(). При этом запускается внешний процесс для выполнения заданной команды.

mkpath(name[, mode=511])¶

Вызывает distutils.dir_util.mkpath(). При этом создается каталог и все отсутствующие каталоги-предки.

move_file(src, dst)¶

Вызывает distutils.file_util.move_file(). Переименовывает src в летнее время.

announce(msg[, level=1])¶

Напишите сообщение, используя distutils.log.debug().

warn(msg)¶

Напишите предупреждающее сообщение msg о стандартной ошибке.

debug_print(msg)¶

Если для этого экземпляра CCompiler установлен флаг debug, выведите msg в стандартный вывод, в противном случае ничего не делайте.

9.3. distutils.unixccompiler — Компилятор Unix C¶

Этот модуль предоставляет класс UnixCCompiler, являющийся подклассом CCompiler, который обрабатывает типичный компилятор командной строки C в стиле Unix:

• макросы, определенные с помощью -Dname[=value]

• макросы, не определенные с помощью -Uname

• включить поисковые каталоги, указанные с помощью -Idir

• библиотеки, указанные с помощью -llib

• поиск по каталогам библиотеки, указанным с помощью -Ldir

• компиляция выполняется с помощью cc (или аналогичного) исполняемого файла с параметром -c: компилирует .c в .o

• связать статическую библиотеку, обрабатываемую командой ar (возможно, с помощью ranlib)

• общая библиотека ссылок, обрабатываемая cc -shared

9.4. distutils.msvccompiler — Компилятор Microsoft¶

Этот модуль предоставляет MSVCCompiler, реализацию абстрактного класса CCompiler для Microsoft Visual Studio. Как правило, модули расширения необходимо компилировать с помощью того же компилятора, который использовался для компиляции Python. Для Python 2.3 и более ранних версий компилятором была Visual Studio 6. Для Python 2.4 и 2.5 компилятором является Visual Studio .NET 2003.

MSVCCompiler обычно выбирает правильный компилятор, компоновщик и т.д. самостоятельно. Чтобы переопределить этот выбор, должны быть установлены переменные окружения DISTUTILS_USE_SDK и MSSdk. MSSdk указывает, что текущая среда была настроена с помощью скрипта SDK SetEnv.Cmd или что переменные среды были зарегистрированы при установке SDK; DISTUTILS_USE_SDK указывает, что пользователь distutils явно решил переопределить выбор компилятора с помощью MSVCCompiler.

9.5. distutils.bcppcompiler — Компилятор Borland¶

Этот модуль предоставляет BorlandCCompiler, подкласс абстрактного класса CCompiler для компилятора Borland C++.

9.6. distutils.cygwincompiler — Компилятор Cygwin¶

Этот модуль предоставляет класс CygwinCCompiler, являющийся подклассом UnixCCompiler, который обрабатывает порт Cygwin компилятора GNU C для Windows. Он также содержит класс Mingw32CCompiler, который обрабатывает порт mingw32 GCC (такой же, как cygwin в режиме без cygwin).

9.7. distutils.archive_util — Утилиты архивирования¶

Этот модуль предоставляет несколько функций для создания архивных файлов, таких как архивные папки или zip-файлы.

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])¶

Создайте архивный файл (например, zip или tar). имя_основы - это имя создаваемого файла без расширения, зависящего от формата; формат - это формат архива: один из zip, tar, gztar, bztar, xztar или ztar. root_dir - это каталог, который будет корневым каталогом архива; т.е. обычно мы вводим chdir в root_dir перед созданием архива. base_dir - это каталог, из которого мы начинаем архивацию; т.е. base_dir будет общим префиксом для всех файлов и каталогов в архиве. В root_dir и base_dir по умолчанию используется текущий каталог. Возвращает имя архивного файла.

Изменено в версии 3.5: Добавлена поддержка формата xztar.

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])¶

„Создайте (необязательно сжатый) архив в виде файла tar из всех файлов в base_dir и под ним. сжатие должно быть 'gzip' (значение по умолчанию), 'bzip2', 'xz', 'compress', или None. Для метода 'compress' утилита сжатия с именем compress должна находиться в пути поиска программы по умолчанию, так что это, вероятно, специфично для Unix. Выходной tar-файл будет называться base_dir.tar, возможно, с соответствующим расширением для сжатия (.gz, .bz2, .xz или .Z). Верните имя выходного файла.

Изменено в версии 3.5: Добавлена поддержка сжатия xz.

distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])¶

Создайте zip-файл из всех файлов в base_dir и под ним. Выходной zip-файл будет называться base_name + .zip. Использует либо модуль zipfile Python (если доступен), либо утилиту Info ZIP zip (если она установлена и найдена по пути поиска по умолчанию). Если ни один из инструментов не доступен, вызывает DistutilsExecError. Возвращает имя выходного zip-файла.

9.8. distutils.dep_util — Проверка зависимостей¶

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

distutils.dep_util.newer(source, target)¶

Возвращает true, если source существует и был изменен позже, чем target, или если source существует, а target нет. Возвращает false, если оба существуют и target имеет тот же возраст или новее, чем source. Поднимите DistutilsFileError, если источник не существует.

distutils.dep_util.newer_pairwise(sources, targets)¶

Параллельно просмотрите два списка имен файлов, проверяя, является ли каждый источник более новым, чем соответствующий целевой файл. Верните пару списков (sources, targets), где source новее, чем target, в соответствии с семантикой newer().

distutils.dep_util.newer_group(sources, target[, missing='error'])¶

Возвращает значение true, если target устарел по отношению к любому файлу, указанному в sources. Другими словами, если target существует и является более новым, чем все файлы в sources, возвращает значение false; в противном случае возвращает значение true. отсутствует управляет тем, что мы делаем, когда отсутствует исходный файл; по умолчанию ('error') добавляется OSError изнутри os.stat(); если это 'ignore', мы автоматически удалите все отсутствующие исходные файлы; если это 'newer', то любые отсутствующие исходные файлы заставляют нас предположить, что target устарел (это удобно в режиме «пробного запуска»: это заставит вас притвориться, что вы выполняете команды, которые не будут работать из-за отсутствия входных данных, но это это не имеет значения, потому что на самом деле вы не собираетесь выполнять команды).

9.9. distutils.dir_util — Операции с деревом каталогов¶

Этот модуль предоставляет функции для работы с каталогами и деревьями каталогов.

distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])¶

Создайте каталог и все отсутствующие каталоги-предки. Если каталог уже существует (или если name - это пустая строка, которая означает текущий каталог, который, конечно же, существует), то ничего не делайте. Поднимите DistutilsFileError, если не удается создать какой-либо каталог на этом пути (например, какой-то подпутешествие существует, но это файл, а не каталог). Если значение verbose равно true, выведите в стандартный вывод однострочную сводку по каждому mkdir. Возвращает список фактически созданных каталогов.

distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])¶

Создайте все пустые каталоги под base_dir, необходимые для размещения файлов там. base_dir - это просто имя каталога, который еще не обязательно существует; files - это список имен файлов, которые следует интерпретировать относительно base_dir. base_dir + часть каталога каждого файла в files будет создана, если он еще не существует. флаги mode, verbose и dry_run соответствуют mkpath().

distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])¶

Скопируйте все дерево каталогов src в новое местоположение dst. Как src, так и dst должны быть именами каталогов. Если src не является каталогом, введите DistutilsFileError. Если dst не существует, он создается с помощью mkpath(). Конечным результатом копирования является то, что каждый файл в src копируется в dst, а каталоги в src рекурсивно копируются в dst. Возвращает список файлов, которые были скопированы или могли быть скопированы, используя их выходные имена. На возвращаемое значение не влияют update или dry_run: это просто список всех файлов под src, имена которых изменены на dst.

preserve_mode и preserve_times те же, что и для distutils.file_util.copy_file(); обратите внимание, что они применяются только к обычным файлам, а не к каталогам. Если значение preserve_symlinks равно true, символические ссылки будут скопированы как символические ссылки (на платформах, которые их поддерживают!); в противном случае (по умолчанию) будет скопировано место назначения символической ссылки. update и verbose такие же, как для copy_file().

Файлы в src, которые начинаются с .nfs, пропускаются (более подробная информация об этих файлах доступна в ответе D2 на NFS FAQ page).

Изменено в версии 3.3.1: Файлы NFS игнорируются.

distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])¶

Рекурсивно удалите directory и все файлы и каталоги, находящиеся под ним. Любые ошибки игнорируются (кроме сообщения о них в sys.stdout, если значение verbose равно true).

9.10. distutils.file_util — Операции с одним файлом¶

Этот модуль содержит некоторые служебные функции для работы с отдельными файлами.

distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])¶

Скопируйте файл src в dst. Если dst является каталогом, то src копируется туда с тем же именем; в противном случае это должно быть имя файла. (Если файл существует, он будет безжалостно удален). Если значение preserve_mode равно true (значение по умолчанию), копируется режим файла (тип и разрешения, или что-то аналогичное на текущей платформе). Если значение preserve_times равно true (значение по умолчанию), то также копируются время последнего изменения и время последнего доступа. Если значение update равно true, src будет скопирован только в том случае, если летнее время не существует или если летнее время существует, но оно старше src.

ссылка позволяет создавать жесткие ссылки (используя os.link()) или символьные ссылки (используя os.symlink()) вместо копирования: установите значение 'hard' или 'sym'; если это None (по умолчанию) файлы будут скопированы. Не устанавливайте link в системах, которые его не поддерживают: copy_file() не проверяет, доступна ли жесткая или символьная ссылка. Для копирования содержимого файла используется _copy_file_contents().

Возвращает кортеж (dest_name, copied): dest_name - это фактическое имя выходного файла, а copyed - значение true, если файл был скопирован (или был бы скопирован, если dry_run true).

distutils.file_util.move_file(src, dst[, verbose, dry_run])¶

Переместите файл src в dst. Если dst является каталогом, файл будет перемещен в него с тем же именем; в противном случае src просто переименовывается в dst. Возвращает новое полное имя файла.

Предупреждение

Обрабатывает перемещения между устройствами в Unix с помощью copy_file(). А как насчет других систем?

distutils.file_util.write_file(filename, contents)¶

Создайте файл с именем filename и запишите в него contents (последовательность строк без разделителей строк).

9.11. distutils.util — Прочие другие полезные функции¶

Этот модуль содержит множество других элементов, которые не помещаются ни в один другой служебный модуль.

distutils.util.get_platform()¶

Возвращает строку, идентифицирующую текущую платформу. Используется в основном для различения каталогов сборки для конкретной платформы и встроенных дистрибутивов для конкретной платформы. Обычно включает название и версию операционной системы, а также архитектуру (как указано в «os.uname()»), хотя точная информация зависит от операционной системы; например, в Linux версия ядра не особенно важна.

Примеры возвращаемых значений:

• linux-i586

• linux-alpha

• solaris-2.6-sun4u

Для платформ, отличных от POSIX, в настоящее время просто возвращается sys.platform.

Для систем macOS версия операционной системы отражает минимальную версию, на которой будут запускаться двоичные файлы (то есть значение MACOSX_DEPLOYMENT_TARGET во время сборки Python), а не версию операционной системы текущей системы.

Для сборок universal binary на macOS значение architecture отражает статус universal binary, а не архитектуру текущего процессора. Для 32-разрядных универсальных двоичных файлов используется архитектура fat, для 64-разрядных универсальных двоичных файлов используется архитектура fat64, а для 4-разрядных универсальных двоичных файлов используется архитектура universal. Начиная с Python 2.7 и Python 3.2 архитектура fat3 используется для трехсторонней универсальной сборки (ppc, i386, x86_64), а intel используется для универсальной сборки с архитектурами i386 и x86_64

Примеры возвращаемых значений в macOS:

• macosx-10.3-ppc

• macosx-10.3-fat

• macosx-10.5-universal

• macosx-10.6-intel

Для AIX Python 3.9 и более поздних версий возвращает строку, начинающуюся с «aix», за которой следуют дополнительные поля (разделенные символом '-'), которые представляют комбинированные значения версии AIX, выпуска и уровня технологии (первое поле), даты сборки (второе поле) и разрядности (третье поле). Python 3.8 и более ранних версий возвращал только одно дополнительное поле с указанием версии и выпуска AIX.

Примеры возвращаемых значений в AIX:

• aix-5307-0747-32 # 32- версия для AIX oslevel -s: 5300-07-00-0000

• aix-7105-1731-64 # 64- версия для AIX oslevel -s: 7100-05-01-1731

• aix-7.2 # Устаревшая форма, описанная в Python 3.8 и более ранних версиях

Изменено в версии 3.9: Формат строки для платформы AIX теперь также включает уровень технологии, дату сборки и разрядность ABI.

distutils.util.convert_path(pathname)¶

Верните „pathname“ как имя, которое будет работать в собственной файловой системе, т.е. разделите его на „/“ и снова соедините, используя текущий разделитель каталогов. Это необходимо потому, что имена файлов в сценарии установки всегда задаются в стиле Unix и должны быть преобразованы в соответствии с локальным соглашением, прежде чем мы сможем фактически использовать их в файловой системе. Вызывает ValueError в системах, отличных от Unix, если имя пути начинается или заканчивается косой чертой.

distutils.util.change_root(new_root, pathname)¶

Возвращает pathname с добавлением new_root. Если pathname является относительным, это эквивалентно os.path.join(new_root,pathname) В противном случае требуется сделать pathname относительным, а затем объединить их, что сложно в DOS / Windows.

distutils.util.check_environ()¶

Убедитесь, что в «os.environ» есть все переменные среды, которые, как мы гарантируем, пользователи могут использовать в конфигурационных файлах, параметрах командной строки и т.д. В настоящее время это включает:

• HOME - домашний каталог пользователя (только для Unix)

• PLAT - описание текущей платформы, включая аппаратное обеспечение и операционную систему (см. get_platform())

distutils.util.subst_vars(s, local_vars)¶

Выполните замену переменной в стиле shell/Perl на s. Каждое вхождение $, за которым следует имя, считается переменной, и переменная заменяется значением, найденным в словаре local_vars, или в os.environ, если его нет в local_vars. Сначала проверяется os.environ/дополнен, чтобы гарантировать, что он содержит определенные значения: смотрите check_environ(). Поднимите ValueError для любых переменных, не найденных ни в local_vars, ни в os.environ.

Обратите внимание, что это не полноценная функция интерполяции строк. Допустимый $variable может состоять только из прописных и строчных букв, цифр и символа подчеркивания. Кавычки в стиле { } или ( ) недоступны.

distutils.util.split_quoted(s)¶

Разделяйте строку в соответствии с правилами Unix shell для кавычек и обратной косой черты. Короче говоря, слова разделяются пробелами, если только эти пробелы не экранируются обратной косой чертой или не находятся внутри строки, заключенной в кавычки. Одинарные и двойные кавычки эквивалентны, и символы кавычек могут быть экранированы обратной косой чертой. Обратная косая черта удаляется из любой двухсимвольной escape-последовательности, оставляя только экранированный символ. Символы кавычек удаляются из любой заключенной в кавычки строки. Возвращает список слов.

distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])¶

Выполните какое-либо действие, влияющее на внешний мир (например, запись в файловую систему). Такие действия являются особенными, поскольку они запрещены флагом dry_run. Этот метод позаботится обо всей этой бюрократии за вас; все, что вам нужно сделать, это указать вызываемую функцию и кортеж аргументов для нее (чтобы воплотить выполняемое «внешнее действие»), а также необязательное сообщение для печати.

distutils.util.strtobool(val)¶

Преобразуйте строковое представление truth в true (1) или false (0).

Истинными значениями являются y, yes, t, true, on и 1; ложными значениями являются n, no, f, false, off и 0. Вызывает ValueError, если val - это что-то еще.

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])¶

Байт-скомпилируйте коллекцию исходных файлов Python в .pyc файлов в подкаталоге __pycache__ (см. PEP 3147 и PEP 488). py_files - это список файлов для компиляции; любые файлы, которые не заканчиваются на .py, автоматически пропускаются. optimize должен быть одним из следующих:

• 0 - не проводить оптимизацию

• 1 - обычная оптимизация (например, python -O)

• 2 - дополнительная оптимизация (например, python -OO)

Если значение force равно true, все файлы будут перекомпилированы независимо от временных меток.

Исходное имя файла, закодированное в каждом bytecode файле, по умолчанию соответствует именам файлов, указанным в py_files; вы можете изменить их с помощью prefix и basedir. prefix - это строка, которая будет удалена из каждого исходного имени файла, а base_dir - это имя каталога, которое будет добавляться перед именем (после удаления prefix). Вы можете указать один из них или оба (или ни один из них) из prefix и base_dir, как пожелаете.

Если dry_run имеет значение true, то на самом деле он не делает ничего, что могло бы повлиять на файловую систему.

Байт-компиляция выполняется либо непосредственно в этом процессе интерпретатора с помощью стандартного модуля py_compile, либо косвенно путем написания временного скрипта и его выполнения. Обычно вы должны позволить byte_compile() решить, использовать прямую компиляцию или нет (подробности смотрите в источнике). Флаг direct используется скриптом, сгенерированным в непрямом режиме; если вы не знаете, что делаете, оставьте его равным None.

Изменено в версии 3.2.3: Создайте .pyc файлы с import magic tag в названии в подкаталоге __pycache__ вместо файлов без тега в текущем каталоге.

Изменено в версии 3.5: Создайте .pyc файлов в соответствии с PEP 488.

distutils.util.rfc822_escape(header)¶

Возвращает экранированную версию header для включения в заголовок RFC 822, обеспечивая наличие 8 пробелов после каждой новой строки. Обратите внимание, что это не приводит к другим изменениям строки.

9.12. distutils.dist — Класс распределения¶

Этот модуль предоставляет класс Distribution, который представляет собой создаваемый/устанавливаемый/распространяемый дистрибутив модуля.

9.13. distutils.extension — Класс расширения¶

Этот модуль предоставляет класс Extension, используемый для описания модулей расширения C/C++ в сценариях установки.

9.14. distutils.debug — Режим отладки дистрибутивов¶

Этот модуль предоставляет флаг ОТЛАДКИ.

9.15. distutils.errors — Исключения из дистрибутивов¶

Предоставляет исключения, используемые модулями Distutils. Обратите внимание, что модули Distutils могут вызывать стандартные исключения; в частности, SystemExit обычно вызывается при ошибках, которые, очевидно, являются ошибкой конечного пользователя (например, неверные аргументы командной строки).

Этот модуль безопасен для использования в режиме from ... import *; он экспортирует только те символы, названия которых начинаются с Distutils и заканчиваются на Error.

9.16. distutils.fancy_getopt — Оболочка для стандартного модуля getopt¶

Этот модуль представляет собой оболочку для стандартного модуля getopt, который предоставляет следующие дополнительные функции:

• короткие и длинные варианты связаны друг с другом

• в параметрах есть строки справки, поэтому fancy_getopt() потенциально может создать полную сводку об использовании

• параметры задают атрибуты передаваемого объекта

• логические параметры могут иметь «отрицательные псевдонимы» - например, если --quiet является «отрицательным псевдонимом» для --verbose, то --quiet в командной строке устанавливает значение verbose равным false.

distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)¶

Функция-оболочка. options - это список из (long_option, short_option, help_string) 3-х кортежей, как описано в конструкторе для FancyGetopt. negative_opt должен быть словарем, сопоставляющим имена опций с именами опций, и ключ, и значение должны быть в списке options. object - это объект, который будет использоваться для хранения значений (смотрите метод getopt() класса FancyGetopt). args - это список аргументов. Будет использоваться sys.argv[1:], если вы передадите None как аргументы.

distutils.fancy_getopt.wrap_text(text, width)¶

Переносит текст на размер, меньший, чем ширина.

class distutils.fancy_getopt.FancyGetopt([option_table=None])¶

Таблица параметров представляет собой список из 3 кортежей: (long_option, short_option, help_string)

Если параметр принимает аргумент, к его long_option должен быть добавлен '='; short_option должен содержать только один символ, ни в коем случае не ':'. short_option должно быть None, если для long_option нет соответствующего short_option. Все кортежи параметров должны содержать длинные параметры.

Класс FancyGetopt предоставляет следующие методы:

FancyGetopt.getopt([args=None, object=None])¶

Анализируйте параметры командной строки в аргументах. Сохраняйте в качестве атрибутов в object.

Если значение args равно None или не указано, используется sys.argv[1:]. Если object равен None или не указан, создается новый экземпляр OptionDummy, в нем сохраняются значения параметров и возвращается кортеж (args, object). Если указан object, он модифицируется на месте, и getopt() просто возвращает args; в обоих случаях возвращаемый args является измененной копией переданного списка args, который остается нетронутым.

FancyGetopt.get_option_order()¶

Возвращает список (option, value) кортежей, обработанных предыдущим запуском getopt(), и возвращает RuntimeError, если getopt() еще не был вызван.

FancyGetopt.generate_help([header=None])¶

Сгенерируйте Helptext (список строк, по одной на каждую предлагаемую строку вывода) из таблицы параметров для этого объекта FancyGetopt.

Если указано, напечатайте прилагаемый заголовок в верхней части справки.

9.17. distutils.filelist — Класс FileList (Список файлов)¶

Этот модуль предоставляет класс FileList, используемый для работы с файловой системой и создания списков файлов.

9.18. distutils.log — Простое ведение журнала в стиле PEP 282¶

9.19. distutils.spawn — Создать подпроцесс¶

Этот модуль предоставляет функцию spawn(), являющуюся интерфейсом к различным функциям, зависящим от платформы, для запуска другой программы в подпроцессе. Также предоставляет find_executable() для поиска пути к заданному имени исполняемого файла.

9.20. distutils.sysconfig — Информация о конфигурации системы¶

Модуль distutils.sysconfig предоставляет доступ к низкоуровневой информации о конфигурации Python. Конкретные доступные переменные конфигурации в значительной степени зависят от платформы и конфигурации. Конкретные переменные зависят от процесса сборки для конкретной запускаемой версии Python; это переменные, которые содержатся в Makefile и заголовке конфигурации, которые устанавливаются вместе с Python в системах Unix. Заголовок конфигурации называется pyconfig.h для версий Python, начиная с 2.2, и config.h для более ранних версий Python.

Предусмотрены некоторые дополнительные функции, которые выполняют некоторые полезные манипуляции с другими частями пакета distutils.

distutils.sysconfig.PREFIX¶

Результат os.path.normpath(sys.prefix).

distutils.sysconfig.EXEC_PREFIX¶

Результат os.path.normpath(sys.exec_prefix).

distutils.sysconfig.get_config_var(name)¶

Возвращает значение единственной переменной. Это эквивалентно get_config_vars().get(name).

distutils.sysconfig.get_config_vars(...)¶

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

distutils.sysconfig.get_config_h_filename()¶

Возвращает полный путь к заголовку конфигурации. Для Unix это будет заголовок, сгенерированный скриптом configure; для других платформ заголовок будет предоставлен непосредственно из исходного кода Python. Файл представляет собой текстовый файл для конкретной платформы.

distutils.sysconfig.get_makefile_filename()¶

Возвращает полный путь к файлу Makefile, который использовался для сборки Python. Для Unix это будет файл, сгенерированный скриптом configure; значение для других платформ будет иным. Файл является текстовым файлом, зависящим от платформы, если он существует. Эта функция полезна только на платформах POSIX.

Следующие функции устарели вместе с этим модулем и не имеют прямой замены.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])¶

Возвращает каталог либо для общих, либо для зависящих от платформы C включаемых файлов. Если значение plat_specific равно true, возвращается платформенно-зависимый включаемый каталог; если значение false или опущено, возвращается платформенно-независимый каталог. Если задан prefix, то он используется либо как префикс вместо PREFIX, либо как exec-префикс вместо EXEC_PREFIX, если значение plat_specific равно true.

distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])¶

Возвращает каталог для установки либо общей библиотеки, либо библиотеки, зависящей от платформы. Если значение plat_specific равно true, возвращается каталог, зависящий от платформы; если значение false или опущено, возвращается каталог, независимый от платформы. Если задан prefix, то он используется либо как префикс вместо PREFIX, либо как exec-префикс вместо EXEC_PREFIX, если значение plat_specific равно true. Если значение standard_lib равно true, то возвращается каталог стандартной библиотеки, а не каталог для установки сторонних расширений.

Следующая функция предназначена только для использования в пакете distutils.

distutils.sysconfig.customize_compiler(compiler)¶

Выполните любую настройку экземпляра distutils.ccompiler.CCompiler для конкретной платформы.

На данный момент эта функция нужна только в Unix, но ее следует вызывать последовательно для поддержки прямой совместимости. Она вставляет информацию, которая варьируется в зависимости от версии Unix и хранится в Makefile Python. Эта информация включает в себя выбранный компилятор, параметры компилятора и компоновщика, а также расширение, используемое компоновщиком для общих объектов.

Эта функция еще более специализирована и должна использоваться только из собственных процедур сборки Python.

distutils.sysconfig.set_python_build()¶

Сообщите модулю distutils.sysconfig, что он используется как часть процесса сборки для Python. Это изменяет множество относительных расположений файлов, позволяя размещать их в области сборки, а не в установленном Python.

9.21. distutils.text_file — Класс textFile¶

Этот модуль предоставляет класс TextFile, который предоставляет интерфейс для текстовых файлов, который (необязательно) устраняет комментарии, игнорирует пустые строки и соединяет строки обратной косой чертой.

class distutils.text_file.TextFile([filename=None, file=None, **options])¶

Этот класс предоставляет файлоподобный объект, который выполняет все действия, которые обычно требуется выполнять при обработке текстового файла с построчным синтаксисом: удаляет комментарии (если # является символом комментария), пропускает пустые строки, соединяет соседние строки. строки, экранируя символ новой строки (т.е. обратную косую черту в конце строки), удаляйте начальные и/или конечные пробелы. Все они являются дополнительными и независимо управляемыми.

Класс предоставляет метод warn(), позволяющий генерировать предупреждающие сообщения, сообщающие номер физической строки, даже если рассматриваемая логическая строка охватывает несколько физических строк. Также предоставляет метод unreadline() для реализации пошагового просмотра.

TextFile экземпляры создаются либо с именем filename, file, либо с обоими. RuntimeError вызывается, если оба имеют значение None. filename должно быть строкой, а file файловым объектом (или чем-то, что предоставляет методы readline() и close()). Рекомендуется указать как минимум имя файла, чтобы TextFile мог включать его в предупреждающие сообщения. Если файл не указан, TextFile создает свой собственный файл, используя встроенную функцию open().

Все параметры являются логическими и влияют на значения, возвращаемые readline()

название опции	описание	по умолчанию
strip_комменты	зачеркнуть от '#' до конца строки, а также все пробелы, ведущие к '#'—, если только они не экранируются обратной косой чертой	истинный
lстрип_ws	удалите начальные пробелы из каждой строки, прежде чем возвращать их обратно	ложный
rstrip_ws (полоса пропускания)	удалите завершающий пробел (включая разделитель строки!) из каждой строки, прежде чем возвращать его обратно.	истинный
пропускать пробелы	пропускайте пустые строки после удаления комментариев и пробелов. ((Если значения lstrip_ws и rstrip_ws равны false, то некоторые строки могут состоять исключительно из пробелов: они не будут пропущены, даже если значение skip_blanks равно true.)	истинный
соединительные строки	если обратная косая черта является последним символом, отличным от символа новой строки, в строке после удаления комментариев и пробелов, присоедините к ней следующую строку, чтобы сформировать одну логическую строку; если N последовательных строк заканчиваются обратной косой чертой, то N+1 физических строк будут объединены в одну логическую строку.	ложный
свернуть_соединение	удалите начальные пробелы из строк, которые соединены с предыдущими; это имеет значение только в том случае, если (join_lines and not lstrip_ws)	ложный

Обратите внимание, что, поскольку rstrip_ws может удалять завершающий символ новой строки, семантика readline() должна отличаться от семантики метода readline() встроенного файлового объекта! В частности, readline() возвращает None для конца файла: пустая строка может быть просто пустой строкой (или полностью заполненной пробелами), если rstrip_ws имеет значение true, а skip_blanks - нет.

open(filename)¶

Откройте новый файл filename. Это переопределяет любые аргументы конструктора file или filename.

close()¶

Закройте текущий файл и забудьте все, что мы о нем знаем (включая имя файла и номер текущей строки).

warn(msg[, line=None])¶

Выведите (в stderr) предупреждающее сообщение, привязанное к текущей логической строке в текущем файле. Если текущая логическая строка в файле охватывает несколько физических строк, предупреждение относится ко всему диапазону, например "lines 3-5". Если указано значение line, оно переопределяет текущий номер строки; это может быть список или кортеж, указывающий диапазон физических строк, или целое число для одной физической строки.

readline()¶

Считывает и возвращает одну логическую строку из текущего файла (или из внутреннего буфера, если строки ранее были «непрочитанными» с unreadline()). Если параметр join_lines имеет значение true, это может включать чтение нескольких физических строк, объединенных в одну строку. Обновляет текущий номер строки, поэтому вызов warn() после readline() выдает предупреждение о только что прочитанных физических строках. Возвращает None в конце файла, поскольку пустая строка может появиться, если значение rstrip_ws равно true, а значение strip_blanks - нет.

readlines()¶

Считывает и возвращает список всех логических строк, оставшихся в текущем файле. При этом номер текущей строки обновляется до последней строки файла.

unreadline(line)¶

Поместите line (строку) во внутренний буфер, который будет проверяться будущими вызовами readline(). Удобно для реализации синтаксического анализатора с возможностью просмотра строки за строкой. Обратите внимание, что строки, которые являются «непрочитанными» с помощью unreadline(), впоследствии не очищаются повторно (без пробелов или чего-либо еще) при чтении с помощью readline(). Если выполняется несколько вызовов на unreadline() перед вызовом на readline(), большинство строк будут возвращены в самом последнем порядке.

9.22. distutils.version — Классы с номерами версий¶

9.23. distutils.cmd — Абстрактный базовый класс для команд Distutils¶

Этот модуль предоставляет абстрактный базовый класс Command.

class distutils.cmd.Command(dist)¶

Абстрактный базовый класс для определения командных классов, «рабочие пчелы» дистрибутива. Полезная аналогия для командных классов - это представление о них как о подпрограммах с локальными переменными, называемыми options. Параметры объявлены в initialize_options() и определены (с учетом их конечных значений) в finalize_options(), и оба они должны быть определены каждым классом команд. Различие между ними необходимо, поскольку значения параметров могут поступать из внешнего мира (командная строка, конфигурационный файл, …), и любые параметры, зависящие от других параметров, должны быть вычислены после обработки этих внешних воздействий - отсюда finalize_options(). Телом подпрограммы, где она выполняет всю свою работу на основе значений своих параметров, является метод run(), который также должен быть реализован каждым классом команд.

Конструктор класса принимает единственный аргумент dist, экземпляр Distribution.

9.24. Создание новой команды Distutils¶

В этом разделе описаны шаги по созданию новой команды Distutils.

Новая команда находится в модуле в пакете distutils.command. В этом каталоге есть образец шаблона с именем command_template. Скопируйте этот файл в новый модуль с тем же именем, что и у новой команды, которую вы реализуете. Этот модуль должен реализовывать класс с тем же именем, что и модуль (и команда). Так, например, чтобы создать команду peel_banana (чтобы пользователи могли запускать setup.py peel_banana), вы должны скопировать command_template в distutils/command/peel_banana.py, а затем отредактировать ее так, чтобы она реализовывала класс peel_banana, подкласс distutils.cmd.Command.

Подклассы Command должны определять следующие методы.

Command.initialize_options()¶

Установите значения по умолчанию для всех параметров, поддерживаемых этой командой. Обратите внимание, что эти значения по умолчанию могут быть заменены другими командами, сценарием установки, файлами конфигурации или командной строкой. Таким образом, здесь не место для кодирования зависимостей между параметрами; как правило, реализации initialize_options() - это просто набор назначений self.foo = None.

Command.finalize_options()¶

Установите окончательные значения для всех опций, поддерживаемых этой командой. Эта функция всегда вызывается как можно позже, т.е. после того, как будут выполнены все задания опций из командной строки или из других команд. Таким образом, здесь можно закодировать зависимости параметров: если foo зависит от bar, то можно безопасно установить foo из bar, если foo по-прежнему имеет то же значение, что и в initialize_options().

Command.run()¶

Смысл существования команды: выполнить действие, для выполнения которого она существует, управляемое параметрами, инициализируемыми в initialize_options(), настраиваемыми другими командами, сценарием установки, командной строкой и конфигурационными файлами, и завершенными в finalize_options(). Все выходные данные терминала и взаимодействие с файловой системой должны выполняться с помощью run().

Command.sub_commands¶

sub_commands формализует понятие «семейства» команд, например, install в качестве родительской команды с подкомандами install_lib, install_headers, и т.д. Родительский элемент семейства команд определяет sub_commands как атрибут класса; это список из 2-х кортежей (command_name, predicate), где имя_команды - строка, а предикат - функция, строка или None. predicate - это метод родительской команды, который определяет, применима ли соответствующая команда в текущей ситуации. (Например, install_headers применимо только в том случае, если у нас есть какие-либо заголовочные файлы C для установки.) Если предикат равен None, то эта команда применима всегда.

sub_commands обычно определяется в конце класса, поскольку предикаты могут быть методами класса, поэтому они должны быть уже определены. Каноническим примером является команда install.

9.25. distutils.command — Отдельные команды Distutils¶

9.26. distutils.command.bdist — Создайте двоичный установщик¶

9.27. distutils.command.bdist_packager — Абстрактный базовый класс для упаковщиков¶

9.28. distutils.command.bdist_dumb — Создайте «тупой» установщик¶

9.29. distutils.command.bdist_rpm — Создайте двоичный дистрибутив в виде Red hat RPM и SRPM¶

9.30. distutils.command.sdist — Создайте дистрибутив с исходным кодом¶

9.31. distutils.command.build — Создайте все файлы пакета¶

9.32. distutils.command.build_clib — Соберите любые библиотеки C в пакет¶

9.33. distutils.command.build_ext — Создавайте любые расширения в пакете¶

9.34. distutils.command.build_py — Создайте файлы .py/.pyc для пакета¶

class distutils.command.build_py.build_py¶

class distutils.command.build_py.build_py_2to3¶

Альтернативная реализация build_py, которая также запускает библиотеку преобразования 2to3 для каждого устанавливаемого файла .py. Чтобы использовать это в файле setup.py для дистрибутива, который предназначен для работы как с Python 2.x, так и с Python 3.x, добавьте:

try:
    from distutils.command.build_py import build_py_2to3 as build_py
except ImportError:
    from distutils.command.build_py import build_py

к вашему setup.py, а позже:

cmdclass = {'build_py': build_py}

к вызову функции setup().

9.35. distutils.command.build_scripts — Создание сценариев для пакета¶

9.36. distutils.command.clean — Очистите область сборки пакета¶

Эта команда удаляет временные файлы, созданные build и его подкомандами, такие как промежуточные скомпилированные объектные файлы. При выборе параметра --all будет удален весь каталог сборки.

Встроенные модули расширения in place не будут очищены, так как их нет в каталоге сборки.

9.37. distutils.command.config — Выполнить настройку пакета¶

9.38. distutils.command.install — Установите пакет¶

9.39. distutils.command.install_data — Установите файлы данных из пакета¶

9.40. distutils.command.install_headers — Установите заголовочные файлы C/C++ из пакета¶

9.41. distutils.command.install_lib — Установка библиотечных файлов из пакета¶

9.42. distutils.command.install_scripts — Установите файлы скрипта из пакета¶

9.43. distutils.command.register — Зарегистрируйте модуль с помощью индекса пакета Python¶

Команда register регистрирует пакет с индексом пакета Python. Более подробно это описано в PEP 301.

9.44. distutils.command.check — Проверьте метаданные пакета¶

Команда check выполняет некоторые проверки метаданных пакета. Например, она проверяет, что все необходимые метаданные предоставлены в качестве аргументов, передаваемых функции setup().