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