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

py_compile.main(args=None)

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

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

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