Справочник 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), где 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])

Возвращает boolean, указывающий, поддерживается ли 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, это то же самое, что и basename, а Windows добавит .exe.

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

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

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

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

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

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

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

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

spawn(cmd)

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

mkpath(name[, mode=511])

Вызывает distutils.dir_util.mkpath(). Это создаёт директорию и все отсутствующие родительские директории.

move_file(src, dst)

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

announce(msg[, level=1])

Выводит сообщение с помощью distutils.log.debug().

warn(msg)

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

debug_print(msg)

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

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

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

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

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

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

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

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

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

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

Этот модуль предоставляет класс CygwinCCompiler, подкласс UnixCCompiler, который обрабатывает порт Cygwin компилятора GNU C для Windows. Он также содержит класс Mingw32CCompiler, который обрабатывает порт mingw32 GCC (такой же, как 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 имеет значение True, то печатает краткое сообщение о каждом mkdir в стандартный вывод. Возвращает список каталогов, которые были фактически созданы.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

distutils.file_util.write_file(filename, contents)

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

9.11. distutils.util — Разные другие служебные функции

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

distutils.util.get_platform()

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

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

• linux-i586
• linux-alpha
• solaris-2.6-sun4u

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

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

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

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

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

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

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

• aix-5307-0747-32 # 32-разрядная сборка на AIX oslevel -s: 5300-07-00-0000
• aix-7105-1731-64 # 64-разрядная сборка на AIX oslevel -s: 7100-05-01-1731
• aix-7.2 # Формат, возвращаемый в Python 3.8 и ранее

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

distutils.util.convert_path(pathname)

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

distutils.util.change_root(new_root, pathname)

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

distutils.util.check_environ()

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

• HOME - домашний каталог пользователя (только Unix)
• PLAT - описание текущей платформы, включая аппаратное и программное обеспечение (см. get_platform())

distutils.util.subst_vars(s, local_vars)

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

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

distutils.util.split_quoted(s)

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

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

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

distutils.util.strtobool(val)

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

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

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

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

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

distutils.sysconfig.customize_compiler(compiler)

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

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

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

distutils.sysconfig.set_python_build()

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

9.21. distutils.text_file — Класс TextFile

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

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

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

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

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

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

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

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

open(filename)

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

close()

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

warn(msg[, line=None])

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

readline()

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

readlines()

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

unreadline(line)

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

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

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

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

class distutils.cmd.Command(dist)

Абстрактный базовый класс для определения классов команд, «рабочих лошадок» Distutils. Полезная аналогия для классов команд — рассматривать их как подпрограммы с локальными переменными, называемыми параметрами. Параметры объявляются в 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

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

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

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

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

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

9.35. distutils.command.build_py — Сборка файлов .py/.pyc пакета

class distutils.command.build_py.build_py

class distutils.command.build_py.build_py_2to3

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

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

в ваш файл setup.py, а затем:

cmdclass = {'build_py': build_py}

к вызову setup().

9.36. distutils.command.build_scripts — Сборка скриптов пакета

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

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

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

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

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

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

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

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

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

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

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

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

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