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