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

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

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

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

Если задан параметр rx, его метод search вызывается с полным путем к каждому файлу, рассматриваемому для компиляции, и если он возвращает истинное значение, файл пропускается. Это позволяет исключать файлы, соответствующие заданному регулярному выражению, представленному объектом 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, bytes или 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. Возвращает истинное значение, если файл был успешно скомпилирован, и ложное значение в противном случае.

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

Если 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)