compileall — Компиляция исходного кода библиотек в байт-код


Модуль предоставляет полезные функции для поддержки установленных библиотек Python. Данные функции компилируют исходные Python файлы в дереве каталогов в байт-код. Данный модуль может использоваться для создания кэшированных файлов байт-кода во время установки библиотеки, которая делает их доступными для использования даже тем пользователям, у которых нет разрешения на запись в каталоги библиотек.

Использование командной строки

Модуль может работать как скрипт (используя python -m compileall) для компиляции Python исходников.

directory ...
file ...

Позиционные аргументы — это файлы для компиляции или каталоги, которые содержат исходные файлы, просматриваемые рекурсивно. Если аргумент не задан, ведёт себя так, как если в командной строке было набрано -l <directories from sys.path>.

-l

Не заходить рекурсивно в подкаталоги, компилировать напрямую только те файлы исходного кода, которые содержащиеся в названных или подразумеваемых каталогах.

-f

Принудительное перестроение, даже если временные метки актуальны.

-q

Не печатать список скомпилированных файлов. Если он будет передан один раз, то сообщения об ошибках всё равно будут печататься. Если передан дважды (-qq), все выводы подавляются.

-d destdir

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

-x regex

regex, используемое для поиска полного пути для каждого считываемого файла для компиляции, и если regex соответствует, то файл пропускается.

-i list

Прочитать файл list и добавить каждую строку в содержащийся список файлов и каталогов для компиляции. Если list является -, читать строки из stdin.

-b

Записать байт-код в файлы с унаследованными местоположениями и именами, при этом возможна перезапись байт-кода файлов, созданных другой версией Python. По умолчанию записываются файлы в их PEP 3147 положения и имена, что позволяет сосуществовать байт-коду файлам с разными версиями Python.

-r

Управление максимальным уровнем рекурсии для подкаталогов. Если передана, то опция -l не будет принята во внимание. python -m compileall <directory> -r 0 эквивалентна python -m compileall <directory> -l.

-j N

Использовать N работников для компиляции файлов в данной директории. Если используется 0, то будет использован результат os.cpu_count().

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

Контроль того, как сгенерированные файлы байт-кода становятся недействительными во время выполнения. Значение timestamp, означает, что в .pyc файлы будет встроена информация об исходной временной метке и размере. При checked-hash и значении unchecked-hash порождают генерацию pycs основанных на хэшах. В pycs файлах основанных на хэшах добавляются хэш сумма в содержимое исходного файла, а не временная метка. См. Инвалидацию кэша байт-кода для получения дополнительной информации о том, как Python проверяет хэши байт-кода файлов во время выполнения. По умолчанию timestamp если не определена переменная среды SOURCE_DATE_EPOCH и checked-hash если переменная среды SOURCE_DATE_EPOCH определена.

Изменено в версии 3.2: Добавлена -i, -b и -h опция.

Изменено в версии 3.5: Добавлена -j, -r, и -qq опция. Опция -q была изменена на многоуровневую значение. -b всегда будет производить байт-код файлы, заканчивающийся на .pyc, никогда не .pyo.

Изменено в версии 3.7: Добавлена опция --invalidation-mode.

Не существует опции командной строки для управления уровнем оптимизации, используемого compile() функцией, потому что интерпретатор Python сам предоставляет опцию: python -O -m compileall.

Точно так же функция compile() учитывает настройку sys.pycache_prefix. Сгенерированный кеш байт-кода будет полезен, только если compile() запускается с тем же sys.pycache_prefix (если есть), который будет использоваться во время выполнения.

Общедоступные функции

compileall.compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=None)

Рекурсивный спуск по дереву каталогов с именем dir, компилируя все файлы .py по пути. Возвращает истинное значение, если все файлы успешно скомпилирован, и ложное в противном случае.

Параметр maxlevels ограничивает глубину рекурсии; по умолчанию — 10.

Если указан ddir, он добавляется к пути каждого компилируемого файла для использования в трассировках во время компиляции, а также компилируется в файл байт-кода, где он будет использоваться в трассировках и других сообщениях в случаях, когда исходный файл не существует в то время, когда файл байт-кода выполняется.

Если force истина, производится перекомпиляция модулей даже если метки находятся в актуальном состоянии.

Если rx определено, метод поиска вызывается по полному пути для каждого файла прочитанному для компиляции, и если возвращает истинное значение, то файл пропускается.

Если quiet является False или 0 (по умолчанию), имена и другие сведения печатаются в стандартный выход. Установка 1, печатает только ошибки. Установка 2, приводит к подавлению всего выхода.

Если legacy истина, файлы c байт-кодом записываются на прежние места с именами, которые могут переписать байт-код файлов, созданные в другой версии Python. По умолчанию для записи файлов на их PEP 3147 места и имена, что позволяет сосуществовать байт-код файлам с различными версиями Python.

optimize задаёт уровень оптимизации компилятора. Она передаётся встроенной функцией compile().

Аргумент workers указывает, сколько работников используется для компиляции файлов параллельно. Значение по умолчанию не использовать несколько рабочих. Если платформа не может использовать несколько рабочих и workers аргумент предоставлен, то последовательная компиляция будет используемый в качестве запасного варианта. Если workers 0, то их количество равно количеству используемых ядер в системе. Если workers меньше, чем 0, то поднимается ValueError.

invalidation_mode должна быть членом py_compile.PycInvalidationMode перечисления и определяет, каким образом генерируемый pycs становится инвалидируемым во время выполнения.

Изменено в версии 3.2: Добавлен legacy и параметр optimize.

Изменено в версии 3.5: Добавлен параметр workers.

Изменено в версии 3.5: Параметр quiet был изменён на многоуровневое значение.

Изменено в версии 3.5: Параметр legacy только записывает файлы .pyc, не .pyo файлы, вне зависимости от значения optimize.

Изменено в версии 3.6: Принимает путеподобный объект.

Изменено в версии 3.7: Был добавлен параметр invalidation_mode.

Изменено в версии 3.7.2: Значение параметра по умолчанию invalidation_mode обновляется до None.

Изменено в версии 3.8: Установка workers до 0 теперь выбирает оптимальное количество ядер.

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

Скомпилировать файл по адресу fullname. Возвращает истинное значение, если файл успешно скомпилирован, и ложное значение в противном случае.

Если предоставлен ddir, он добавляется к пути к компилируемому файлу для использования в обратных трассировках времени компиляции, а также компилируется в файл с байтовым кодом, где он будет использоваться в обратных трассировках и других сообщениях в тех случаях, когда исходный файл не существует на момент выполнения файла с байт-кодом.

Если предоставлен rx, её методу поиска передаётся полный путь к файлу, который компилируется, и если она возвращает истинное значение, то файл не компилируется и возвращается True.

Если quiet является False или 0 (по умолчанию), имена и другие сведения печатаются в стандартный выход. Установка 1, то печатаются ТОЛЬКО ошибки. Установка 2, то все выходные подавляются.

Если legacy истина, байт-код файлы записываются на их наследственные места и имена, которые могут переписать байт-код файлы, созданные в другой версии Python. По умолчанию производится запись файлов на их PEP 3147 места и имена, что позволяет совместно сосуществовать байт-кодам файлов с различными версиями Python.

optimize задаёт уровень оптимизации компилятора. Передаётся встроенной функцией compile().

invalidation_mode должен быть членом py_compile.PycInvalidationMode enum и определяет, каким образом генерируемый pycs становятся инвалидируемым во время выполнения.

Добавлено в версии 3.2.

Изменено в версии 3.5: Параметр quiet был изменён на многоуровневое значение.

Изменено в версии 3.5: Параметр legacy записывает только .pyc файлы, но не .pyo, вне зависимости от значения optimize.

Изменено в версии 3.7: Добавлен параметр invalidation_mode.

Изменено в версии 3.7.2: Значение параметра по умолчанию invalidation_mode обновлено до None.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=None)

Байт-компиляции всех .py файлов найденных в sys.path. Возвращает истинное значение, если все файлы успешно скомпилированы, и ложное значение в противном случае.

Если у skip_curdir истиное значение (по умолчанию), то текущий каталог не входит в поиск. Все остальные параметры передаются в функцию compile_dir(). Обратите внимание, что в отличие от других функций компиляции, maxlevels по умолчанию 0.

Изменено в версии 3.2: Добавлен legacy и параметр optimize.

Изменено в версии 3.5: Параметр quiet был изменён на многоуровневое значение.

Изменено в версии 3.5: Параметр legacy записывает только .pyc файлы, но не .pyo, вне зависимости от значения optimize.

Изменено в версии 3.7: Добавлен параметр invalidation_mode.

Изменено в версии 3.7.2: Значение параметра по умолчанию invalidation_mode обновлено до None.

Принудительная перекомпиляция всех файлов .py в Lib/ каталоге и всех его подкаталогах:

import compileall

compileall.compile_dir('Lib/', force=True)

# Выполнить ту же компиляцию, исключая файлы в каталогах .svn.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path объекты также могут использоваться.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

См.также

Модуль py_compile
Байтовая компиляция одного исходного файла.