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

Исходный код: Lib/py_compile.py

Модуль 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 ложь (по умолчанию), строка ошибки записывается в sys.stderr, но исключение не генерируется. Эта функция возвращает путь к скомпилированному файлу байткода, т. е. значение cfile, которое было использовано.

Аргументы doraise и quiet определяют, как обрабатываются ошибки во время компиляции файла. Если quiet равно 0 или 1, а doraise ложь, то включено поведение по умолчанию: строка ошибки записывается в sys.stderr, а функция возвращает None вместо пути. Если doraise истина, возникает 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 является символьным ссылкой или не является обычным файлом.

Изменено в версии 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, например, системой сборки.