Справочник 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

Объект 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 или в стандартный вывод, если 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)

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

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

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

• макросы, определенные с помощью -Dname[=value]
• макросы, не определенные с помощью -Uname
• директории поиска include, указанные с помощью -Idir
• библиотеки, указанные с помощью -llib
• директории поиска библиотек, указанные с помощью -Ldir
• компиляция, выполняемая исполняемым файлом cc (или аналогичным) с опцией -c: компилирует .c в .o
• связывание статической библиотеки, выполняемое командой ar (возможно, с ranlib)
• связывание динамической библиотеки, выполняемое cc -shared

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

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

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

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

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

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

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

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

Этот модуль предоставляет несколько функций для создания архивов, таких как 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, необходимые для размещения files. base_dir — просто имя каталога, который необязательно существует; files — список имен файлов, которые интерпретируются относительно base_dir. base_dir + каталожная часть каждого файла в files будет создана, если она еще не существует. Флаги mode, verbose и dry_run такие же, как для mkpath().

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

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

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

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

Изменено в версии 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.

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

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

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

• macosx-10.3-ppc
• macosx-10.3-fat
• macosx-10.5-universal
• macosx-10.6-intel

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)

Производит подстановку переменных в стиле оболочки shell/Perl в s. Любой фрагмент $ за которым следует имя, считается переменной, и переменная заменяется значением, найденным в словаре local_vars, или в os.environ в противном случае. Сначала проверяется/дополняется 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)

Преобразует строковое представление истинности в истинное (1) или ложное (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 истинно, все файлы будут перекомпилированы независимо от временных меток.

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

Если dry_run истинно, не выполняется никаких действий, влияющих на файловую систему.

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

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

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

distutils.util.rfc822_escape(header)

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

9.12. distutils.dist — Класс дистрибутива

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

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

Этот модуль предоставляет класс Extension, используемый для описания модулей расширения C/C++ в скриптах 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 в ложь.

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

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

open(filename)

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

close()

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

warn(msg[, line=None])

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

readline()

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

class distutils.command.bdist_msi.bdist_msi

Создает двоичный пакет установщика Windows (.msi).

В большинстве случаев установщик bdist_msi предпочтительнее установщика bdist_wininst, так как он обеспечивает лучшую поддержку платформ Win64, позволяет администраторам выполнять неинтерактивные установки и позволяет устанавливать через групповые политики.

9.30. distutils.command.bdist_rpm — Сборка двоичного дистрибутива как RPM Redhat и 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().