py_compile – Компиляция исходных файлов Python¶py_compile – Compile Python source files

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