compileall — байт-компиляции библиотеки Python

Исходный код: Lib/compileall.py

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

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

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

directory ...
file ...

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

-l

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

-f

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

-q

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

-d destdir

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

-x 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 по пути. Возвращает значение True, если все файлы успешно скомпилирован, и False в противном случае.

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

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

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

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

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

Если legacy True, файлы 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 обновляется нет.

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

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

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

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

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

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

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

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

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

invalidation_mode должен быть членом py_compile.PycInvalidationMode перечисления и определяет, каким образом генерируемый 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. Возвращает значение True, если все файлы успешно скомпилированы, и False значение в противном случае.

Если skip_curdir имеет значение true (по умолчанию), то текущий каталог не входит в поиск. Все остальные параметры передаются в функцию 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.Объекты пути также могут быть использованы.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)

См.также

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