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 истинно, возникает PyCompileError, когда при компиляции file возникает ошибка. Если doraise ложно (по умолчанию), строка ошибки записывается в sys.stderr, но исключение не генерируется. Эта функция возвращает путь к скомпилированному байткоду, то есть значение, которое было использовано для cfile.

Аргументы doraise и quiet определяют, как обрабатываются ошибки во время компиляции файла. Если quiet равно 0 или 1, а doraise ложно, активируется поведение по умолчанию: строка ошибки записывается в sys.stderr, и функция возвращает None вместо пути. Если doraise истинно, вместо этого генерируется 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() для компиляции всех файлов, указанных в командной строке. Код завершается с ненулевым статусом, если один из файлов не удалось скомпилировать.