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 ложен, то включается поведение по умолчанию: строка ошибки записывается в 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 системой, например, системой сборки.