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 и определяет, как во время выполнения программы проверяется актуальность созданного кэша байт-кода. Если задана переменная окружения SOURCE_DATE_EPOCH, по умолчанию используется PycInvalidationMode.CHECKED_HASH; в противном случае используется 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, например системой сборки.