11. Справочник API¶API Reference

11.1. distutils.core – Основная функциональность Distutils¶distutils.core – Core Distutils functionality

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

distutils.core.setup(arguments)¶

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

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

имя аргумента	значение	тип
имя	Название пакета	строка
версия	Номер версии пакета	См. distutils.version
описание	Краткое описание пакета (одна строка)	строка
long_description	Подробное описание пакета	строка
author	Имя автора пакета	строка
author_email	Адрес электронной почты автора пакета	строка
maintainer	Имя текущего мейнтейнера, если оно отличается от автора	строка
maintainer_email	Адрес электронной почты текущего сопровождающего, если он отличается от автора
url	URL пакета (домашняя страница)	URL
download_url	URL для загрузки пакета	URL
packages	Список пакетов Python, которыми будет управлять distutils	список строк
py_modules	Список модулей Python, которыми будет управлять distutils	список строк
сценарии	Список отдельных файлов скриптов, которые нужно собрать и установить	список строк
ext_modules	Список расширений Python, которые необходимо собрать	Список экземпляров distutils.core.Extension
classifiers	Список категорий для пакета	Список доступных категорий находится по адресу http://pypi.python.org/pypi?:action=list_classifiers.
distclass	класс Distribution для использования	Подкласс distutils.core.Distribution
script_name	Имя скрипта setup.py – по умолчанию sys.argv[0]	строка
script_args	Аргументы, передаваемые скрипту setup	список строк
опции	параметры по умолчанию для скрипта setup	строка
лицензия	Лицензия пакета	строка
keywords	Описательные метаданные, см. PEP 314
platforms
cmdclass	Сопоставление имён команд с подклассами Command	словарь
data_files	Список файлов данных для установки	список
package_dir	Сопоставление пакетов и имён каталогов	словарь

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

Запускает сценарий установки в частично контролируемом окружении и возвращает экземпляр 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++ в скрипте setup. Его конструктор принимает следующие именованные аргументы.

имя аргумента	значение	тип
имя	полное имя расширения, включая любые пакеты – то есть не имя файла или путь, а точечное имя Python	строка
sources	список имён исходных файлов, относительно корня дистрибутива, корень (где setup-скрипт находится), в Unix-формате (косая черта) для переносимости. Исходные файлы могут быть на C, C++, SWIG (.i), платформенно-зависимые файлы ресурсов или что-либо ещё распознаётся командой build_ext как исходный код для расширения Python.	строка
include_dirs	список каталогов для поиска файлов заголовков C/C++ (в формате Unix для переносимости)	строка
define_macros	список макросов для определения; каждый макрос определяется с помощью кортежа из двух элементов (name, value), где value – это либо строка для определения значения, либо None для определения без конкретного значения (эквивалент #define FOO в исходном коде или -DFOO в командной строке C компилятора Unix)	(string, string) кортеж или (имя, None)
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 + extension_name.	строка
зависит	список файлов, от которых зависит расширение	строка
язык	язык расширения (т.е. 'c', 'c++', 'objc'). Будет определён по расширениям исходных файлов, если не указан.	строка

class distutils.core.Distribution¶

Distribution описывает, как собрать, установить и упаковать программный пакет Python.

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

class distutils.core.Command¶

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

11.2. distutils.ccompiler – базовый класс CCompiler¶distutils.ccompiler – CCompiler base class

Этот модуль предоставляет абстрактный базовый класс для классов 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().

The following methods allow you to manually alter compiler options for the instance of the Compiler class.

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

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

Компоновщику будет указано компоновать с библиотеками в том порядке, в котором они были переданы в add_library() и/или set_libraries(). Дублирование имён библиотек вполне допустимо; компоновщику будет указано компоновать с библиотеками столько раз, сколько они упомянуты.

set_libraries(libnames)¶

Set the list of libraries to be included in all links driven by this compiler object to libnames (a list of strings). This does not affect any standard system libraries that the linker may include by default.

add_library_dir(dir)¶

Добавляет dir в список каталогов, в которых будет выполняться поиск библиотек, указанных в add_library() и set_libraries(). Компоновщику будет указано искать библиотеки в том порядке, в котором они передаются в add_library_dir() и/или set_library_dirs().

set_library_dirs(dirs)¶

Set the list of library search directories to dirs (a list of strings). This does not affect any standard library search path that the linker may search by default.

add_runtime_library_dir(dir)¶

Add dir to the list of directories that will be searched for shared libraries at runtime.

set_runtime_library_dirs(dirs)¶

Set the list of directories to search for shared libraries at runtime to dirs (a list of strings). This does not affect any standard search path that the runtime linker may search by default.

define_macro(name[, value=None])¶

Определяет макрос препроцессора для всех компиляций, управляемых данным объектом компилятора. Необязательный параметр value должен быть строкой; если он не указан, макрос будет определён без явного значения, и точный результат зависит от используемого компилятора (XXX верно? говорит ли ANSI что-нибудь об этом?)

undefine_macro(name)¶

Отменяет макрос препроцессора для всех компиляций, выполняемых данным объектом компилятора. Если один и тот же макрос определён с помощью define_macro() и отменён с помощью undefine_macro(), последний вызов имеет приоритет (включая множественные переопределения или отмены). Если макрос переопределяется/отменяется для конкретной компиляции (т.е. в вызове compile()), то приоритет у этого действия.

add_link_object(object)¶

Add object to 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.

set_link_objects(objects)¶

Set the list of object files (or analogues) to be included in every link to objects. This does not affect any standard object files that the linker may include by default (such as system libraries).

Следующие методы реализуют автодетекцию параметров компилятора, предоставляя функциональность, аналогичную GNU autoconf.

detect_language(sources)¶

Определяет язык указанного файла или списка файлов. Для этого используются атрибуты экземпляра language_map (словарь) и language_order (список).

find_library_file(dirs, lib[, debug=0])¶

Ищет в указанном списке каталогов файл статической или динамической библиотеки lib и возвращает полный путь к этому файлу. Если debug истинно, ищет отладочную версию (если это имеет смысл на текущей платформе). Возвращает None, если lib не найден ни в одном из указанных каталогов.

has_function(funcname[, includes=None, include_dirs=None, libraries=None, library_dirs=None])¶

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

library_dir_option(dir)¶

Возвращает опцию компилятора для добавления dir в список каталогов, в которых выполняется поиск библиотек.

library_option(lib)¶

Возвращает параметр компилятора для добавления dir в список библиотек, подключаемых к общей библиотеке или исполняемому файлу.

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), либо кортеж из одного элемента (name,). Первый случай определяет макрос; если значение равно None, макрос определяется без явного значения. Кортеж из одного элемента отменяет макрос. Последующие определения/переопределения/отмены имеют приоритет.

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 – это каталог, в который будет помещён файл библиотеки. XXX значение по умолчанию?

debug – логическое значение; если истинно, в библиотеку будет включена отладочная информация (обратите внимание: на большинстве платформ значение имеет этап компиляции; флаг debug добавлен здесь лишь для единообразия).

target_lang – целевой язык, для которого компилируются указанные объекты. Это позволяет выполнять специальную обработку на этапе компоновки для некоторых языков.

В случае ошибки вызывает LibError.

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

Связывает всё вместе, чтобы создать исполняемый файл или файл динамической библиотеки.

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

libraries – это список библиотек для линковки. Это имена библиотек, а не имена файлов, так как они преобразуются в имена файлов платформо-зависимым способом (например, foo становится libfoo.a на Unix и foo.lib на DOS/Windows). Однако они могут содержать компонент каталога, что означает, что линковщик будет искать в этом конкретном каталоге, а не во всех обычных местах.

library_dirs, если указано, должно быть списком каталогов для поиска библиотек, заданных как простые имена (без компонента каталога). Они добавляются к системным по умолчанию и тем, что указаны в add_library_dir() и/или set_library_dirs(). runtime_library_dirs – это список каталогов, которые будут встроены в разделяемую библиотеку и использоваться для поиска других разделяемых библиотек, от которых она зависит во время выполнения. (Это может быть актуально только на Unix.)

export_symbols – список символов, которые будет экспортировать динамическая библиотека. (Это актуально, по-видимому, только в Windows.)

debug работает так же, как и в compile() и create_static_lib(), с тем небольшим отличием, что на большинстве платформ это действительно важно (в отличие от create_static_lib(), которая включает флаг debug в основном для проформы).

extra_preargs и extra_postargs аналогичны параметрам compile() (за исключением, конечно, того, что они передают аргументы командной строки для конкретного используемого компоновщика).

target_lang – целевой язык, для которого компилируются указанные объекты. Это позволяет выполнять специальную обработку на этапе компоновки для некоторых языков.

При неудаче вызывает LinkError.

link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])¶

Компоновка исполняемого файла. output_progname – это имя файла исполняемого файла, а objects – список имён объектных файлов для компоновки. Остальные аргументы аналогичны аргументам метода link().

link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])¶

Компоновка разделяемой библиотеки. output_libname – это имя выходной библиотеки, а objects – список имён объектных файлов для компоновки. Остальные аргументы аналогичны аргументам метода link().

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

Компоновка разделяемого объекта. output_filename – это имя создаваемого разделяемого объекта, а objects – список имён объектных файлов для компоновки. Остальные аргументы аналогичны аргументам метода link().

preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])¶

Препроцессинг одного файла исходного кода на C/C++, указанного в source. Результат будет записан в файл с именем output_file, или в stdout, если output_file не указан. macros – это список определений макросов, как в compile(), который дополнит макросы, заданные с помощью define_macro() и undefine_macro(). include_dirs – это список имён каталогов, которые будут добавлены к списку по умолчанию, так же как и в add_include_dir().

При неудаче вызывает PreprocessError.

Следующие вспомогательные методы определены в классе CCompiler для использования конкретными подклассами.

executable_filename(basename[, strip_dir=0, output_dir=''])¶

Возвращает имя файла исполняемого файла для заданного basename. Обычно на платформах, отличных от Windows, это то же самое, что и базовое имя, а в Windows будет добавлено .exe.

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

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

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

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

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

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

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

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

spawn(cmd)¶

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

mkpath(name[, mode=511])¶

Вызывает distutils.dir_util.mkpath(). Создаёт каталог и все недостающие родительские каталоги. XXX см. также.

move_file(src, dst)¶

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

announce(msg[, level=1])¶

Записывает сообщение через distutils.log.debug(). XXX см. также.

warn(msg)¶

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

debug_print(msg)¶

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

11.3. distutils.unixccompiler – компилятор C для Unix¶distutils.unixccompiler – Unix C Compiler

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

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

11.4. distutils.msvccompiler – компилятор Microsoft¶distutils.msvccompiler – Microsoft Compiler

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

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

11.5. distutils.bcppcompiler – компилятор Borland¶distutils.bcppcompiler – Borland Compiler

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

11.6. distutils.cygwincompiler – компилятор Cygwin¶distutils.cygwincompiler – Cygwin Compiler

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

11.7. distutils.emxccompiler – компилятор OS/2 EMX¶distutils.emxccompiler – OS/2 EMX Compiler

Этот модуль предоставляет класс EMXCCompiler, подкласс UnixCCompiler, который обеспечивает порт EMX компилятора GNU C для OS/2.

11.8. distutils.archive_util – утилиты архивирования¶distutils.archive_util – Archiving utilities

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

distutils.archive_util.make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])¶

Создаёт архивный файл (например, zip или tar). base_name – это имя создаваемого файла без расширения, зависящего от формата; format – формат архива: один из zip, tar, ztar или gztar. root_dir – каталог, который будет корневым каталогом архива; то есть обычно мы выполняем chdir в root_dir перед созданием архива. base_dir – каталог, с которого начинается архивация; то есть base_dir будет общим префиксом всех файлов и каталогов в архиве. root_dir и base_dir по умолчанию равны текущему каталогу. Возвращает имя файла архива.

distutils.archive_util.make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])¶

Создаёт (возможно, сжатый) архив в виде tar-файла из всех файлов в base_dir и всех его подкаталогах. compress должен быть 'gzip' (по умолчанию), 'compress', 'bzip2' или None. И tar, и утилита сжатия, указанная в compress, должны быть доступны в стандартном пути поиска программ, поэтому это, вероятно, специфично для Unix. Выходной tar-файл будет назван base_dir.tar, возможно с добавлением соответствующего расширения сжатия (.gz, .bz2 или .Z). Возвращает имя выходного файла.

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-файла.

11.9. distutils.dep_util – проверка зависимостей¶distutils.dep_util – Dependency checking

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

distutils.dep_util.newer(source, target)¶

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

distutils.dep_util.newer_pairwise(sources, targets)¶

Обходит два списка имён файлов параллельно, проверяя, является ли каждый исходный файл новее соответствующего целевого. Возвращает пару списков (sources, targets), где исходный файл новее целевого, согласно семантике newer()

distutils.dep_util.newer_group(sources, target[, missing='error'])¶

Возвращает истину, если target устарел относительно любого файла из списка sources. Другими словами, если target существует и новее каждого файла из sources, возвращает ложь; в противном случае возвращает истину. missing управляет тем, что делать, если исходный файл отсутствует; значение по умолчанию ('error') – завершиться с ошибкой OSError изнутри os.stat(); если это 'ignore', мы молча пропускаем отсутствующие исходные файлы; если это 'newer', то любой отсутствующий исходный файл заставляет считать, что target устарел (это удобно в режиме «сухого прогона»: он заставит имитировать выполнение команд, которые не сработают из-за отсутствия входных данных, но это не имеет значения, так как команды на самом деле не выполняются).

11.10. distutils.dir_util – операции с деревом каталогов¶distutils.dir_util – Directory tree operations

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

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

Создаёт каталог и все отсутствующие родительские каталоги. Если каталог уже существует (или name – пустая строка, означающая текущий каталог, который, разумеется, существует), то ничего не делает. Возбуждает DistutilsFileError, если не удаётся создать какой-либо каталог по пути (например, существует вложенный путь, но это файл, а не каталог). Если verbose имеет значение true, выводит в stdout по одной строке-сводке для каждого 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 такие же, как в copy_file() из distutils.file_util; они применяются только к обычным файлам, не к каталогам. Если preserve_symlinks равен true, символические ссылки копируются как символические ссылки (на платформах, которые их поддерживают!); иначе (по умолчанию) копируется объект, на который указывает ссылка. update и verbose такие же, как в copy_file().

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

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

11.11. distutils.file_util – операции с отдельными файлами¶distutils.file_util – Single file operations

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

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 (последовательность строк без символов конца строки).

11.12. distutils.util – Разные прочие служебные функции¶distutils.util – Miscellaneous other utility functions

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

distutils.util.get_platform()¶

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

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

• linux-i586
• linux-alpha
• solaris-2.6-sun4u
• irix-5.3
• irix64-6.2

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

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

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

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

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

distutils.util.convert_path(pathname)¶

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

distutils.util.change_root(new_root, pathname)¶

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

distutils.util.check_environ()¶

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

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

distutils.util.subst_vars(s, local_vars)¶

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

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

distutils.util.grok_environment_error(exc[, prefix='error: '])¶

Формирует полезное сообщение об ошибке из объекта исключения EnvironmentError (IOError или OSError). Поддерживает стили Python 1.5.1 и новее, и делает всё возможное для обработки объектов исключений, у которых нет имени файла (это происходит, когда ошибка связана с операцией над двумя файлами, например, rename() или link()). Возвращает сообщение об ошибке в виде строки с префиксом prefix.

distutils.util.split_quoted(s)¶

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

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

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

distutils.util.strtobool(val)¶

Преобразует строковое представление истинности в true (1) или false (0).

Истинные значения: y, yes, t, true, on и 1; ложные значения: n, no, f, false, off и 0. Вызывает ValueError, если val – что-то другое.

distutils.util.byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])¶

Компилирует набор исходных файлов Python в байт-код, создавая файлы .pyc или .pyo в том же каталоге. py_files – это список файлов для компиляции; любые файлы, не оканчивающиеся на .py, молча пропускаются. optimize должен быть одним из следующих значений:

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

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

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

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

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

distutils.util.rfc822_escape(header)¶

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

11.13. distutils.dist – Класс Distribution¶distutils.dist – The Distribution class

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

11.14. distutils.extension – Класс Extension¶distutils.extension – The Extension class

Этот модуль предоставляет класс Extension, используемый для описания модулей расширения на C/C++ в скриптах установки.

11.15. distutils.debug – Режим отладки Distutils¶distutils.debug – Distutils debug mode

Этот модуль предоставляет флаг DEBUG.

11.16. distutils.errors – Исключения Distutils¶distutils.errors – Distutils exceptions

Предоставляет исключения, используемые модулями Distutils. Обратите внимание, что модули Distutils могут вызывать стандартные исключения; в частности, SystemExit обычно возбуждается для ошибок, которые явно являются виной конечного пользователя (например, неправильные аргументы командной строки).

Этот модуль безопасно использовать в режиме from ... import *; он экспортирует только символы, чьи имена начинаются с Distutils и заканчиваются на Error.

11.17. distutils.fancy_getopt – Обёртка над стандартным модулем getopt¶distutils.fancy_getopt – Wrapper around the standard getopt module

Этот модуль предоставляет обёртку вокруг стандартного модуля getopt, которая добавляет следующие возможности:

• короткие и длинные опции привязаны друг к другу
• параметры имеют строки справки, так что fancy_getopt() может создавать полную сводку по использованию
• опции устанавливают атрибуты переданного объекта
• Логические опции могут иметь «отрицательные псевдонимы» – например, если --quiet является «отрицательным псевдонимом» для --verbose, то --quiet в командной строке устанавливает verbose в false.

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

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

distutils.fancy_getopt.wrap_text(text, width)¶

Переносит text до ширины менее width.

class distutils.fancy_getopt.FancyGetopt([option_table=None])¶

The option_table is a list of 3-tuples: (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 в начале справки.

11.18. distutils.filelist – Класс FileList¶distutils.filelist – The FileList class

Этот модуль предоставляет класс FileList, используемый для исследования файловой системы и составления списков файлов.

11.19. distutils.log – Простое журналирование в стиле PEP 282¶distutils.log – Simple PEP 282-style logging

11.20. distutils.spawn – Порождение подпроцесса¶distutils.spawn – Spawn a sub-process

Этот модуль предоставляет функцию spawn() – интерфейс к различным платформенно-зависимым функциям для запуска другой программы в подпроцессе. Также предоставляет find_executable() для поиска заданного исполняемого файла по путям.

11.21. distutils.sysconfig – Информация о системной конфигурации¶distutils.sysconfig – System configuration information

Модуль distutils.sysconfig предоставляет доступ к низкоуровневой информации о конфигурации Python. Доступные переменные конфигурации сильно зависят от платформы и конфигурации. Конкретные переменные зависят от процесса сборки конкретной версии Python; это переменные из Makefile и заголовочного файла конфигурации, которые устанавливаются вместе с Python в Unix-системах. Для версий Python начиная с 2.2 заголовочный файл конфигурации называется pyconfig.h, а для более ранних версий – config.h.

Предоставляются некоторые дополнительные функции, выполняющие полезные операции для других частей пакета distutils.

distutils.sysconfig.PREFIX¶

Результат os.path.normpath(sys.prefix).

distutils.sysconfig.EXEC_PREFIX¶

Результат os.path.normpath(sys.exec_prefix).

distutils.sysconfig.get_config_var(name)¶

Возвращает значение одной переменной. Эквивалентно get_config_vars().get(name).

distutils.sysconfig.get_config_vars(...)¶

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

distutils.sysconfig.get_config_h_filename()¶

Возвращает полное имя файла заголовка конфигурации. Для Unix это будет заголовок, сгенерированный сценарием configure; для других платформ заголовок поставляется непосредственно с дистрибутивом исходных кодов Python. Этот файл является платформозависимым текстовым файлом.

distutils.sysconfig.get_makefile_filename()¶

Возвращает полный путь к Makefile, используемому для сборки Python. В Unix это будет файл, сгенерированный сценарием configure; на других платформах смысл может отличаться. Файл является платформенно-зависимым текстовым файлом, если он существует. Эта функция полезна только на платформах POSIX.

distutils.sysconfig.get_python_inc([plat_specific[, prefix]])¶

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

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

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

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

distutils.sysconfig.customize_compiler(compiler)¶

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

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

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

distutils.sysconfig.set_python_build()¶

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

11.22. distutils.text_file – Класс TextFile¶distutils.text_file – The TextFile class

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

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

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

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

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

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

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

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

open(filename)¶

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

close()¶

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

warn(msg[, line=None])¶

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

readline()¶

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

readlines()¶

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

unreadline(line)¶

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

11.23. distutils.version – Классы номеров версий¶distutils.version – Version number classes

11.24. distutils.cmd – Абстрактный базовый класс для команд Distutils¶distutils.cmd – Abstract base class for Distutils commands

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

class distutils.cmd.Command(dist)¶

Абстрактный базовый класс для определения классов команд – «рабочих пчёл» Distutils. Полезная аналогия для классов команд – рассматривать их как подпрограммы с локальными переменными, называемыми options. Опции объявляются в initialize_options() и определяются (получают свои окончательные значения) в finalize_options(), причём оба метода должны быть определены в каждом классе команды. Различие между ними необходимо, потому что значения опций могут поступать из внешнего мира (командная строка, файл конфигурации и т.д.), и любые опции, зависящие от других опций, должны вычисляться после обработки этих внешних воздействий – отсюда finalize_options(). Тело подпрограммы, где выполняется вся работа на основе значений опций, – это метод run(), который также должен быть реализован в каждом классе команды.

Конструктор класса принимает единственный аргумент dist – экземпляр Distribution .

11.25. Создание новой команды Distutils¶Creating a new Distutils command

В этом разделе описываются шаги по созданию новой команды 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()¶

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

Command.finalize_options()¶

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

Command.run()¶

Смысл существования команды: выполнить действие, для которого она предназначена, управляемое опциями, инициализированными в initialize_options(), настроенными другими командами, скриптом установки, командной строкой и файлами конфигурации, и окончательно определёнными в 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.

11.26. distutils.command – Отдельные команды Distutils¶distutils.command – Individual Distutils commands

11.27. distutils.command.bdist – Сборка двоичного установщика¶distutils.command.bdist – Build a binary installer

11.28. distutils.command.bdist_packager – Абстрактный базовый класс для упаковщиков¶distutils.command.bdist_packager – Abstract base class for packagers

11.29. distutils.command.bdist_dumb – Сборка «тупого» установщика¶distutils.command.bdist_dumb – Build a “dumb” installer

11.30. distutils.command.bdist_msi – Сборка двоичного пакета Microsoft Installer¶distutils.command.bdist_msi – Build a Microsoft Installer binary package

class distutils.command.bdist_msi.bdist_msi(Command)¶

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

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

11.31. distutils.command.bdist_rpm – Сборка двоичного дистрибутива в виде Redhat RPM и SRPM¶distutils.command.bdist_rpm – Build a binary distribution as a Redhat RPM and SRPM

11.32. distutils.command.bdist_wininst – Сборка установщика для Windows¶distutils.command.bdist_wininst – Build a Windows installer

11.33. distutils.command.sdist – Сборка дистрибутива исходного кода¶distutils.command.sdist – Build a source distribution

11.34. distutils.command.build – Сборка всех файлов пакета¶distutils.command.build – Build all files of a package

11.35. distutils.command.build_clib – Сборка библиотек C в пакете¶distutils.command.build_clib – Build any C libraries in a package

11.36. distutils.command.build_ext – Сборка расширений в пакете¶distutils.command.build_ext – Build any extensions in a package

11.37. distutils.command.build_py – Сборка файлов .py/.pyc пакета¶distutils.command.build_py – Build the .py/.pyc files of a package

class distutils.command.build_py.build_py(Command)¶

class distutils.command.build_py.build_py_2to3(build_py)¶

Альтернативная реализация 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().

11.38. distutils.command.build_scripts – Сборка скриптов пакета¶distutils.command.build_scripts – Build the scripts of a package

11.39. distutils.command.clean – Очистка области сборки пакета¶distutils.command.clean – Clean a package build area

11.40. distutils.command.config – Выполнение конфигурации пакета¶distutils.command.config – Perform package configuration

11.41. distutils.command.install – Установка пакета¶distutils.command.install – Install a package

11.42. distutils.command.install_data – Установка файлов данных из пакета¶distutils.command.install_data – Install data files from a package

11.43. distutils.command.install_headers – Установка заголовочных файлов C/C++ из пакета¶distutils.command.install_headers – Install C/C++ header files from a package

11.44. distutils.command.install_lib – Установка файлов библиотек из пакета¶distutils.command.install_lib – Install library files from a package

11.45. distutils.command.install_scripts – Установка файлов скриптов из пакета¶distutils.command.install_scripts – Install script files from a package

11.46. distutils.command.register – Регистрация модуля в Python Package Index¶distutils.command.register – Register a module with the Python Package Index

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

11.47. distutils.command.check – Проверка метаданных пакета¶distutils.command.check – Check the meta-data of a package

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