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