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