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

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

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

directory ...

file ...

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

-l

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

-f

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

-q

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

-d destdir

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

-s strip_prefix

-p prepend_prefix

Удалить (-s) или добавить (-p) заданный префикс путей, записанных в файлах .pyc. Не может быть использовано совместно с -d.

-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 установлена.

-o level

Скомпилировать с заданным уровнем оптимизации. Может использоваться несколько раз для компиляции сразу для нескольких уровней (например, compileall -o 1 -o 2).

-e dir

Игнорировать ссылки на символы, указывающие на внешнюю область данного каталога.

--hardlink-dupes

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

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

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

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

compileall.compile_dir(dir, maxlevels=sys.getrecursionlimit(), ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=- 1, workers=1, invalidation_mode=None, *, stripdir=None, prependdir=None, limit_sl_dest=None, hardlink_dupes=False)

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

Параметр maxlevels используется для ограничения глубины рекурсии; по умолчанию он равен sys.getrecursionlimit().

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

Если force имеет значение True, модули будут перекомпилированы даже если метки времени последних изменений совпадают.

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

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

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

optimize задаёт уровень оптимизации компилятора. Он передаётся встроенной функции compile(). Также принимает последовательность уровней оптимизации, что приводит к многократному компилированию одного .py файла в одном вызове.

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

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

Аргументы stripdir, prependdir и limit_sl_dest соответствуют параметрам -s, -p и -e , описанным выше. Они могут быть заданы как str или os.PathLike.

Если hardlink_dupes имеет значение True, и два .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 теперь выбирает оптимальное количество ядер.

Изменено в версии 3.9: Добавлены аргументы stripdir, prependdir, limit_sl_dest и hardlink_dupes. Значение параметра maxlevels по умолчанию было изменено с 10 на sys.getrecursionlimit().

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

Компилирует файл с путём fullname. Возвращает значение True, если файл был успешно скомпилирован, и False в противном случае.

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

Если задан параметр rx, его метод search передаёт полное имя файла, подлежащего компиляции, и если он возвращает значение True, файл не компилируется и возвращается True. Это можно использовать для исключения файлов, соответствующих заданному регулярному выражению, представленному объектом re.Pattern.

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

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

optimize задаёт уровень оптимизации компилятора. Он передаётся встроенной функции compile(). Также принимает последовательность уровней оптимизации, что приводит к многократному компилированию одного .py файла в одном вызове.

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

Аргументы stripdir, prependdir и limit_sl_dest соответствуют параметрам -s, -p и -e , описанным выше. Они могут быть заданы как str или os.PathLike.

Если hardlink_dupes имеет значение True, и два .pyc файла с разными уровнями оптимизации имеют одинаковое содержимое, используются жёсткие ссылки для объединения дубликатов.

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

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

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

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

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

Изменено в версии 3.9: Добавлены аргументы stripdir, prependdir, limit_sl_dest и hardlink_dupes.

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)