9. Справочник по API¶

9.1. distutils.core — Основная функциональность Distutils¶

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

distutils.core.setup(arguments)¶

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

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

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

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

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

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

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

значение	описание
init	Остановка после создания экземпляра 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 для переносимости)	список строк
define_macros	список макросов для определения; каждый макрос определяется с помощью кортежа (name, value), где значение - либо строка для определения, либо None для определения без конкретного значения (эквивалент #define FOO в исходном тексте или -DFOO в командной строке компилятора Unix C)	список кортежей
undef_macros	список макросов для явного неопределения	список строк
библиотечные_диры	список каталогов для поиска библиотек C/C++ во время компоновки	список строк
библиотеки	список имен библиотек (не имен файлов или путей) для компоновки	список строк
runtime_library_dirs.	список каталогов для поиска библиотек C/C++ во время выполнения (для разделяемых расширений это происходит при загрузке расширения)	список строк
extra_objects	список дополнительных файлов для компоновки (например, объектные файлы, не подразумеваемые „sources“, статическая библиотека, которая должна быть явно указана, бинарные файлы ресурсов и т.д.)	список строк
extra_compile_args.	любая дополнительная информация, специфичная для платформы и компилятора, которую следует использовать при компиляции исходных файлов в „sources“. Для платформ и компиляторов, где командная строка имеет смысл, это обычно список аргументов командной строки, но для других платформ это может быть что угодно.	список строк
extra_link_args	любая дополнительная информация, специфичная для платформы и компилятора, которую следует использовать при компоновке объектных файлов вместе для создания расширения (или для создания нового статического интерпретатора Python). Интерпретация аналогична интерпретации „extra_compile_args“.	список строк
экспорт_символов	список символов, экспортируемых из общего расширения. Используется не на всех платформах и, как правило, не нужен для расширений Python, которые обычно экспортируют ровно один символ: init + имя_расширения.	список строк
зависит	список файлов, от которых зависит расширение	список строк
язык	язык расширения (т.е. 'c', 'c++', 'objc'). Будет определен из исходных расширений, если не указан.	струна
опционально	указывает, что сбой сборки в расширении не должен прерывать процесс сборки, а просто пропускать расширение.	булева величина

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

class distutils.core.Distribution¶

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

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

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

class distutils.core.Command¶

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

9.2. distutils.ccompiler — базовый класс CCompiler¶

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

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

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

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

distutils.ccompiler.gen_preprocess_options(macros, include_dirs)¶

Сгенерируйте опции препроцессора Си (-D, -U, -I), используемые по крайней мере двумя типами компиляторов: типичным компилятором Unix и Visual C++. macros - это обычная вещь, список из 1- или 2-кортежей, где (name,) означает undefine (-U) макроса name, а (name, value) означает define (-D) макроса name в value. 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)¶

Заводская функция для генерации экземпляра некоторого подкласса CCompiler для заданной комбинации платформы/компилятора. 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 определяет интерфейс, который должен быть реализован реальными классами компилятора. Класс также имеет некоторые полезные методы, используемые несколькими классами компиляторов.

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

Конструктор каждого подкласса создает экземпляр объекта Compiler. Флаги: 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++
linker_so	компоновщик, используемый для создания разделяемых объектов и библиотек
linker_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.

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

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

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

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

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

При неудаче поднимает CompileError.

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

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

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

debug - булево значение; если оно истинно, то отладочная информация будет включена в библиотеку (обратите внимание, что на большинстве платформ это важно на этапе компиляции: флаг 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])¶

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

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

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

library_dirs, если поставляется, должен быть списком каталогов для поиска библиотек, которые были указаны как «голые» имена библиотек (т.е. без компонента каталога). Они находятся поверх системного значения по умолчанию и тех, которые передаются в add_library_dir() и/или set_library_dirs(). runtime_library_dirs - это список каталогов, которые будут встроены в разделяемую библиотеку и использоваться для поиска других разделяемых библиотек, от которых *it* зависит во время выполнения. (Это может быть актуально только для 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 не указан. macros - список макроопределений как для compile(), который дополнит макросы, заданные в define_macro() и undefine_macro(). include_dirs - список имен каталогов, которые будут добавлены к списку по умолчанию, аналогично add_include_dir().

При неудаче поднимает PreprocessError.

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

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

Возвращает имя файла исполняемого файла для заданного basename. Обычно для платформ, отличных от 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 в dst.

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 указывает, что текущее окружение было настроено скриптом SetEnv.Cmd SDK, или что переменные окружения были зарегистрированы при установке SDK; DISTUTILS_USE_SDK указывает, что пользователь distutils сделал явный выбор отменить выбор компилятора с помощью MSVCCompiler.

9.5. distutils.bcppcompiler — Borland Compiler¶

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

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

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

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

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

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

Создать архивный файл (например, zip или tar). base_name - имя создаваемого файла, за вычетом расширения, специфичного для формата; format - формат архива: один из 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 и под ним. compress должно быть '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 (если доступен), либо утилита InfoZIP zip (если установлена и найдена в пути поиска по умолчанию). Если ни одна из этих утилит недоступна, выдается сообщение DistutilsExecError. Возвращает имя выходного zip-файла.

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

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

distutils.dep_util.newer(source, target)¶

Возвращает true, если источник существует и более недавно изменен, чем цель, или если источник существует, а цель нет. Возвращает false, если оба существуют и цель того же возраста или новее, чем источник. Вернуть DistutilsFileError, если источник не существует.

distutils.dep_util.newer_pairwise(sources, targets)¶

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

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

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

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

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

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

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

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

Создайте все пустые каталоги под base_dir, необходимые для размещения там files. 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])¶

Рекурсивно удалить каталог и все файлы и каталоги под ним. Любые ошибки игнорируются (кроме сообщения 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 будет скопирован, только если dst не существует, или если dst существует, но старше, чем src.

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

Возвращает кортеж (dest_name, copied): dest_name - фактическое имя выходного файла, и copied - 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), а не версию ОС текущей системы.

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

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(). Для любых переменных, не найденных ни в local_vars, ни в ValueError, выдается сообщение os.environ.

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

distutils.util.split_quoted(s)¶

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

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

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

distutils.util.strtobool(val)¶

Преобразование строкового представления истины в 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¶

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

9.14. distutils.debug — Режим отладки Distutils¶

Этот модуль предоставляет флаг DEBUG.

9.15. distutils.errors — Исключения Distutils¶

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

distutils.fancy_getopt.wrap_text(text, width)¶

Обертывает текст до ширины менее ширины.

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

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

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

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

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

Разбор опций командной строки в args. Хранить как атрибуты объекта.

Если 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])¶

Генерирует текст справки (список строк, по одной на предлагаемую строку вывода) из таблицы опций для данного объекта 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, возвращается каталог include, зависящий от платформы; если 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()). Рекомендуется указывать как минимум filename, чтобы TextFile мог включать его в предупреждающие сообщения. Если file не предоставлен, TextFile создает свой собственный, используя встроенную функцию open().

Все опции являются булевыми и влияют на значения, возвращаемые readline().

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

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

open(filename)¶

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

close()¶

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

warn(msg[, line=None])¶

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

readline()¶

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

readlines()¶

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

unreadline(line)¶

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

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

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

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

class distutils.cmd.Command(dist)¶

Абстрактный базовый класс для определения классов команд, «рабочих пчел» Distutils. Полезной аналогией для классов команд является представление о них как о подпрограммах с локальными переменными, называемыми 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 как атрибут класса; это список из двух кортежей (command_name, predicate), где имя_команды - строка, а предикат - функция, строка или None. predicate - это метод родительской команды, который определяет, применима ли соответствующая команда в текущей ситуации. (Например, команда install_headers применима только в том случае, если у нас есть заголовочные файлы C для установки.) Если predicate равен 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_msi — Создание бинарного пакета Microsoft Installer¶

class distutils.command.bdist_msi.bdist_msi¶

9.30. distutils.command.bdist_rpm — Сборка бинарного дистрибутива в виде Redhat RPM и SRPM¶

9.31. distutils.command.sdist — Сборка исходного дистрибутива¶

9.32. distutils.command.build — Собрать все файлы пакета¶

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

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

9.35. 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 и 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.36. distutils.command.build_scripts — Сборка сценариев пакета¶

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

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

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

9.38. distutils.command.config — Выполнить конфигурацию пакета¶

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

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

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

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

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

9.44. distutils.command.register — Регистрация модуля в индексе пакетов Python¶

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

9.45. distutils.command.check — Проверка мета-данных пакета¶

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