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

-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)