py_compile — Компиляция исходных файлов Python

Модуль py_compile предоставляет функцию для генерации файла байт-кода из исходного файла и другую используемую функцию, когда исходный файл модуля вызывается в качестве сценария.

Хотя он не часто необходим, он может быть полезен, устанавливая модули для общего использования, особенно если у некоторых пользователей может не быть разрешения написать байт-код файлы кэш в справочнике, содержащем исходный код.

exception py_compile.PyCompileError

Исключение при возникновении ошибки при попытке компиляции файла.

py_compile.compile(file, cfile=None, dfile=None, doraise=False, optimize=-1, invalidation_mode=PycInvalidationMode.TIMESTAMP, quiet=0)

Скомпилировать исходный файл в байт-код и записать файл кэша байт-кода. Исходный код загружается из файла с именем file. Байт-код записывается в cfile, который по умолчанию соответствует пути PEP 3147 / PEP 488, оканчивающемуся на .pyc. Например, если file — это /foo/bar/baz.py, cfile по умолчанию будет /foo/bar/__pycache__/baz.cpython-32.pyc для Python 3.2. Если указано dfile, оно используется как имя исходного файла в сообщениях об ошибках вместо file. Если doraise истинно, PyCompileError возникает при обнаружении ошибки при компиляции file. Если doraise имеет значение false (по умолчанию), строка ошибки записывается в sys.stderr, но исключение не возникает. Функция возвращает путь к файлу с байтовой компиляцией, т.е. какое бы значение cfile ни использовалось.

Аргументы doraise и quiet определяют способ обработки ошибок при компиляции файла. Если quiet равно 0 или 1, а doraise равно false, то включается поведение по умолчанию: ошибка строка записывается в sys.stderr, а функция возвращает None вместо пути. Если doraise имеет значение true, вместо него возникает PyCompileError. Однако, если quiet равно 2, сообщение не записывается, и doraise не имеет эффекта.

Если путь, которым становится cfile (или явно определенный или вычисленный) будет симлинк или необычный файл, то будет вызвано FileExistsError. Это должно быть предупреждением, что импорт превратит эти пути в обычные файлы, если разрешено записывать скомпилированные байтами файлы в эти пути. Это побочный эффект импорта с использованием переименования файлов, чтобы поместить на место последний скомпилированный в байтах файл, чтобы предотвратить одновременные проблемы записи файлов.

optimize управляет уровнем оптимизации и передается встроенной функции compile(). По умолчанию для параметра -1 выбирается уровень оптимизации текущего интерпретатора.

invalidation_mode должен быть членом перечисления PycInvalidationMode и управляет тем, как сгенерированный байт-код кэш считается недействительным во время выполнения. Значение по умолчанию равно PycInvalidationMode.CHECKED_HASH, если установлена переменная среды SOURCE_DATE_EPOCH, в противном случае значение по умолчанию равно PycInvalidationMode.TIMESTAMP.

Изменено в версии 3.2: Измененный по умолчанию значение cfile, чтобы быть PEP 3147-соответствующим. Предыдущее значение по умолчанию: file + 'c' ('o' если была включена оптимизация). Также добавлен параметр optimize.

Изменено в версии 3.4: Изменено код для использования importlib для записи файла байт-код кэш. Это означает, что семантика создания/записи файлов теперь соответствует тому, что делает importlib, например, разрешения, семантика записи и перемещения и т.д. Также добавлена оговорка, что FileExistsError возникает, если cfile является symlink или нерегулярным файлом.

Изменено в версии 3.7: Параметр invalidation_mode добавлен, как указано в разделе PEP 552. Если переменная окружения SOURCE_DATE_EPOCH будет установлена, то invalidation_mode будет вызван к PycInvalidationMode.CHECKED_HASH.

Изменено в версии 3.7.2: Переменная окружения SOURCE_DATE_EPOCH больше не отвергает значение аргумента invalidation_mode и определяет его по умолчанию значение вместо этого.

Изменено в версии 3.8: Добавлен параметр quiet.

class py_compile.PycInvalidationMode

Перечисление возможных методов, которые интерпретатор может использовать для определения того, является ли файл байт-кода актуальным для исходного файла. Файл .pyc указывает требуемый режим недействительности в заголовке. Дополнительные сведения о том, как Инвалидация кэша байткода делает файлы Python недействительными во время выполнения, см. в разделе .pyc.

Добавлено в версии 3.7.

TIMESTAMP

Файл .pyc включает метку времени и размер исходного файла, который Python сравнит с метаданными исходного файла во времени выполнения, чтобы определить, должен ли файл .pyc быть восстановлен.

CHECKED_HASH

Файл .pyc включает мешанину содержания исходного файла, которое Python сравнит с источником во времени выполнения, чтобы определить, должен ли файл .pyc быть восстановлен.

UNCHECKED_HASH

Как и CHECKED_HASH, файл .pyc включает в себя хэш содержимого исходного файла. Однако во время выполнения программы Python будет предполагать, что файл .pyc обновлен и вообще не проверяет .pyc на соответствие исходному файлу.

Этот выбор полезен, когда .pycs усовершенствованы некоторой системой, внешней к Python как построить система.

py_compile.main(args=None)

Скомпилировать несколько исходных файлов. Файлы назвали в args (или на командной строке, если args - None), собраны, и получающийся байт-код припрятался про запас нормальным способом. Функция не выполняет поиск исходных файлов в структуре каталогов; он компилирует только файлы, именованные явно. Если '-' является единственным параметром в args, список файлов берется из стандартного ввода.

Изменено в версии 3.2: Добавлена поддержка '-'.

Когда этим модулем управляют как сценарий, main() - используемый, чтобы собрать все файлы, названные на командной строке. Состояние выхода ненулевое, если один из файлов не удалось скомпилировать.

См.также

Модуль compileall
Утилиты для компиляции всех исходных файлов Python в дереве каталогов.