Справочник 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 dotted name)	строка
sources	список имён файлов исходного кода, относительных к корню дистрибутива (где находится скрипт setup), в формате 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++ во время выполнения (для shared расширений, это момент загрузки расширения)	список строк
extra_objects	список дополнительных файлов для линковки (например, файлы .o, не подразумеваемые ‘sources’, статические библиотеки, которые необходимо явно указать, двоичные файлы ресурсов и т.д.)	список строк
extra_compile_args	любые дополнительные платформенно- и компиляторно-специфичные сведения для использования при компиляции файлов исходного кода в ‘sources’. Для платформ и компиляторов, где имеет смысл командная строка, это обычно список аргументов командной строки, но для других платформ это может быть что угодно.	список строк
extra_link_args	любые дополнительные платформенно- и компиляторно-специфичные сведения для использования при линковке файлов .o, для создания расширения (или для создания нового статического интерпретатора Python). Аналогичная интерпретация, как для ‘extra_compile_args’.	список строк
export_symbols	список символов, которые должны экспортироваться из shared расширения. Не используется на всех платформах и обычно не требуется для расширений Python, которые, как правило, экспортируют ровно один символ: init + имя_расширения.	список строк
depends	список файлов, от которых зависит расширение	список строк
language	язык расширения (например, 'c', 'c++', 'objc'). Будет определён из файлов исходного кода, если не указан.	строка
optional	указывается, что ошибка сборки расширения не должна прерывать процесс сборки, а просто пропустить расширение.	логическое значение

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

class distutils.core.Distribution

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

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

target_lang — целевой язык, для которого компилируются заданные объекты. Это позволяет применять специфическое обращение к определённым языкам во время компоновки.

Возникает LibError при ошибке.

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

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

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

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

Связывает общий объект. 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)

Если флаг 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 или zipfile.

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 истина, печатает краткое описание каждого mkdir в stdout. Возвращает список каталогов, которые были фактически созданы.

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 истина, ссылки будут копироваться как ссылки (на платформах, которые их поддерживают!); в противном случае (по умолчанию) содержимое ссылки будет скопировано. 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 истина).

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

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

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

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

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

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

Имя параметра	Описание	Значение по умолчанию
strip_comments	удаляет от '#' до конца строки, а также любые пробелы перед '#', если они не экранированы обратным слешем	true
lstrip_ws	удаляет начальные пробелы из каждой строки перед ее возвращением	false
rstrip_ws	удаляет конечные пробелы (включая символ новой строки!) из каждой строки перед ее возвращением.	true
skip_blanks	пропускает строки, которые пустые *после* удаления комментариев и пробелов. (Если оба параметра lstrip_ws и rstrip_ws ложны, то некоторые строки могут состоять только из пробелов: они *не* будут пропущены, даже если 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 имеет значение true, но skip_blanks — false.

open(filename)

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

close()

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

warn(msg[, line=None])

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

readline()

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

readlines()

Прочитать и вернуть список всех оставшихся логических строк в текущем файле. Это обновляет текущий номер строки до последней строки файла.

unreadline(line)

Поместить 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()

Устанавливает значения по умолчанию для всех поддерживаемых опций этой команды. Обратите внимание, что эти значения по умолчанию могут быть переопределены другими командами, скриптом 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 как атрибут класса; это список пар кортежей (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_msi — Сборка бинарного пакета с установщиком Microsoft Installer

class distutils.command.bdist_msi.bdist_msi

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

9.31. distutils.command.bdist_wininst — Сборка установщика Windows

9.32. distutils.command.sdist — Сборка дистрибутива исходных кодов

9.33. distutils.command.build — Сборка всех файлов пакета

9.34. distutils.command.build_clib — Сборка C библиотек в пакете

9.35. distutils.command.build_ext — Сборка расширений в пакете

9.36. 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.37. distutils.command.build_scripts — Сборка скриптов пакета

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

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

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

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

9.40. distutils.command.install — Установка пакета

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

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

9.43. distutils.command.install_lib — Установка файлов библиотек из пакета

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

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

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

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

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