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.process_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 и управляет тем, как сгенерированные pycs будут аннулированы во время выполнения.

Аргументы 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 и управляет тем, как сгенерированные pycs будут аннулированы во время выполнения.

Аргументы 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)