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)

Компилирует исходный файл в байткод и записывает файл кеша байткода. Исходный код загружается из файла с именем 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.

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

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

py_compile.main(args=None)

Компилирует несколько исходных файлов. Файлы, перечисленные в args (или в командной строке, если args — None), компилируются, и полученный байткод кешируется обычным способом. Эта функция не ищет структуру каталогов для поиска исходных файлов; она компилирует только явно указанные файлы. Если '-' является единственным параметром в args, список файлов берётся из стандартного ввода.

Изменено в версии 3.2: Добавлена поддержка '-'.

При запуске этого модуля в качестве скрипта используется функция main() для компиляции всех файлов, указанных в командной строке. Код завершается с ненулевым статусом, если один из файлов не удалось скомпилировать.