apiref.md

1> **Источник:** https://python-all.ru/3.0/distutils/apiref.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# Справочник API89## `distutils.core` – основная функциональность Distutils1011Модуль `distutils.core` – единственный модуль, который нужно установить для использования Distutils. Он предоставляет функцию [`setup()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.setup) (она вызывается из сценария установки). Косвенно предоставляет классы `distutils.dist.Distribution` и [`distutils.cmd.Command`](https://python-all.ru/3.0/distutils/apiref.html#distutils.cmd.Command).1213#### `[distutils.core.setup]distutils.core.setup(arguments)`1415Основная универсальная функция, которая делает почти всё, что может потребоваться от метода Distutils. См. XXXXX1617Функция setup принимает большое количество аргументов. Они перечислены в следующей таблице.1819| имя аргумента | значение | тип |20| --- | --- | --- |21| *имя* | Название пакета | строка |22| *версия* | Номер версии пакета | См. `distutils.version` |23| *описание* | Краткое описание пакета (одна строка) | строка |24| *long\_description* | Подробное описание пакета | строка |25| *author* | Имя автора пакета | строка |26| *author\_email* | Адрес электронной почты автора пакета | строка |27| *maintainer* | Имя текущего мейнтейнера, если оно отличается от автора | строка |28| *maintainer\_email* | Адрес электронной почты текущего сопровождающего, если он отличается от автора |  |29| *url* | URL пакета (домашняя страница) | URL |30| *download\_url* | URL для загрузки пакета | URL |31| *packages* | Список пакетов Python, которыми будет управлять distutils | список строк |32| *py\_modules* | Список модулей Python, которыми будет управлять distutils | список строк |33| *сценарии* | Список отдельных файлов скриптов, которые нужно собрать и установить | список строк |34| *ext\_modules* | Список расширений Python, которые необходимо собрать | Список экземпляров [`distutils.core.Extension`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Extension) |35| *classifiers* | Список категорий для пакета | Список доступных категорий находится по адресу [http://pypi.python.org/pypi?:action=list\_classifiers](https://python-all.ru/3.0/distutils/apiref.html). |36| *distclass* | класс [`Distribution`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Distribution) для использования | Подкласс [`distutils.core.Distribution`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Distribution) |37| *script\_name* | Имя скрипта setup.py – по умолчанию `sys.argv[0]` | строка |38| *script\_args* | Аргументы, передаваемые скрипту setup | список строк |39| *опции* | параметры по умолчанию для скрипта setup | строка |40| *лицензия* | Лицензия пакета | строка |41| *keywords* | Описательные метаданные, см. [**PEP 314**](https://python-all.ru/3.0/distutils/apiref.html) |  |42| *platforms* |  |  |43| *cmdclass* | Сопоставление имён команд с подклассами [`Command`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Command) | словарь |44| *data\_files* | Список файлов данных для установки | список |45| *package\_dir* | Сопоставление пакетов и имён каталогов | словарь |4647#### `[distutils.core.run_setup]distutils.core.run_setup(script_name[, script_args=None, stop_after='run'])`4849Запускает сценарий установки в частично контролируемом окружении и возвращает экземпляр `distutils.dist.Distribution`, который управляет процессом. Это полезно, если нужно получить метаданные дистрибутива (передаваемые в виде именованных аргументов из *script* в [`setup()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.setup)) или содержимое конфигурационных файлов или командной строки.5051*script\_name* – это файл, который будет прочитан и выполнен с помощью [`exec()`](https://python-all.ru/3.0/library/functions.html#exec). `sys.argv[0]` будет заменён на *script* на время вызова. *script\_args* – это список строк; если он указан, `sys.argv[1:]` будет заменён на *script\_args* на время вызова.5253*stop\_after* указывает [`setup()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.setup), когда останавливать обработку; возможные значения:5455| значение | описание |56| --- | --- |57| *init* | Остановиться после того, как экземпляр [`Distribution`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Distribution) был создан и заполнен именованными аргументами [`setup()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.setup) |58| *config* | Остановиться после того, как конфигурационные файлы будут разобраны (а их данные сохранены в экземпляре [`Distribution`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Distribution)) |59| *commandline* | Остановиться после того, как командная строка (`sys.argv[1:]` или *script\_args*) будет разобрана (а данные сохранены в экземпляре [`Distribution`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Distribution)) |60| *run* | Остановиться после выполнения всех команд (то же самое, как если бы [`setup()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.setup) была вызвана обычным способом). Это значение по умолчанию. |6162Кроме того, модуль `distutils.core` предоставлял ряд классов, которые находятся в других местах.6364- [`Extension`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Extension) из `distutils.extension`65- [`Command`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Command) из `distutils.cmd`66- [`Distribution`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Distribution) из `distutils.dist`6768Краткое описание каждого из них приведено ниже, но полную справку смотрите в соответствующем модуле.6970#### `[distutils.core.Extension]class distutils.core.Extension`7172Класс Extension описывает один модуль расширения на C или C++ в скрипте setup. Его конструктор принимает следующие именованные аргументы.7374| имя аргумента | значение | тип |75| --- | --- | --- |76| *имя* | полное имя расширения, включая любые пакеты – то есть *не* имя файла или путь, а точечное имя Python | строка |77| *sources* | список имён исходных файлов, относительно корня дистрибутива, корень (где setup-скрипт находится), в Unix-формате (косая черта) для переносимости. Исходные файлы могут быть на C, C++, SWIG (.i), платформенно-зависимые файлы ресурсов или что-либо ещё распознаётся командой **build\_ext** как исходный код для расширения Python. | строка |78| *include\_dirs* | список каталогов для поиска файлов заголовков C/C++ (в формате Unix для переносимости) | строка |79| *define\_macros* | список макросов для определения; каждый макрос определяется с помощью кортежа из двух элементов `(name, value)`, где *value* – это либо строка для определения значения, либо `None` для определения без конкретного значения (эквивалент `#define FOO` в исходном коде или *-DFOO* в командной строке C компилятора Unix) | (string, string) кортеж или (имя, `None`) |80| *undef\_macros* | список макросов, которые нужно явно отменить | строка |81| *library\_dirs* | список каталогов для поиска библиотек C/C++ во время компоновки | строка |82| *libraries* | список имён библиотек (не имён файлов или путей) для компоновки | строка |83| *runtime\_library\_dirs* | список каталогов для поиска библиотек C/C++ во время выполнения (для разделяемых расширений это момент загрузки расширения) | строка |84| *extra\_objects* | список дополнительных файлов для компоновки (например, объектные файлы, не входящие в «sources», статическая библиотека, которую нужно явно указать, бинарные ресурсные файлы и т.д.) | строка |85| *extra\_compile\_args* | любая дополнительная информация, зависящая от платформы и компилятора, используемая при компиляции исходных файлов из «sources». Для платформ и компиляторов, где командная строка имеет смысл, это обычно список аргументов командной строки, но для других платформ это может быть что угодно. | строка |86| *extra\_link\_args* | любая дополнительная информация, зависящая от платформы и компилятора, используемая при компоновке объектных файлов для создания расширения (или для создания нового статического интерпретатора Python). Интерпретация аналогична «extra\_compile\_args». | строка |87| *export\_symbols* | список символов для экспорта из разделяемого расширения. Не используется на всех платформах и обычно не требуется для расширений Python, которые обычно экспортируют ровно один символ: `init` + extension\_name. | строка |88| *зависит* | список файлов, от которых зависит расширение | строка |89| *язык* | язык расширения (т.е. `'c'`, `'c++'`, `'objc'`). Будет определён по расширениям исходных файлов, если не указан. | строка |9091#### `[distutils.core.Distribution]class distutils.core.Distribution`9293[`Distribution`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Distribution) описывает, как собрать, установить и упаковать программный пакет Python.9495См. функцию [`setup()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.setup) для списка ключевых аргументов, принимаемых конструктором Distribution. [`setup()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.setup) создаёт экземпляр Distribution.9697#### `[distutils.core.Command]class distutils.core.Command`9899Класс100101[`Command`](https://python-all.ru/3.0/distutils/apiref.html#distutils.core.Command)102103(а точнее, экземпляр одного из его подклассов) реализует одну команду distutils.104105## `distutils.ccompiler` – базовый класс CCompiler106107Этот модуль предоставляет абстрактный базовый класс для классов [`CCompiler`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler). Экземпляр [`CCompiler`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler) можно использовать для всех этапов компиляции и компоновки, необходимых для сборки одного проекта. Предоставляются методы для установки параметров компилятора – макроопределений, путей включения, путей компоновки, библиотек и тому подобного.108109Этот модуль предоставляет следующие функции.110111#### `[distutils.ccompiler.gen_lib_options]distutils.ccompiler.gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)`112113Генерирует параметры компоновщика для поиска каталогов библиотек и компоновки с конкретными библиотеками.114115*libraries*116117и118119*library\_dirs*120121– это соответственно списки имён библиотек (не имён файлов!) и каталогов поиска. Возвращает список параметров командной строки, подходящих для использования с некоторым компилятором (в зависимости от двух переданных строк формата).122123#### `[distutils.ccompiler.gen_preprocess_options]distutils.ccompiler.gen_preprocess_options(macros, include_dirs)`124125Генерирует параметры препроцессора C (126127*-D*128129,130131*-U*132133,134135*-I*136137), которые используются по меньшей мере двумя типами компиляторов: типичным Unix-компилятором и Visual C++. Параметр138139*macros*140141представляет собой обычный список из 1- или 2-кортежей, где142143`(name,)`144145означает отмену определения (146147*-U*148149) макроса150151*name*152153, а154155`(name, value)`156157– определение (158159*-D*160161) макроса162163*name*164165со значением166167*value*168169. Параметр170171*include\_dirs*172173– это просто список имён каталогов, которые добавляются в путь поиска заголовочных файлов (174175*-I*176177). Возвращает список параметров командной строки, подходящих как для Unix-компиляторов, так и для Visual C++.178179#### `[distutils.ccompiler.get_default_compiler]distutils.ccompiler.get_default_compiler(osname, platform)`180181Определяет компилятор по умолчанию для указанной платформы.182183*osname* должно быть одним из стандартных имён ОС Python (т.е. тех, что возвращаются `os.name`), а *platform* – обычным значением, возвращаемым `sys.platform` для данной платформы.184185Значения по умолчанию – `os.name` и `sys.platform`, если параметры не указаны.186187#### `[distutils.ccompiler.new_compiler]distutils.ccompiler.new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)`188189Фабричная функция для создания экземпляра некоторого подкласса CCompiler для заданной комбинации платформы/компилятора.190191*plat*192193по умолчанию равен194195`os.name`196197(например,198199`'posix'`200201,202203`'nt'`204205), а206207*compiler*208209по умолчанию равен компилятору по умолчанию для этой платформы. В настоящее время поддерживаются только210211`'posix'`212213и214215`'nt'`216217, а компиляторы по умолчанию – это «традиционный интерфейс Unix» (класс218219`UnixCCompiler`220221) и Visual C++ (класс222223`MSVCCompiler`224225). Обратите внимание, что вполне можно запросить объект компилятора Unix в Windows и объект компилятора Microsoft в Unix – если указать значение для226227*compiler*228229,230231*plat*232233игнорируется.234235#### `[distutils.ccompiler.show_compilers]distutils.ccompiler.show_compilers()`236237Выводит список доступных компиляторов (используется параметрами238239*--help-compiler*240241команд242243**build**244245,246247**build\_ext**248249,250251**build\_clib**252253).254255#### `[distutils.ccompiler.CCompiler]class distutils.ccompiler.CCompiler([verbose=0, dry_run=0, force=0])`256257Абстрактный базовый класс [`CCompiler`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler) определяет интерфейс, который должен быть реализован реальными классами компиляторов. Класс также содержит некоторые вспомогательные методы, используемые несколькими классами компиляторов.258259Основная идея абстрактного класса компилятора заключается в том, что каждый экземпляр может использоваться для всех этапов компиляции/компоновки при сборке одного проекта. Таким образом, атрибуты, общие для всех этих этапов компиляции и компоновки – каталоги включения, определяемые макросы, библиотеки для компоновки и т.д. – являются атрибутами экземпляра компилятора. Чтобы обеспечить возможность изменения обработки отдельных файлов, большинство этих атрибутов можно изменять для каждой компиляции или каждой компоновки отдельно.260261Конструктор каждого подкласса создаёт экземпляр объекта Compiler. Флаги: *verbose* (показывать подробный вывод), *dry\_run* (не выполнять шаги фактически) и *force* (пересобрать всё, независимо от зависимостей). Все эти флаги по умолчанию равны `0` (выключены). Обратите внимание: вероятно, не следует напрямую создавать экземпляр [`CCompiler`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler) или одного из его подклассов – вместо этого используйте фабричную функцию `distutils.CCompiler.new_compiler()`.262263The following methods allow you to manually alter compiler options for the instance of the Compiler class.264265#### `[distutils.ccompiler.CCompiler.add_include_dir]add_include_dir(dir)`266267Добавляет268269*dir*270271в список каталогов, в которых будет выполняться поиск заголовочных файлов. Компилятору предписывается искать каталоги в том порядке, в котором они передаются последовательными вызовами272273[`add_include_dir()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_include_dir)274275.276277#### `[distutils.ccompiler.CCompiler.set_include_dirs]set_include_dirs(dirs)`278279Устанавливает список каталогов для поиска равным280281*dirs*282283(список строк). Переопределяет любые предыдущие вызовы284285[`add_include_dir()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_include_dir)286287; последующие вызовы288289[`add_include_dir()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_include_dir)290291добавляют к списку, переданному в292293[`set_include_dirs()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.set_include_dirs)294295. Это не влияет на список стандартных каталогов включения, которые компилятор может искать по умолчанию.296297#### `[distutils.ccompiler.CCompiler.add_library]add_library(libname)`298299Add *libname* to the list of libraries that will be included in all links driven by this compiler object. Note that *libname* should \*not\* be the name of a file containing a library, but the name of the library itself: the actual filename will be inferred by the linker, the compiler, or the compiler class (depending on the platform).300301Компоновщику будет указано компоновать с библиотеками в том порядке, в котором они были переданы в [`add_library()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_library) и/или [`set_libraries()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.set_libraries). Дублирование имён библиотек вполне допустимо; компоновщику будет указано компоновать с библиотеками столько раз, сколько они упомянуты.302303#### `[distutils.ccompiler.CCompiler.set_libraries]set_libraries(libnames)`304305Set the list of libraries to be included in all links driven by this compiler object to306307*libnames*308309(a list of strings). This does not affect any standard system libraries that the linker may include by default.310311#### `[distutils.ccompiler.CCompiler.add_library_dir]add_library_dir(dir)`312313Добавляет314315*dir*316317в список каталогов, в которых будет выполняться поиск библиотек, указанных в318319[`add_library()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_library)320321и322323[`set_libraries()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.set_libraries)324325. Компоновщику будет указано искать библиотеки в том порядке, в котором они передаются в326327[`add_library_dir()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_library_dir)328329и/или330331[`set_library_dirs()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.set_library_dirs)332333.334335#### `[distutils.ccompiler.CCompiler.set_library_dirs]set_library_dirs(dirs)`336337Set the list of library search directories to338339*dirs*340341(a list of strings). This does not affect any standard library search path that the linker may search by default.342343#### `[distutils.ccompiler.CCompiler.add_runtime_library_dir]add_runtime_library_dir(dir)`344345Add346347*dir*348349to the list of directories that will be searched for shared libraries at runtime.350351#### `[distutils.ccompiler.CCompiler.set_runtime_library_dirs]set_runtime_library_dirs(dirs)`352353Set the list of directories to search for shared libraries at runtime to354355*dirs*356357(a list of strings). This does not affect any standard search path that the runtime linker may search by default.358359#### `[distutils.ccompiler.CCompiler.define_macro]define_macro(name[, value=None])`360361Определяет макрос препроцессора для всех компиляций, управляемых данным объектом компилятора. Необязательный параметр362363*value*364365должен быть строкой; если он не указан, макрос будет определён без явного значения, и точный результат зависит от используемого компилятора (XXX верно? говорит ли ANSI что-нибудь об этом?)366367#### `[distutils.ccompiler.CCompiler.undefine_macro]undefine_macro(name)`368369Отменяет макрос препроцессора для всех компиляций, выполняемых данным объектом компилятора. Если один и тот же макрос определён с помощью370371[`define_macro()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.define_macro)372373и отменён с помощью374375[`undefine_macro()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.undefine_macro)376377, последний вызов имеет приоритет (включая множественные переопределения или отмены). Если макрос переопределяется/отменяется для конкретной компиляции (т.е. в вызове378379[`compile()`](https://python-all.ru/3.0/library/functions.html#compile)380381), то приоритет у этого действия.382383#### `[distutils.ccompiler.CCompiler.add_link_object]add_link_object(object)`384385Add386387*object*388389to the list of object files (or analogues, such as explicitly named library files or the output of “resource compilers”) to be included in every link driven by this compiler object.390391#### `[distutils.ccompiler.CCompiler.set_link_objects]set_link_objects(objects)`392393Set the list of object files (or analogues) to be included in every link to394395*objects*396397. This does not affect any standard object files that the linker may include by default (such as system libraries).398399Следующие методы реализуют автодетекцию параметров компилятора, предоставляя функциональность, аналогичную GNU **autoconf**.400401#### `[distutils.ccompiler.CCompiler.detect_language]detect_language(sources)`402403Определяет язык указанного файла или списка файлов. Для этого используются атрибуты экземпляра404405`language_map`406407(словарь) и408409`language_order`410411(список).412413#### `[distutils.ccompiler.CCompiler.find_library_file]find_library_file(dirs, lib[, debug=0])`414415Ищет в указанном списке каталогов файл статической или динамической библиотеки416417*lib*418419и возвращает полный путь к этому файлу. Если420421*debug*422423истинно, ищет отладочную версию (если это имеет смысл на текущей платформе). Возвращает424425`None`426427, если428429*lib*430431не найден ни в одном из указанных каталогов.432433#### `[distutils.ccompiler.CCompiler.has_function]has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])`434435Возвращает логическое значение, указывающее, поддерживается ли436437*funcname*438439на текущей платформе. Необязательные аргументы можно использовать для расширения среды компиляции, предоставляя дополнительные включаемые файлы и пути, а также библиотеки и пути.440441#### `[distutils.ccompiler.CCompiler.library_dir_option]library_dir_option(dir)`442443Возвращает опцию компилятора для добавления444445*dir*446447в список каталогов, в которых выполняется поиск библиотек.448449#### `[distutils.ccompiler.CCompiler.library_option]library_option(lib)`450451Возвращает параметр компилятора для добавления452453*dir*454455в список библиотек, подключаемых к общей библиотеке или исполняемому файлу.456457#### `[distutils.ccompiler.CCompiler.runtime_library_dir_option]runtime_library_dir_option(dir)`458459Возвращает опцию компилятора для добавления460461*dir*462463в список каталогов, в которых выполняется поиск библиотек времени выполнения.464465#### `[distutils.ccompiler.CCompiler.set_executables]set_executables(**args)`466467Определяет исполняемые файлы (и параметры для них), которые будут запущены для выполнения различных этапов компиляции. Точный набор исполняемых файлов, которые могут быть здесь указаны, зависит от класса компилятора (через атрибут класса ‘executables’), но большинство будут иметь:468469| атрибут | описание |470| --- | --- |471| *compiler* | компилятор C/C++ |472| *linker\_so* | компоновщик, используемый для создания разделяемых объектов и библиотек |473| *linker\_exe* | компоновщик, используемый для создания двоичных исполняемых файлов |474| *archiver* | создатель статических библиотек |475476На платформах с командной строкой (Unix, DOS/Windows) каждая из этих строк разбивается на имя исполняемого файла и (необязательный) список аргументов. (Разбиение строки выполняется аналогично работе оболочек Unix: слова разделяются пробелами, но кавычки и обратная косая черта могут это переопределить. См. [`distutils.util.split_quoted()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.util.split_quoted).)477478Следующие методы вызывают этапы процесса сборки.479480#### `[distutils.ccompiler.CCompiler.compile]compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])`481482Компилирует один или несколько исходных файлов. Создаёт объектные файлы (например, преобразует файл `.c` в файл `.o`).483484*sources* должен быть списком имён файлов, скорее всего C/C++ файлов, но на самом деле любых, которые может обработать конкретный компилятор и класс компилятора (например, `MSVCCompiler` может обрабатывать ресурсные файлы в *sources*). Возвращает список имён объектных файлов, по одному для каждого исходного файла в *sources*. В зависимости от реализации не все исходные файлы обязательно будут скомпилированы, но все соответствующие имена объектных файлов будут возвращены.485486Если задан *output\_dir*, объектные файлы будут помещены в этот каталог с сохранением исходного пути. То есть `foo/bar.c` обычно компилируется в `foo/bar.o` (для реализации Unix); если *output\_dir* равен *build*, то он скомпилируется в `build/foo/bar.o`.487488*macros*, если задан, должен быть списком определений макросов. Определение макроса – это либо кортеж из двух элементов `(name, value)`, либо кортеж из одного элемента `(name,)`. Первый случай определяет макрос; если значение равно `None`, макрос определяется без явного значения. Кортеж из одного элемента отменяет макрос. Последующие определения/переопределения/отмены имеют приоритет.489490*include\_dirs*, если указан, должен быть списком строк – каталогов, добавляемых к пути поиска включаемых файлов по умолчанию только для данной компиляции.491492*debug* – логическое значение; если истинно, компилятору будет дано указание выводить отладочные символы в объектный файл (или рядом с ним).493494*extra\_preargs* и *extra\_postargs* зависят от реализации. На платформах, имеющих понятие командной строки (например, Unix, DOS/Windows), они, скорее всего, представляют собой списки строк: дополнительные аргументы командной строки, добавляемые в начало/конец командной строки компилятора. На других платформах обращайтесь к документации класса реализации. В любом случае они предназначены как запасной выход для тех случаев, когда абстрактная структура компилятора не справляется.495496*depends*, если указан, представляет собой список имен файлов, от которых зависят все цели. Если исходный файл старше любого файла из depends, то исходный файл будет перекомпилирован. Это обеспечивает отслеживание зависимостей, но только с грубой зернистостью.497498В случае ошибки вызывает `CompileError`.499500#### `[distutils.ccompiler.CCompiler.create_static_lib]create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])`501502Связывает вместе набор объектов для создания файла статической библиотеки. «Набор объектов» состоит из списка объектных файлов, переданных как *objects*, дополнительных объектных файлов, переданных в [`add_link_object()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_link_object) и/или [`set_link_objects()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.set_link_objects), библиотек, переданных в [`add_library()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_library) и/или [`set_libraries()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.set_libraries), а также библиотек, переданных как *libraries* (если есть).503504*output\_libname* должно быть именем библиотеки, а не именем файла; имя файла будет выведено из имени библиотеки. *output\_dir* – это каталог, в который будет помещён файл библиотеки. XXX значение по умолчанию?505506*debug* – логическое значение; если истинно, в библиотеку будет включена отладочная информация (обратите внимание: на большинстве платформ значение имеет этап компиляции; флаг *debug* добавлен здесь лишь для единообразия).507508*target\_lang* – целевой язык, для которого компилируются указанные объекты. Это позволяет выполнять специальную обработку на этапе компоновки для некоторых языков.509510В случае ошибки вызывает `LibError`.511512#### `[distutils.ccompiler.CCompiler.link]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])`513514Связывает всё вместе, чтобы создать исполняемый файл или файл динамической библиотеки.515516«Всё вместе» включает список объектных файлов, переданных в *objects*. *output\_filename* должно быть именем файла. Если *output\_dir* задан, *output\_filename* указывается относительно него (т.е. *output\_filename* может содержать компоненты пути).517518*libraries* – это список библиотек для линковки. Это имена библиотек, а не имена файлов, так как они преобразуются в имена файлов платформо-зависимым способом (например, *foo* становится `libfoo.a` на Unix и `foo.lib` на DOS/Windows). Однако они могут содержать компонент каталога, что означает, что линковщик будет искать в этом конкретном каталоге, а не во всех обычных местах.519520*library\_dirs*, если указано, должно быть списком каталогов для поиска библиотек, заданных как простые имена (без компонента каталога). Они добавляются к системным по умолчанию и тем, что указаны в [`add_library_dir()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_library_dir) и/или [`set_library_dirs()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.set_library_dirs). *runtime\_library\_dirs* – это список каталогов, которые будут встроены в разделяемую библиотеку и использоваться для поиска других разделяемых библиотек, от которых она зависит во время выполнения. (Это может быть актуально только на Unix.)521522*export\_symbols* – список символов, которые будет экспортировать динамическая библиотека. (Это актуально, по-видимому, только в Windows.)523524*debug* работает так же, как и в [`compile()`](https://python-all.ru/3.0/library/functions.html#compile) и [`create_static_lib()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.create_static_lib), с тем небольшим отличием, что на большинстве платформ это действительно важно (в отличие от [`create_static_lib()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.create_static_lib), которая включает флаг *debug* в основном для проформы).525526*extra\_preargs* и *extra\_postargs* аналогичны параметрам [`compile()`](https://python-all.ru/3.0/library/functions.html#compile) (за исключением, конечно, того, что они передают аргументы командной строки для конкретного используемого компоновщика).527528*target\_lang* – целевой язык, для которого компилируются указанные объекты. Это позволяет выполнять специальную обработку на этапе компоновки для некоторых языков.529530При неудаче вызывает `LinkError`.531532#### `[distutils.ccompiler.CCompiler.link_executable]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])`533534Компоновка исполняемого файла.535536*output\_progname*537538– это имя файла исполняемого файла, а539540*objects*541542– список имён объектных файлов для компоновки. Остальные аргументы аналогичны аргументам метода543544[`link()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.link)545546.547548#### `[distutils.ccompiler.CCompiler.link_shared_lib]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])`549550Компоновка разделяемой библиотеки.551552*output\_libname*553554– это имя выходной библиотеки, а555556*objects*557558– список имён объектных файлов для компоновки. Остальные аргументы аналогичны аргументам метода559560[`link()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.link)561562.563564#### `[distutils.ccompiler.CCompiler.link_shared_object]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])`565566Компоновка разделяемого объекта.567568*output\_filename*569570– это имя создаваемого разделяемого объекта, а571572*objects*573574– список имён объектных файлов для компоновки. Остальные аргументы аналогичны аргументам метода575576[`link()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.link)577578.579580#### `[distutils.ccompiler.CCompiler.preprocess]preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])`581582Препроцессинг одного файла исходного кода на C/C++, указанного в *source*. Результат будет записан в файл с именем *output\_file*, или в *stdout*, если *output\_file* не указан. *macros* – это список определений макросов, как в [`compile()`](https://python-all.ru/3.0/library/functions.html#compile), который дополнит макросы, заданные с помощью [`define_macro()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.define_macro) и [`undefine_macro()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.undefine_macro). *include\_dirs* – это список имён каталогов, которые будут добавлены к списку по умолчанию, так же как и в [`add_include_dir()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler.add_include_dir).583584При неудаче вызывает `PreprocessError`.585586Следующие вспомогательные методы определены в классе [`CCompiler`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler) для использования конкретными подклассами.587588#### `[distutils.ccompiler.CCompiler.executable_filename]executable_filename(basename[, strip_dir=0, output_dir=''])`589590Возвращает имя файла исполняемого файла для заданного591592*basename*593594. Обычно на платформах, отличных от Windows, это то же самое, что и базовое имя, а в Windows будет добавлено595596`.exe`597598.599600#### `[distutils.ccompiler.CCompiler.library_filename]library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])`601602Возвращает имя файла для заданного имени библиотеки на текущей платформе. На Unix библиотека с603604*lib\_type*605606равным607608`'static'`609610обычно будет иметь вид611612`liblibname.a`613614, а с615616*lib\_type*617618равным619620`'dynamic'`621622– вид623624`liblibname.so`625626.627628#### `[distutils.ccompiler.CCompiler.object_filenames]object_filenames(source_filenames[, strip_dir=0, output_dir=''])`629630Возвращает имена объектных файлов для заданных исходных файлов.631632*source\_filenames*633634должен быть списком имен файлов.635636#### `[distutils.ccompiler.CCompiler.shared_object_filename]shared_object_filename(basename[, strip_dir=0, output_dir=''])`637638Возвращает имя файла разделяемого объекта для заданного имени файла639640*basename*641642.643644#### `[distutils.ccompiler.CCompiler.execute]execute(func, args[, msg=None, level=1])`645646Вызывает647648[`distutils.util.execute()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.util.execute)649650. Этот метод вызывает функцию Python651652*func*653654с переданными аргументами655656*args*657658после логирования и с учётом флага659660*dry\_run*661662. XXX см. также.663664#### `[distutils.ccompiler.CCompiler.spawn]spawn(cmd)`665666Вызывает667668`distutils.util.spawn()`669670. Эта функция запускает внешний процесс для выполнения указанной команды. XXX см. также.671672#### `[distutils.ccompiler.CCompiler.mkpath]mkpath(name[, mode=511])`673674Вызывает675676[`distutils.dir_util.mkpath()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.dir_util.mkpath)677678. Создаёт каталог и все недостающие родительские каталоги. XXX см. также.679680#### `[distutils.ccompiler.CCompiler.move_file]move_file(src, dst)`681682Вызывает683684[`distutils.file_util.move_file()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.file_util.move_file)685686. Переименовывает687688*src*689690в691692*dst*693694. XXX см. также.695696#### `[distutils.ccompiler.CCompiler.announce]announce(msg[, level=1])`697698Записывает сообщение через699700`distutils.log.debug()`701702. XXX см. также.703704#### `[distutils.ccompiler.CCompiler.warn]warn(msg)`705706Записывает предупреждающее сообщение707708*msg*709710в стандартный поток ошибок.711712#### `[distutils.ccompiler.CCompiler.debug_print]debug_print(msg)`713714Если на данном экземпляре715716[`CCompiler`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler)717718установлен флаг719720*debug*721722, вывести723724*msg*725726в стандартный вывод, в противном случае ничего не делать.727728## `distutils.unixccompiler` – компилятор C Unix729730Этот модуль предоставляет класс `UnixCCompiler`, подкласс `CCompiler`, который работает с типичным Unix-стилем командной строки компилятора C:731732- макросы, определённые с помощью *-Dname\[=value\]*733- макросы, отменённые с помощью *-Uname*734- каталоги поиска заголовочных файлов, заданные с помощью *-Idir*735- библиотеки, заданные с помощью *-llib*736- каталоги поиска библиотек, заданные с помощью *-Ldir*737- компиляция выполняется исполняемым файлом **cc** (или аналогичным) с опцией [*-c*](https://python-all.ru/3.0/using/cmdline.html#cmdoption-c): компилирует `.c` в `.o`738- компоновка статической библиотеки выполняется командой **ar** (возможно, с **ranlib**)739- компоновка разделяемой библиотеки выполняется с помощью **cc** *-shared*740741## `distutils.msvccompiler` – компилятор Microsoft742743Этот модуль предоставляет `MSVCCompiler` – реализацию абстрактного класса `CCompiler` для Microsoft Visual Studio. Обычно модули расширения необходимо компилировать тем же компилятором, который использовался для компиляции Python. Для Python 2.3 и более ранних версий использовался Visual Studio 6. Для Python 2.4 и 2.5 – Visual Studio .NET 2003. Двоичные файлы для AMD64 и Itanium создаются с помощью Platform SDK.744745`MSVCCompiler` обычно сам выбирает нужный компилятор, компоновщик и т.д. Чтобы переопределить этот выбор, необходимо установить обе переменные окружения *DISTUTILS\_USE\_SDK* и *MSSdk*. *MSSdk* указывает, что текущее окружение было настроено скриптом `SetEnv.Cmd` из SDK, или что переменные окружения были зарегистрированы при установке SDK; *DISTUTILS\_USE\_SDK* указывает, что пользователь distutils явно решил переопределить выбор компилятора с помощью `MSVCCompiler`.746747## `distutils.bcppcompiler` – компилятор Borland748749Этот модуль предоставляет `BorlandCCompiler` – подкласс абстрактного класса `CCompiler` для компилятора Borland C++.750751## `distutils.cygwincompiler` – компилятор Cygwin752753Этот модуль предоставляет класс `CygwinCCompiler`, подкласс `UnixCCompiler`, который работает с портом GNU C компилятора для Windows под Cygwin. Он также содержит класс Mingw32CCompiler, который работает с портом GCC для mingw32 (то же, что и cygwin в режиме без cygwin).754755## `distutils.emxccompiler` – компилятор OS/2 EMX756757Этот модуль предоставляет класс EMXCCompiler, подкласс `UnixCCompiler`, который обеспечивает порт EMX компилятора GNU C для OS/2.758759## `distutils.mwerkscompiler` – поддержка Metrowerks CodeWarrior760761Содержит `MWerksCompiler` – реализацию абстрактного `CCompiler` класса для MetroWerks CodeWarrior на Macintosh до Mac OS X. Требуется доработка для поддержки CW на Windows или Mac OS X.762763## `distutils.archive_util` – утилиты архивирования764765Этот модуль предоставляет несколько функций для создания архивных файлов, таких как tar-архивы или zip-файлы.766767#### `[distutils.archive_util.make_archive]distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])`768769Создаёт архивный файл (например, `zip` или `tar`). *base\_name* – это имя создаваемого файла без расширения, зависящего от формата; *format* – формат архива: один из `zip`, `tar`, `ztar` или `gztar`. *root\_dir* – каталог, который будет корневым каталогом архива; то есть обычно мы выполняем `chdir` в *root\_dir* перед созданием архива. *base\_dir* – каталог, с которого начинается архивация; то есть *base\_dir* будет общим префиксом всех файлов и каталогов в архиве. *root\_dir* и *base\_dir* по умолчанию равны текущему каталогу. Возвращает имя файла архива.770771> **Предупреждение**772>773> Это нужно изменить для поддержки файлов bz2774775#### `[distutils.archive_util.make_tarball]distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])`776777Создаёт (возможно, сжатый) архив в виде tar-файла из всех файлов в *base\_dir* и всех его подкаталогах. *compress* должен быть `'gzip'` (по умолчанию), `'compress'`, `'bzip2'` или `None`. И **tar**, и утилита сжатия, указанная в *compress*, должны быть доступны в стандартном пути поиска программ, поэтому это, вероятно, специфично для Unix. Выходной tar-файл будет назван `base_dir.tar`, возможно с добавлением соответствующего расширения сжатия (`.gz`, `.bz2` или `.Z`). Возвращает имя выходного файла.778779> **Предупреждение**780>781> Это следует заменить на вызовы модуля [`tarfile`](https://python-all.ru/3.0/library/tarfile.html#module-tarfile).782783#### `[distutils.archive_util.make_zipfile]distutils.archive_util.make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])`784785Создаёт zip-файл из всех файлов внутри и в подкаталогах786787*base\_dir*788789. Результирующий zip-файл будет назван790791*base\_dir*792793+794795`.zip`796797. Использует либо модуль798799[`zipfile`](https://python-all.ru/3.0/library/zipfile.html#module-zipfile)800801Python (если доступен), либо утилиту InfoZIP802803`zip`804805(если установлена и найдена в стандартном пути поиска). Если ни один инструмент не доступен, возбуждает806807`DistutilsExecError`808809. Возвращает имя результирующего zip-файла.810811## `distutils.dep_util` – проверка зависимостей812813Этот модуль предоставляет функции для простой проверки зависимостей файлов и групп файлов на основе временных меток; а также функции, полностью основанные на таком анализе зависимостей по временным меткам.814815#### `[distutils.dep_util.newer]distutils.dep_util.newer(source, target)`816817Возвращает истину, если818819*source*820821существует и был изменён позже, чем822823*target*824825, или если826827*source*828829существует, а830831*target*832833– нет. Возвращает ложь, если оба существуют и834835*target*836837имеет тот же возраст или новее, чем838839*source*840841. Возбуждает842843`DistutilsFileError`844845, если846847*source*848849не существует.850851#### `[distutils.dep_util.newer_pairwise]distutils.dep_util.newer_pairwise(sources, targets)`852853Обходит два списка имён файлов параллельно, проверяя, является ли каждый исходный файл новее соответствующего целевого. Возвращает пару списков (854855*sources*856857,858859*targets*860861), где исходный файл новее целевого, согласно семантике862863[`newer()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.dep_util.newer)864865#### `[distutils.dep_util.newer_group]distutils.dep_util.newer_group(sources, target[, missing='error'])`866867Возвращает истину, если868869*target*870871устарел относительно любого файла из списка872873*sources*874875. Другими словами, если876877*target*878879существует и новее каждого файла из880881*sources*882883, возвращает ложь; в противном случае возвращает истину.884885*missing*886887управляет тем, что делать, если исходный файл отсутствует; значение по умолчанию (888889`'error'`890891) – завершиться с ошибкой892893[`OSError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OSError)894895изнутри896897[`os.stat()`](https://python-all.ru/3.0/library/os.html#os.stat)898899; если это900901`'ignore'`902903, мы молча пропускаем отсутствующие исходные файлы; если это904905`'newer'`906907, то любой отсутствующий исходный файл заставляет считать, что908909*target*910911устарел (это удобно в режиме «сухого прогона»: он заставит имитировать выполнение команд, которые не сработают из-за отсутствия входных данных, но это не имеет значения, так как команды на самом деле не выполняются).912913## `distutils.dir_util` – операции с деревом каталогов914915Этот модуль предоставляет функции для работы с каталогами и деревьями каталогов.916917#### `[distutils.dir_util.mkpath]distutils.dir_util.mkpath(name[, mode=0o777, verbose=0, dry_run=0])`918919Создаёт каталог и все отсутствующие родительские каталоги. Если каталог уже существует (или920921*name*922923– пустая строка, означающая текущий каталог, который, разумеется, существует), то ничего не делает. Возбуждает924925`DistutilsFileError`926927, если не удаётся создать какой-либо каталог по пути (например, существует вложенный путь, но это файл, а не каталог). Если928929*verbose*930931имеет значение true, выводит в stdout по одной строке-сводке для каждого mkdir. Возвращает список фактически созданных каталогов.932933#### `[distutils.dir_util.create_tree]distutils.dir_util.create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])`934935Создаёт все пустые каталоги внутри936937*base\_dir*938939, необходимые для размещения940941*files*942943.944945*base\_dir*946947– это просто имя каталога, который может ещё не существовать;948949*files*950951– список имён файлов, интерпретируемых относительно952953*base\_dir*954955.956957*base\_dir*958959вместе с каталоговой частью каждого файла из960961*files*962963будет создан, если его ещё нет. Флаги964965*mode*966967,968969*verbose*970971и972973*dry\_run*974975работают так же, как в976977[`mkpath()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.dir_util.mkpath)978979.980981#### `[distutils.dir_util.copy_tree]distutils.dir_util.copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])`982983Копирует всё дерево каталогов *src* в новое расположение *dst*. Оба *src* и *dst* должны быть именами каталогов. Если *src* не является каталогом, возбуждается `DistutilsFileError`. Если *dst* не существует, он создаётся с помощью [`mkpath()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.dir_util.mkpath). Конечный результат копирования: каждый файл в *src* копируется в *dst*, а каталоги в *src* рекурсивно копируются в *dst*. Возвращает список файлов, которые были скопированы или могли быть скопированы, с использованием их выходного имени. Возвращаемое значение не зависит от *update* или *dry\_run*: это просто список всех файлов в *src*, с именами, изменёнными на принадлежащие *dst*.984985*preserve\_mode* и *preserve\_times* такие же, как в `copy_file()` из `distutils.file_util`; они применяются только к обычным файлам, не к каталогам. Если *preserve\_symlinks* равен true, символические ссылки копируются как символические ссылки (на платформах, которые их поддерживают!); иначе (по умолчанию) копируется объект, на который указывает ссылка. *update* и *verbose* такие же, как в `copy_file()`.986987#### `[distutils.dir_util.remove_tree]distutils.dir_util.remove_tree(directory[, verbose=0, dry_run=0])`988989Рекурсивно удаляет990991*directory*992993и все файлы и каталоги внутри него. Любые ошибки игнорируются (за исключением вывода в994995`sys.stdout`996997, если998999*verbose*10001001имеет значение true).10021003**\*\*** Часть этого можно заменить модулем shutil? **\*\***10041005## `distutils.file_util` – операции с отдельными файлами10061007Этот модуль содержит несколько служебных функций для работы с отдельными файлами.10081009#### `[distutils.file_util.copy_file]distutils.file_util.copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])`10101011Копирует файл *src* в *dst*. Если *dst* является каталогом, то *src* копируется туда с тем же именем; в противном случае это должно быть имя файла. (Если файл существует, он будет безжалостно перезаписан.) Если *preserve\_mode* равен true (по умолчанию), то копируется режим файла (тип и биты разрешений, или что-то аналогичное на текущей платформе). Если *preserve\_times* равен true (по умолчанию), то также копируются время последнего изменения и последнего доступа. Если *update* равен true, то *src* будет скопирован только если *dst* не существует, или если *dst* существует, но старше, чем *src*.10121013*link* позволяет создавать жёсткие ссылки (с помощью [`os.link()`](https://python-all.ru/3.0/library/os.html#os.link)) или символические ссылки (с помощью [`os.symlink()`](https://python-all.ru/3.0/library/os.html#os.symlink)) вместо копирования: установите его в `'hard'` или `'sym'`; если он равен `None` (по умолчанию), файлы копируются. Не устанавливайте *link* в системах, которые его не поддерживают: [`copy_file()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.file_util.copy_file) не проверяет, доступно ли создание жёстких или символических ссылок. Для копирования содержимого файлов используется `_copy_file_contents()`.10141015Возвращает кортеж `(dest_name, copied)`: *dest\_name* – это фактическое имя выходного файла, а *copied* имеет значение true, если файл был скопирован (или был бы скопирован, если *dry\_run* имеет значение true).10161017#### `[distutils.file_util.move_file]distutils.file_util.move_file(src, dst[, verbose, dry_run])`10181019Перемещает файл *src* в *dst*. Если *dst* является каталогом, файл будет перемещён в него с тем же именем; в противном случае *src* просто переименовывается в *dst*. Возвращает новое полное имя файла.10201021> **Предупреждение**1022>1023> Обрабатывает перемещение между устройствами на Unix с помощью [`copy_file()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.file_util.copy_file). А как насчёт других систем???10241025#### `[distutils.file_util.write_file]distutils.file_util.write_file(filename, contents)`10261027Создаёт файл с именем10281029*filename*10301031и записывает в него10321033*contents*10341035(последовательность строк без символов конца строки).10361037## `distutils.util` – прочие вспомогательные функции10381039Этот модуль содержит другие разрозненные элементы, которые не вписываются ни в один другой вспомогательный модуль.10401041#### `[distutils.util.get_platform]distutils.util.get_platform()`10421043Возвращает строку, идентифицирующую текущую платформу. В основном используется для различения платформозависимых каталогов сборки и платформозависимых готовых дистрибутивов. Обычно включает имя и версию ОС, а также архитектуру (как их возвращает ‘os.uname()’), хотя точный состав информации зависит от ОС; например, для IRIX архитектура не особенно важна (IRIX работает только на оборудовании SGI), а для Linux версия ядра не особенно важна.10441045Примеры возвращаемых значений:10461047- `linux-i586`1048- `linux-alpha`1049- `solaris-2.6-sun4u`1050- `irix-5.3`1051- `irix64-6.2`10521053Для платформ, отличных от POSIX, в настоящее время просто возвращает `sys.platform`.10541055Для систем MacOS X версия ОС отражает минимальную версию, на которой будут выполняться бинарные файлы (то есть значение `MACOSX_DEPLOYMENT_TARGET` во время сборки Python), а не версию ОС текущей системы.10561057Для универсальных бинарных сборок на MacOS X значение архитектуры отражает статус универсального бинарного файла, а не архитектуру текущего процессора. Для 32-разрядных универсальных бинарных файлов архитектура – `fat`, для 64-разрядных – `fat64`, а для четырёхкомпонентных универсальных бинарных файлов – `universal`.10581059Примеры возвращаемых значений на MacOS X:10601061- `macosx-10.3-ppc`1062- `macosx-10.3-fat`1063- `macosx-10.5-universal`10641065#### `[distutils.util.convert_path]distutils.util.convert_path(pathname)`10661067Возвращает 'pathname' как имя, которое будет работать в родной файловой системе, т.е. разделяет его по '/' и снова собирает, используя текущий разделитель каталогов. Это необходимо, потому что имена файлов в скрипте установки всегда указываются в стиле Unix и должны быть преобразованы в локальное соглашение, прежде чем их можно будет использовать в файловой системе. Вызывает10681069[`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError)10701071на системах, не похожих на Unix, если10721073*pathname*10741075начинается или заканчивается косой чертой.10761077#### `[distutils.util.change_root]distutils.util.change_root(new_root, pathname)`10781079Возвращает10801081*pathname*10821083с добавленным в начало10841085*new\_root*10861087. Если10881089*pathname*10901091является относительным, это эквивалентно10921093`os.path.join(new_root,pathname)`10941095. В противном случае требуется сделать10961097*pathname*10981099относительным, а затем объединить их, что сложно на DOS/Windows.11001101#### `[distutils.util.check_environ]distutils.util.check_environ()`11021103Гарантирует, что 'os.environ' содержит все переменные окружения, которые пользователи могут использовать в конфигурационных файлах, параметрах командной строки и т.д. В настоящее время это включает:11041105- **HOME** - домашний каталог пользователя (только Unix)1106- **PLAT** - описание текущей платформы, включая аппаратное обеспечение и ОС (см. [`get_platform()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.util.get_platform))11071108#### `[distutils.util.subst_vars]distutils.util.subst_vars(s, local_vars)`11091110Выполняет подстановку переменных в стиле shell/Perl для *s*. Каждое вхождение `$`, за которым следует имя, считается переменной, и переменная заменяется значением из словаря *local\_vars* или из `os.environ`, если её нет в *local\_vars*. *os.environ* сначала проверяется/дополняется, чтобы гарантировать, что он содержит определённые значения: см. [`check_environ()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.util.check_environ). Вызывает [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError) для любых переменных, не найденных ни в *local\_vars*, ни в `os.environ`.11111112Обратите внимание, что это не полноценная функция интерполяции строк. Допустимая `$variable` может состоять только из прописных и строчных букв, цифр и символа подчёркивания. Кавычки в стиле { } или ( ) не поддерживаются.11131114#### `[distutils.util.grok_environment_error]distutils.util.grok_environment_error(exc[, prefix='error: '])`11151116Формирует полезное сообщение об ошибке из объекта исключения11171118[`EnvironmentError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.EnvironmentError)11191120(11211122[`IOError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.IOError)11231124или11251126[`OSError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.OSError)11271128). Поддерживает стили Python 1.5.1 и новее, и делает всё возможное для обработки объектов исключений, у которых нет имени файла (это происходит, когда ошибка связана с операцией над двумя файлами, например,11291130`rename()`11311132или11331134`link()`11351136). Возвращает сообщение об ошибке в виде строки с префиксом11371138*prefix*11391140.11411142#### `[distutils.util.split_quoted]distutils.util.split_quoted(s)`11431144Разделяет строку по правилам, похожим на оболочку Unix, для кавычек и обратной косой черты. Кратко: слова разделяются пробелами, если эти пробелы не экранированы обратной косой чертой или не находятся внутри строки в кавычках. Одинарные и двойные кавычки эквивалентны, и символы кавычек могут быть экранированы обратной косой чертой. Обратная косая черта удаляется из любой двухсимвольной escape-последовательности, оставляя только экранированный символ. Символы кавычек удаляются из любой строки в кавычках. Возвращает список слов.11451146#### `[distutils.util.execute]distutils.util.execute(func, args[, msg=None, verbose=0, dry_run=0])`11471148Выполняет некоторое действие, влияющее на внешний мир (например, запись в файловую систему). Такие действия особенны тем, что они отключаются флагом11491150*dry\_run*11511152. Этот метод берет на себя всю эту бюрократию; все, что нужно сделать – предоставить вызываемую функцию и кортеж аргументов для нее (чтобы воплотить выполняемое «внешнее действие») и необязательное сообщение для вывода.11531154#### `[distutils.util.strtobool]distutils.util.strtobool(val)`11551156Преобразует строковое представление истинности в true (1) или false (0).11571158Истинные значения: `y`, `yes`, `t`, `true`, `on` и `1`; ложные значения: `n`, `no`, `f`, `false`, `off` и `0`. Вызывает [`ValueError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.ValueError), если *val* – что-то другое.11591160#### `[distutils.util.byte_compile]distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])`11611162Компилирует набор исходных файлов Python в байт-код, создавая файлы `.pyc` или `.pyo` в том же каталоге. *py\_files* – это список файлов для компиляции; любые файлы, не оканчивающиеся на `.py`, молча пропускаются. *optimize* должен быть одним из следующих значений:11631164- `0` – не оптимизировать (создавать `.pyc`)1165- `1` – обычная оптимизация (как `python -O`)1166- `2` – дополнительная оптимизация (как `python -OO`)11671168Если *force* равно true, все файлы перекомпилируются независимо от временных меток.11691170Имя исходного файла, закодированное в каждом [*bytecode*](https://python-all.ru/3.0/glossary.html#term-bytecode) файле, по умолчанию соответствует именам файлов, перечисленным в *py\_files*; их можно изменить с помощью *prefix* и *basedir*. *prefix* – это строка, которая будет отрезана от каждого имени исходного файла, а *base\_dir* – это имя каталога, которое будет добавлено спереди (после того, как *prefix* будет отрезан). Можно указать либо *prefix*, либо *base\_dir*, или оба, или ни одного, по желанию.11711172Если *dry\_run* равно true, на самом деле не выполняет никаких действий, влияющих на файловую систему.11731174Байт-компиляция выполняется либо непосредственно в этом процессе интерпретатора с помощью стандартного модуля [`py_compile`](https://python-all.ru/3.0/library/py_compile.html#module-py_compile), либо косвенно – путём создания временного скрипта и его выполнения. Обычно функция [`byte_compile()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.util.byte_compile) сама определяет, использовать прямую компиляцию или нет (подробнее см. исходный код). Флаг *direct* используется скриптом, создаваемым в косвенном режиме; если вы не уверены в своих действиях, оставьте его равным `None`.11751176#### `[distutils.util.rfc822_escape]distutils.util.rfc822_escape(header)`11771178Возвращает версию11791180*header*11811182с экранированием для включения в заголовок11831184[**RFC 822**](https://python-all.ru/3.0/distutils/apiref.html)11851186, гарантируя наличие 8 пробелов после каждого перевода строки. Обратите внимание, что никаких других изменений строки не производится.11871188## `distutils.dist` – класс Distribution11891190Этот модуль предоставляет класс `Distribution`, который представляет распространяемый модуль (сборку/установку/распространение).11911192## `distutils.extension` – класс Extension11931194Этот модуль предоставляет класс `Extension`, используемый для описания модулей расширения на C/C++ в скриптах установки.11951196## `distutils.debug` – режим отладки Distutils11971198Этот модуль предоставляет флаг DEBUG.11991200## `distutils.errors` – исключения Distutils12011202Предоставляет исключения, используемые модулями Distutils. Обратите внимание, что модули Distutils могут вызывать стандартные исключения; в частности, SystemExit обычно возбуждается для ошибок, которые явно являются виной конечного пользователя (например, неправильные аргументы командной строки).12031204Этот модуль безопасно использовать в режиме `from ... import *`; он экспортирует только символы, чьи имена начинаются с `Distutils` и заканчиваются на `Error`.12051206## `distutils.fancy_getopt` – обёртка для стандартного модуля getopt12071208Этот модуль предоставляет обёртку вокруг стандартного модуля [`getopt`](https://python-all.ru/3.0/library/getopt.html#module-getopt), которая добавляет следующие возможности:12091210- короткие и длинные опции привязаны друг к другу1211- параметры имеют строки справки, так что [`fancy_getopt()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.fancy_getopt) может создавать полную сводку по использованию1212- опции устанавливают атрибуты переданного объекта1213- Логические опции могут иметь «отрицательные псевдонимы» – например, если *--quiet* является «отрицательным псевдонимом» для *--verbose*, то *--quiet* в командной строке устанавливает *verbose* в false.12141215**\*\*** Следует заменить на `optik` (который также известен как [`optparse`](https://python-all.ru/3.0/library/optparse.html#module-optparse) в Python 2.3 и более поздних). **\*\***12161217#### `[distutils.fancy_getopt.fancy_getopt]distutils.fancy_getopt.fancy_getopt(options, negative_opt, object, args)`12181219Функция-обёртка.12201221*options*12221223– это список12241225`(long_option, short_option, help_string)`122612273-кортежей, как описано в конструкторе12281229[`FancyGetopt`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.FancyGetopt)12301231.12321233*negative\_opt*12341235должен быть словарём, сопоставляющим имена опций с именами опций; и ключ, и значение должны присутствовать в списке12361237*options*12381239.12401241*object*12421243– это объект, который будет использоваться для хранения значений (см. метод12441245`getopt()`12461247класса12481249[`FancyGetopt`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.FancyGetopt)12501251).12521253*args*12541255– список аргументов. Если передать12561257`None`12581259в качестве12601261*args*12621263, будет использоваться12641265`sys.argv[1:]`12661267.12681269#### `[distutils.fancy_getopt.wrap_text]distutils.fancy_getopt.wrap_text(text, width)`12701271Переносит *text* до ширины менее *width*.12721273> **Предупреждение**1274>1275> Следует заменить на [`textwrap`](https://python-all.ru/3.0/library/textwrap.html#module-textwrap) (доступен в Python 2.3 и более поздних версиях).12761277#### `[distutils.fancy_getopt.FancyGetopt]class distutils.fancy_getopt.FancyGetopt([option_table=None])`12781279The option\_table is a list of 3-tuples: `(long_option, short_option, help_string)`12801281Если опция принимает аргумент, *long\_option* должно оканчиваться на `'='`; *short\_option* должна быть одним символом, без `':'` в любом случае. *short\_option* должно быть `None`, если *long\_option* не имеет соответствующей *short\_option*. Все кортежи опций должны содержать длинные опции.12821283Класс [`FancyGetopt`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.FancyGetopt) предоставляет следующие методы:12841285#### `[distutils.fancy_getopt.FancyGetopt.getopt]FancyGetopt.getopt([args=None, object=None])`12861287Разбирает параметры командной строки в args. Сохраняет как атрибуты *object*.12881289Если *args* равен `None` или не указан, используется `sys.argv[1:]`. Если *object* равен `None` или не указан, создаётся новый экземпляр `OptionDummy`, в него сохраняются значения опций, и возвращается кортеж `(args, object)`. Если *object* указан, он изменяется на месте, и [`getopt()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.FancyGetopt.getopt) просто возвращает *args*; в обоих случаях возвращаемый *args* – это изменённая копия переданного списка *args*, который остаётся нетронутым.12901291#### `[distutils.fancy_getopt.FancyGetopt.get_option_order]FancyGetopt.get_option_order()`12921293Возвращает список кортежей12941295`(option, value)`12961297, обработанных предыдущим вызовом12981299[`getopt()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.FancyGetopt.getopt)13001301. Вызывает13021303[`RuntimeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.RuntimeError)13041305, если13061307[`getopt()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.FancyGetopt.getopt)13081309ещё не вызывался.13101311#### `[distutils.fancy_getopt.FancyGetopt.generate_help]FancyGetopt.generate_help([header=None])`13121313Генерирует текст справки (список строк, по одной на предполагаемую строку вывода) из таблицы опций для данного объекта [`FancyGetopt`](https://python-all.ru/3.0/distutils/apiref.html#distutils.fancy_getopt.FancyGetopt).13141315Если указан, выводит переданный *header* в начале справки.13161317## `distutils.filelist` – класс FileList13181319Этот модуль предоставляет класс `FileList`, используемый для исследования файловой системы и составления списков файлов.13201321## `distutils.log` – простое журналирование в стиле PEP 28213221323> **Предупреждение**1324>1325> Следует заменить стандартным модулем [`logging`](https://python-all.ru/3.0/library/logging.html#module-logging).13261327## `distutils.spawn` – Запуск подпроцесса13281329Этот модуль предоставляет функцию `spawn()` – интерфейс к различным платформенно-зависимым функциям для запуска другой программы в подпроцессе. Также предоставляет `find_executable()` для поиска заданного исполняемого файла по путям.13301331## `distutils.sysconfig` – Информация о конфигурации системы13321333Модуль `distutils.sysconfig` предоставляет доступ к низкоуровневой информации о конфигурации Python. Доступные переменные конфигурации сильно зависят от платформы и конфигурации. Конкретные переменные зависят от процесса сборки конкретной версии Python; это переменные из `Makefile` и заголовочного файла конфигурации, которые устанавливаются вместе с Python в Unix-системах. Для версий Python начиная с 2.2 заголовочный файл конфигурации называется `pyconfig.h`, а для более ранних версий – `config.h`.13341335Предоставляются некоторые дополнительные функции, выполняющие полезные операции для других частей пакета [`distutils`](https://python-all.ru/3.0/library/distutils.html#module-distutils).13361337#### `[distutils.sysconfig.PREFIX]distutils.sysconfig.PREFIX`13381339Результат13401341`os.path.normpath(sys.prefix)`13421343.13441345#### `[distutils.sysconfig.EXEC_PREFIX]distutils.sysconfig.EXEC_PREFIX`13461347Результат13481349`os.path.normpath(sys.exec_prefix)`13501351.13521353#### `[distutils.sysconfig.get_config_var]distutils.sysconfig.get_config_var(name)`13541355Возвращает значение одной переменной. Эквивалентно13561357`get_config_vars().get(name)`13581359.13601361#### `[distutils.sysconfig.get_config_vars]distutils.sysconfig.get_config_vars(...)`13621363Возвращает набор определений переменных. Если аргументы не переданы, возвращает словарь, отображающий имена переменных конфигурации в их значения. Если переданы аргументы, они должны быть строками, и возвращаемым значением будет последовательность соответствующих значений. Если для данного имени нет соответствующего значения, для этой переменной будет включено13641365`None`13661367.13681369#### `[distutils.sysconfig.get_config_h_filename]distutils.sysconfig.get_config_h_filename()`13701371Возвращает полное имя файла заголовка конфигурации. Для Unix это будет заголовок, сгенерированный сценарием13721373**configure**13741375; для других платформ заголовок поставляется непосредственно с дистрибутивом исходных кодов Python. Этот файл является платформозависимым текстовым файлом.13761377#### `[distutils.sysconfig.get_makefile_filename]distutils.sysconfig.get_makefile_filename()`13781379Возвращает полный путь к13801381`Makefile`13821383, используемому для сборки Python. В Unix это будет файл, сгенерированный сценарием13841385**configure**13861387; на других платформах смысл может отличаться. Файл является платформенно-зависимым текстовым файлом, если он существует. Эта функция полезна только на платформах POSIX.13881389#### `[distutils.sysconfig.get_python_inc]distutils.sysconfig.get_python_inc([plat_specific[, prefix]])`13901391Возвращает каталог для общих или платформозависимых C-заголовочных файлов. Если13921393*plat\_specific*13941395истинно, возвращается каталог платформозависимых заголовков; если ложно или опущено, возвращается каталог платформонезависимых заголовков. Если указан13961397*prefix*13981399, он используется либо как префикс вместо14001401[`PREFIX`](https://python-all.ru/3.0/distutils/apiref.html#distutils.sysconfig.PREFIX)14021403, либо как exec-префикс вместо14041405[`EXEC_PREFIX`](https://python-all.ru/3.0/distutils/apiref.html#distutils.sysconfig.EXEC_PREFIX)14061407, если14081409*plat\_specific*14101411истинно.14121413#### `[distutils.sysconfig.get_python_lib]distutils.sysconfig.get_python_lib([plat_specific[, standard_lib[, prefix]]])`14141415Возвращает каталог для установки общих или платформозависимых библиотек. Если14161417*plat\_specific*14181419истинно, возвращается каталог платформозависимых заголовков; если ложно или опущено, возвращается каталог платформонезависимых заголовков. Если указан14201421*prefix*14221423, он используется либо как префикс вместо14241425[`PREFIX`](https://python-all.ru/3.0/distutils/apiref.html#distutils.sysconfig.PREFIX)14261427, либо как exec-префикс вместо14281429[`EXEC_PREFIX`](https://python-all.ru/3.0/distutils/apiref.html#distutils.sysconfig.EXEC_PREFIX)14301431, если14321433*plat\_specific*14341435истинно. Если14361437*standard\_lib*14381439истинно, возвращается каталог стандартной библиотеки, а не каталог для установки сторонних расширений.14401441Следующая функция предназначена только для использования в пакете [`distutils`](https://python-all.ru/3.0/library/distutils.html#module-distutils).14421443#### `[distutils.sysconfig.customize_compiler]distutils.sysconfig.customize_compiler(compiler)`14441445Выполняет любую платформозависимую настройку экземпляра [`distutils.ccompiler.CCompiler`](https://python-all.ru/3.0/distutils/apiref.html#distutils.ccompiler.CCompiler).14461447В настоящее время эта функция необходима только в Unix, но её следует вызывать последовательно для обеспечения прямой совместимости. Она вставляет информацию, которая различается в разных версиях Unix и хранится в `Makefile` Python. Эта информация включает выбранный компилятор, параметры компилятора и компоновщика, а также расширение, используемое компоновщиком для общих объектов.14481449Эта функция ещё более специализированная и должна использоваться только в процедурах сборки самого Python.14501451#### `[distutils.sysconfig.set_python_build]distutils.sysconfig.set_python_build()`14521453Сообщает модулю14541455`distutils.sysconfig`14561457, что он используется в процессе сборки Python. Это меняет многие относительные пути к файлам, позволяя им находиться в области сборки, а не в установленном Python.14581459## `distutils.text_file` – Класс TextFile14601461Этот модуль предоставляет класс [`TextFile`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile), который предоставляет интерфейс к текстовым файлам, (опционально) обрабатывающий удаление комментариев, игнорирование пустых строк и объединение строк с обратной косой чертой.14621463#### `[distutils.text_file.TextFile]class distutils.text_file.TextFile([filename=None, file=None, **options])`14641465Этот класс предоставляет объект, подобный файлу, который заботится обо всех вещах, которые обычно нужно делать при обработке текстового файла с построчным синтаксисом: удаление комментариев (если `#` является символом комментария), пропуск пустых строк, объединение соседних строк с помощью экранирования перевода строки (т.е. обратная косая черта в конце строки), удаление начальных и/или конечных пробелов. Все эти возможности опциональны и управляются независимо.14661467Класс предоставляет метод [`warn()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.warn), с помощью которого можно генерировать предупреждающие сообщения, содержащие номер физической строки, даже если рассматриваемая логическая строка охватывает несколько физических строк. Также предоставляет [`unreadline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.unreadline) для реализации просмотра вперед по одной строке.14681469Экземпляры [`TextFile`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile) создаются с помощью *filename*, *file* или обоих. Если оба равны `None`, возбуждается [`RuntimeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.RuntimeError). *filename* должна быть строкой, а *file* – файловым объектом (или чем-то, что предоставляет методы [`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline) и [`close()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.close)). Рекомендуется указывать хотя бы *filename*, чтобы [`TextFile`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile) мог включать его в предупреждающие сообщения. Если *file* не указан, [`TextFile`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile) создает свой собственный, используя встроенную функцию [`open()`](https://python-all.ru/3.0/library/functions.html#open).14701471Все параметры имеют булевый тип и влияют на значения, возвращаемые [`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline)14721473| имя параметра | описание | по умолчанию |1474| --- | --- | --- |1475| *strip\_comments* | удалять от `'#'` до конца строки, а также все пробельные символы перед `'#'` – если только они не экранированы обратной косой чертой | истина |1476| *lstrip\_ws* | удаляет начальные пробелы из каждой строки перед её возвратом | ложь |1477| *rstrip\_ws* | Удаляет завершающие пробелы (включая символ конца строки!) из каждой строки перед её возвратом. | истина |1478| *skip\_blanks* | Пропускает строки, которые пусты \*после\* удаления комментариев и пробелов. (Если и lstrip\_ws, и rstrip\_ws равны false, то некоторые строки могут состоять только из пробелов: они \*не\* будут пропущены, даже если *skip\_blanks* равно true.) | истина |1479| *join\_lines* | если обратная косая черта – последний символ (не перевод строки) в строке после удаления комментариев и пробелов, соединить следующую строку с ней, чтобы получить одну логическую строку; если N последовательных строк заканчиваются обратной косой чертой, то N+1 физических строк будут объединены для образования одной логической строки. | ложь |1480| *collapse\_join* | удалять начальные пробелы из строк, которые объединяются с предыдущей; имеет значение только если `(join_lines и не lstrip_ws)` | ложь |14811482Обратите внимание: поскольку *rstrip\_ws* может удалять завершающий символ новой строки, семантика [`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline) должна отличаться от семантики одноимённого метода встроенного файлового объекта [`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline)! В частности, [`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline) возвращает `None` при достижении конца файла: пустая строка может быть просто пустой строкой (или строкой из пробелов), если *rstrip\_ws* равно true, но *skip\_blanks* – нет.14831484#### `[distutils.text_file.TextFile.open]open(filename)`14851486Открывает новый файл14871488*filename*14891490. Это переопределяет любые аргументы конструктора14911492*file*14931494или14951496*filename*14971498.14991500#### `[distutils.text_file.TextFile.close]close()`15011502Закрывает текущий файл и забывает всю информацию о нём (включая имя файла и текущий номер строки).15031504#### `[distutils.text_file.TextFile.warn]warn(msg[, line=None])`15051506Выводит (в stderr) предупреждение, привязанное к текущей логической строке в текущем файле. Если текущая логическая строка в файле охватывает несколько физических строк, предупреждение относится ко всему диапазону, например15071508`"lines 3-5"`15091510. Если указан15111512*line*15131514, он заменяет номер текущей строки; это может быть список или кортеж для указания диапазона физических строк, или целое число для одной физической строки.15151516#### `[distutils.text_file.TextFile.readline]readline()`15171518Читает и возвращает одну логическую строку из текущего файла (или из внутреннего буфера, если строки ранее были «возвращены» с помощью15191520[`unreadline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.unreadline)15211522). Если параметр15231524*join\_lines*15251526равен истине, это может включать чтение нескольких физических строк, объединённых в одну строку. Обновляет номер текущей строки, поэтому вызов15271528[`warn()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.warn)15291530после15311532[`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline)15331534выводит предупреждение о только что прочитанных физических строках. Возвращает15351536`None`15371538при достижении конца файла, поскольку пустая строка может возникнуть, если15391540*rstrip\_ws*15411542равен истине, а15431544*strip\_blanks*15451546– ложь.15471548#### `[distutils.text_file.TextFile.readlines]readlines()`15491550Читает и возвращает список всех логических строк, оставшихся в текущем файле. Это обновляет текущий номер строки до последней строки файла.15511552#### `[distutils.text_file.TextFile.unreadline]unreadline(line)`15531554Помещает15551556*line*15571558(строку) во внутренний буфер, который будет проверяться последующими вызовами15591560[`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline)15611562. Удобно для реализации синтаксического анализатора с просмотром вперёд по одной строке. Обратите внимание, что строки, «возвращённые» с помощью15631564[`unreadline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.unreadline)15651566, впоследствии не очищаются повторно (пробелы не удаляются и т.д.) при чтении через15671568[`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline)15691570. Если до вызова15711572[`readline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.readline)15731574было несколько вызовов15751576[`unreadline()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.text_file.TextFile.unreadline)15771578, строки будут возвращены в порядке от самой последней к самой первой.15791580## `distutils.version` – Классы для номеров версий15811582## `distutils.cmd` – Абстрактный базовый класс для команд Distutils15831584Этот модуль предоставляет абстрактный базовый класс [`Command`](https://python-all.ru/3.0/distutils/apiref.html#distutils.cmd.Command).15851586#### `[distutils.cmd.Command]class distutils.cmd.Command(dist)`15871588Абстрактный базовый класс для определения классов команд – «рабочих пчёл» Distutils. Полезная аналогия: классы команд можно рассматривать как подпрограммы с локальными переменными, называемыми *options*. Параметры объявляются в `initialize_options()` и определяются (получают свои окончательные значения) в `finalize_options()`; оба метода должны быть определены в каждом классе команд. Различие между ними необходимо, потому что значения параметров могут поступать из внешнего мира (командная строка, конфигурационный файл и т.д.), а любые параметры, зависящие от других параметров, должны вычисляться после обработки этих внешних влияний – отсюда `finalize_options()`. Тело подпрограммы, где выполняется вся работа на основе значений параметров, – это метод `run()`, который также должен быть реализован в каждом классе команд.15891590Конструктор класса принимает единственный аргумент *dist* – экземпляр `Distribution`.15911592## `distutils.command` – Отдельные команды Distutils15931594## `distutils.command.bdist` – Сборка двоичного установщика15951596## `distutils.command.bdist_packager` – Абстрактный базовый класс для упаковщиков15971598## `distutils.command.bdist_dumb` – Сборка «тупого» установщика15991600## `distutils.command.bdist_msi` – Сборка двоичного пакета Microsoft Installer16011602## `distutils.command.bdist_rpm` – Сборка двоичного дистрибутива в формате Redhat RPM и SRPM16031604## `distutils.command.bdist_wininst` – Сборка установщика для Windows16051606## `distutils.command.sdist` – Сборка дистрибутива исходного кода16071608## `distutils.command.build` – Сборка всех файлов пакета16091610## `distutils.command.build_clib` – Сборка любых C-библиотек в пакете16111612## `distutils.command.build_ext` – Сборка любых расширений в пакете16131614## `distutils.command.build_py` – Сборка .py/.pyc файлов пакета16151616#### `[distutils.command.build_py.build_py]class distutils.command.build_py.build_py(Command)`16171618#### `[distutils.command.build_py.build_py_2to3]class distutils.command.build_py.build_py_2to3(build_py)`16191620Альтернативная реализация build\_py, которая также запускает библиотеку преобразования 2to3 для каждого .py файла, подлежащего установке. Чтобы использовать это в файле setup.py для дистрибутива, предназначенного для работы с Python 2.x и 3.x, добавьте:16211622```python1623try:1624   from distutils.command.build_py import build_py_2to3 as build_py1625except ImportError:1626   from distutils.command.build_py import build_py1627```16281629в файл setup.py, а затем:16301631```python1632cmdclass = {'build_py':build_py}1633```16341635в вызов setup().16361637## `distutils.command.build_scripts` – Сборка скриптов пакета16381639## `distutils.command.clean` – Очистка области сборки пакета16401641## `distutils.command.config` – Выполнение настройки пакета16421643## `distutils.command.install` – Установка пакета16441645## `distutils.command.install_data` – Установка файлов данных из пакета16461647## `distutils.command.install_headers` – Установка заголовочных файлов C/C++ из пакета16481649## `distutils.command.install_lib` – Установка файлов библиотек из пакета16501651## `distutils.command.install_scripts` – Установка файлов скриптов из пакета16521653## `distutils.command.register` – Регистрация модуля в Python Package Index16541655Команда `register` регистрирует пакет в Python Package Index. Подробнее это описано в [**PEP 301**](https://python-all.ru/3.0/distutils/apiref.html).16561657## Создание новой команды Distutils16581659В этом разделе описываются шаги по созданию новой команды Distutils.16601661Новая команда находится в модуле пакета `distutils.command`. В этом каталоге есть образец шаблона `command_template`. Скопируйте этот файл в новый модуль с тем же именем, что и реализуемая команда. Этот модуль должен реализовать класс с тем же именем, что и модуль (и команда). Так, например, чтобы создать команду `peel_banana` (чтобы пользователи могли запускать `setup.py peel_banana`), нужно скопировать `command_template` в `distutils/command/peel_banana.py`, затем отредактировать его так, чтобы он реализовывал класс `peel_banana`, подкласс [`distutils.cmd.Command`](https://python-all.ru/3.0/distutils/apiref.html#distutils.cmd.Command).16621663Подклассы `Command` должны определять следующие методы.16641665#### `[distutils.command.register.Command.initialize_options]Command.initialize_options()(S)`16661667Устанавливает значения по умолчанию для всех параметров, которые поддерживает эта команда. Обратите внимание, что эти значения по умолчанию могут быть переопределены другими командами, сценарием setup, файлами конфигурации или командной строкой. Поэтому здесь не место для кодирования зависимостей между параметрами; обычно реализации16681669[`initialize_options()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.command.register.Command.initialize_options)16701671представляют собой просто набор присваиваний вида16721673`self.foo = None`16741675.16761677#### `[distutils.command.register.Command.finalize_options]Command.finalize_options()`16781679Устанавливает финальные значения для всех опций, поддерживаемых этой командой. Этот метод всегда вызывается как можно позже, то есть после того, как все назначения опций из командной строки или из других команд были выполнены. Таким образом, это место для кодирования зависимостей опций: если16801681*foo*16821683зависит от16841685*bar*16861687, то можно безопасно установить16881689*foo*16901691из16921693*bar*16941695, пока16961697*foo*16981699сохраняет то же значение, которое было присвоено в17001701[`initialize_options()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.command.register.Command.initialize_options)17021703.17041705#### `[distutils.command.register.Command.run]Command.run()`17061707Смысл существования команды: выполнить действие, для которого она предназначена, управляемое опциями, инициализированными в17081709[`initialize_options()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.command.register.Command.initialize_options)17101711, настроенными другими командами, скриптом установки, командной строкой и файлами конфигурации, и окончательно определёнными в17121713[`finalize_options()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.command.register.Command.finalize_options)17141715. Весь вывод в терминал и взаимодействие с файловой системой должны выполняться в17161717[`run()`](https://python-all.ru/3.0/distutils/apiref.html#distutils.command.register.Command.run)17181719.17201721*sub\_commands* формализует понятие «семейства» команд, например, `install` как родитель с подкомандами `install_lib`, `install_headers` и т.д. Родитель семейства команд определяет *sub\_commands* как атрибут класса; это список 2-кортежей `(command_name, predicate)`, где *command\_name* – строка, а *предикат* – функция, строка или None. *предикат* – это метод родительской команды, который определяет, применима ли соответствующая команда в текущей ситуации. (Например, `install_headers` применима, только если есть заголовочные файлы C для установки.) Если *предикат* равен None, эта команда всегда применима.17221723*sub\_commands* обычно определяется в \*конце\* класса, потому что предикаты могут быть методами класса, поэтому они должны быть уже определены. Канонический пример – команда **install**.1724