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 3147PEP 488 path, заканчивающийся на .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. Это служит предупреждением о том, что импорт преобразует эти пути в обычные файлы, если разрешено записывать в них файлы, скомпилированные по байтам. Это побочный эффект импорта, использующего переименование файлов для размещения конечного файла, скомпилированного по байтам, на место, чтобы предотвратить проблемы с одновременной записью файлов.

оптимизировать управляет уровнем оптимизации и передается встроенной функции compile(). Значение по умолчанию -1 определяет уровень оптимизации текущего интерпретатора.

invalidation_mode должен быть членом перечисления PycInvalidationMode и управляет тем, как сгенерированный кэш байт-кода становится недействительным во время выполнения. Значение по умолчанию равно PycInvalidationMode.CHECKED_HASH, если задана переменная окружения SOURCE_DATE_EPOCH, в противном случае значение по умолчанию равно PycInvalidationMode.TIMESTAMP.

Изменено в версии 3.2: Изменено значение по умолчанию для cfile, чтобы оно соответствовало PEP 3147. Предыдущее значение по умолчанию было file + 'c' ('o' если была включена оптимизация). Также добавлен параметр оптимизировать.

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