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 имеет значение true, при обнаружении ошибки во время компиляции file возбуждается исключение PyCompileError. Если 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 является символической ссылкой или обычным файлом.

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