Справочник по API

9.1. distutils.core — Основной функционал Distutils

Модуль distutils.core — единственный модуль, который нужно установить для использования Distutils. Он предоставляет функцию setup() (которая вызывается из скрипта setup). Непосредственно предоставляет distutils.dist.Distribution и класс distutils.cmd.Command.

distutils.core.setup(arguments)

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

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

Имя аргумента	Значение	Тип
name	Имя пакета	строка
version	Номер версии пакета; см. distutils.version	строка
description	Однострочное описание пакета	строка
long_description	Подробное описание пакета	строка
author	Имя автора пакета	строка
author_email	Адрес электронной почты автора пакета	строка
maintainer	Имя текущего разработчика, если отличается от автора. Обратите внимание, что если разработчик указан, distutils будет использовать его в качестве автора в PKG-INFO	строка
maintainer_email	Адрес электронной почты текущего разработчика, если отличается от автора	строка
url	URL пакета (домашняя страница)	строка
download_url	URL для скачивания пакета	строка
packages	Список пакетов Python, которые будут обрабатываться distutils	список строк
py_modules	Список модулей Python, которые будут обрабатываться distutils	список строк
scripts	Список автономных скриптовых файлов, которые нужно будет создать и установить	список строк
ext_modules	Список расширений Python, которые нужно будет создать	список экземпляров distutils.core.Extension
classifiers	Список категорий пакета	список строк; допустимые классификаторы перечислены на PyPI.
distclass	используемый класс Distribution	подкласс distutils.core.Distribution
script_name	Имя скрипта setup.py — по умолчанию sys.argv[0]	строка
script_args	Аргументы для передачи скрипту setup	список строк
options	Параметры по умолчанию для скрипта setup	словарь
license	Лицензия пакета	строка
keywords	Дескриптивные метаданные, см. PEP 314	список строк или строка, разделенная запятыми
platforms		список строк или строка, разделенная запятыми
cmdclass	Отображение имен команд на подклассы Command	словарь
data_files	Список файлов данных для установки	список
package_dir	Отображение имен пакетов на имена каталогов	словарь

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

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

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

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

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

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

• Extension из distutils.extension
• Command из distutils.cmd
• Distribution из distutils.dist

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

class distutils.core.Extension

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

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

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

class distutils.core.Distribution

Распределение описывает, как собрать, установить и упаковать пакет программного обеспечения Python.

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

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

class distutils.core.Command

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

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

Этот модуль предоставляет абстрактный базовый класс для классов 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++. macros — это обычное дело, список 1- или 2-кортежей, где (name,) означает отмену определения (-U) макроса name, а (name, value) означает определение (-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(). Это не влияет на любой список стандартных каталогов включения, которые компилятор может искать по умолчанию.

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»), но большинство из них будут иметь:

атрибут	описание
compiler	компилятор C/C++
linker_so	линкер, используемый для создания shared object и библиотек
linker_exe	линкер, используемый для создания двоичных исполняемых файлов
archiver	создатель статических библиотек

На платформах с командной строкой (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, они должны быть списком определений макросов. Определение макроса представляет собой либо (name, value) пару из 2 элементов, либо (name,) пару из 1 элемента. Первая определяет макрос; если значение равно None, макрос определен без явного значения. Случай с 1-элементной парой отменяет определение макроса. Более поздние определения/переопределения/отмены имеют приоритет.

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

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(), и библиотек, предоставленных как 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])

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

«Набор элементов» состоит из списка объектных файлов, предоставленных как objects. 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 — это список каталогов, которые будут встроены в общую библиотеку и использоваться для поиска других общих библиотек, от которых *она* зависит во время выполнения. (Это может быть актуально только на 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])

Связывает shared object. output_filename — имя создаваемого shared object, а 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, это совпадает с basename, в то время как 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)

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

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

Этот модуль предоставляет класс 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, который обрабатывает порт компилятора GNU C для Cygwin в Windows. Он также содержит класс Mingw32CCompiler, который обрабатывает порт GCC mingw32 (так же, как cygwin в режиме без cygwin).

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

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

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. Использует модуль Python zipfile (если доступен) или утилиту InfoZIP zip (если установлена и найдена в пути поиска по умолчанию). Если ни одна из утилит недоступна, выводит DistutilsExecError. Возвращает имя выходного zip-файла.

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

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

distutils.dep_util.newer(source, target)

Возвращает True, если source существует и был изменён позже, чем target, или если source существует, а target нет. Возвращает False, если оба существуют и target имеет тот же возраст или новее, чем source. Вызывает DistutilsFileError если source не существует.

distutils.dep_util.newer_pairwise(sources, targets)

Обрабатывает два списка имён файлов параллельно, проверяя, является ли каждый исходный файл новее соответствующего целевого. Возвращает пару списков (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', любые отсутствующие исходные файлы заставляют нас предположить, что target устарел (это удобно в режиме «сухого запуска»: это заставит вас предположить выполнение команд, которые не сработали бы из-за отсутствия входных данных, но это не имеет значения, потому что вы не собираетесь фактически выполнять эти команды).

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

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

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

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

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

Изменено в версии 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 будет скопирован только в том случае, если 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 для 3-х архитектурной универсальной сборки (ppc, i386, x86_64) используется архитектура fat3, а для универсальной сборки с архитектурами i386 и x86_64 используется intel.

Примеры возвращаемых значений на 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’ как имя, которое будет работать в файловой системе, т.е. разделяет его по ‘/’ и собирает обратно, используя разделитель текущего каталога. Необходима, потому что имена файлов в скрипте setup всегда предоставляются в стиле 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)

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

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

distutils.util.split_quoted(s)

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

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 (см. PEP 3147 и PEP 488). py_files — это список файлов для компиляции; любые файлы, не заканчивающиеся на .py, проигнорируются. optimize должно быть одним из следующих:

• 0 - не оптимизировать
• 1 - обычная оптимизация (как python -O)
• 2 - дополнительная оптимизация (как python -OO)

Если force равно true, все файлы перекомпилируются независимо от отметки времени.

Имя исходного файла, закодированное в каждом файле байткода, по умолчанию совпадает с именами, перечисленными в 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

Этот модуль предоставляет класс 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 в ложь.

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

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

distutils.fancy_getopt.wrap_text(text, width)

Обрезает 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])

Разбирает опции командной строки в args. Сохраняет как атрибуты в 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])

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

Если предоставлен, выводит предоставленный header в верхней части справки.

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 истинно, возвращается каталог файлов заголовков, специфичный для платформы; если ложно или опущено, возвращается независимый от платформы каталог. Если задан prefix, он используется либо как префикс вместо PREFIX, либо как exec-префикс вместо EXEC_PREFIX, если plat_specific истинно.

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

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

Следующая функция предназначена только для использования внутри пакета 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 экземпляры создаются с помощью имя_файла, файл или обоих. RuntimeError генерируется, если оба являются None. имя_файла должно быть строкой, а файл — объектом файла (или чем-то, что предоставляет readline() и close() методы). Рекомендуется указать хотя бы имя_файла, чтобы TextFile мог включить его в сообщения об ошибках. Если файл не указан, TextFile создает свой собственный с помощью встроенной функции open().

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

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

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

open(filename)

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

close()

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

warn(msg[, line=None])

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

readline()

Прочитать и вернуть одну логическую строку из текущего файла (или из внутреннего буфера, если строки были предварительно «отменены» с помощью unreadline()). Если параметр join_lines равен true, это может потребовать чтения нескольких физических строк, сконкатенированных в одну строку. Обновляет текущий номер строки, поэтому вызов 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. Полезная аналогия для классов команд — это подпрограммы с локальными переменными, называемыми параметрами. Параметры объявляются в 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()

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

Command.finalize_options()

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

Command.run()

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

Command.sub_commands

sub_commands формализует понятие «семейства» команд, например, install в качестве родительской команды с подчиненными командами install_lib, install_headers, и т.д. Родитель семейства команд определяет sub_commands как атрибут класса; это список пар из 2-х кортежей (command_name, predicate), где 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_rpm — Построение двоичного дистрибутива в виде RPM и SRPM Red Hat

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, так и с 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 весь каталог построения будет удалён.

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

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