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
файлы во время выполнения.Added in version 3.7.
- TIMESTAMP¶
Файл
.pyc
содержит временную метку и размер исходного файла, которые Python будет сравнивать с метаданными исходного файла во время выполнения, чтобы определить, нужно ли регенерировать файл.pyc
.
- CHECKED_HASH¶
Файл
.pyc
содержит хэш содержимого исходного файла, который Python будет сравнивать с исходным текстом во время выполнения, чтобы определить, нужно ли регенерировать файл.pyc
.
- UNCHECKED_HASH¶
Как и
CHECKED_HASH
, файл.pyc
содержит хэш содержимого исходного файла. Однако во время выполнения Python будет считать, что файл.pyc
актуален, и не будет проверять.pyc
на соответствие исходному файлу.Эта опция полезна, когда
.pycs
поддерживается в актуальном состоянии какой-либо внешней по отношению к Python системой, например, системой сборки.
Интерфейс командной строки¶
Этот модуль может быть вызван как сценарий для компиляции нескольких исходных файлов. Файлы, названные в filenames, компилируются, а полученный байткод кэшируется обычным образом. Эта программа не ищет исходные файлы в структуре каталогов; она компилирует только файлы с явными именами. Если один из файлов не может быть скомпилирован, статус выхода будет ненулевым.
- <file> ... <fileN>¶
- -¶
Позиционные аргументы - это файлы для компиляции. Если
-
является единственным параметром, список файлов берется из стандартного ввода.
- -q, --quiet¶
Подавление вывода ошибок.
Изменено в версии 3.2: Добавлена поддержка -
.
Изменено в версии 3.10: Добавлена поддержка -q
.
См.также
- Модуль
compileall
Утилита для компиляции всех исходных файлов Python в дереве каталогов.