compileall — Компиляция 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 вызывают генерацию pyc на основе хэша. Хэшированные pyc содержат хэш содержимого файла исходного кода вместо метки времени. См. Инвалидация кэша байткода для получения более подробной информации о том, как Python проверяет файлы кэша байткода во время выполнения. По умолчанию timestamp, если переменная окружения SOURCE_DATE_EPOCH не установлена, и checked-hash, если переменная окружения SOURCE_DATE_EPOCH установлена.

Нет опции командной строки для управления уровнем оптимизации, используемым функцией 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, он добавляется в начало пути каждого компилируемого файла для использования в отслеживании времени компиляции, а также включается в файл байткода, где используется для отслеживания и других сообщений в случаях, когда исходный файл отсутствует в момент выполнения файла байткода.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Новое в версии 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)

# Perform same compilation, excluding files in .svn directories.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# pathlib.Path objects can also be used.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)