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

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