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