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

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

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

directory ...

file ...

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

-l

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

-f

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

-q

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

-d destdir

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

-s strip_prefix

Удалить указанный префикс из путей, записанных в файлах .pyc. Пути становятся относительными к префиксу.

Этот параметр можно использовать с -p, но не с -d.

-p prepend_prefix

Добавить указанный префикс в начало путей, записанных в файлах .pyc. Используйте -p /, чтобы сделать пути абсолютными.

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

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

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

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

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

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

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

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

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