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

Для поиска совпадений с regex используется полный путь к каждому файлу, рассматриваемому для компиляции; если 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 имеет истинное значение, модули компилируются повторно, даже если временные метки актуальны.

Если задан 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)