compileall — Байт-компиляция библиотек Python

Источник: Lib/compileall.py

Этот модуль предоставляет некоторые служебные функции для поддержки установки библиотек Python. Эти функции компилируют исходные файлы Python в дереве каталогов. Этот модуль можно использовать для создания кэшированных файлов байт-кода во время установки библиотеки, что делает их доступными для использования даже теми пользователями, у которых нет прав на запись в каталоги библиотеки.

Availability: не WASI.

Этот модуль не работает или недоступен на WebAssembly. Дополнительную информацию см. в разделе Платформы WebAssembly.

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

Этот модуль может работать как скрипт (используя 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.process_cpu_count().

--invalidation-mode [timestamp|checked-hash|unchecked-hash]

Управляет тем, как сгенерированные файлы байт-кода будут аннулированы во время выполнения. Значение timestamp означает, что будут сгенерированы файлы .pyc с исходной временной меткой и встроенным размером. Значения checked-hash и unchecked-hash приводят к генерации пикчей на основе хэша. В хэш-файлы pycs встраивается хэш содержимого исходного файла, а не временная метка. Смотрите Устранение недействительности кэшированного байткода для получения дополнительной информации о том, как Python проверяет файлы кэша байткода во время выполнения. По умолчанию используется значение timestamp, если переменная окружения SOURCE_DATE_EPOCH не установлена, и checked-hash, если установлена переменная окружения SOURCE_DATE_EPOCH.

-o level

Компиляция с заданным уровнем оптимизации. Может использоваться несколько раз для компиляции нескольких уровней за раз (например, compileall -o 1 -o 2).

-e dir

Игнорировать симлинки, указывающие за пределы заданного каталога.

Если два .pyc файла с разным уровнем оптимизации имеют одинаковое содержимое, используйте жесткие ссылки для объединения дубликатов.

Изменено в версии 3.2: Добавлены опции -i, -b и -h.

Изменено в версии 3.5: Добавлены опции -j, -r и -qq. Опция -q была заменена на многоуровневое значение. -b всегда будет создавать файл с байт-кодом, заканчивающимся на .pyc, и никогда - на .pyo.

Изменено в версии 3.7: Добавлена опция --invalidation-mode.

Изменено в версии 3.9: Добавлены опции -s, -p, -e и --hardlink-dupes. Увеличен лимит рекурсии по умолчанию с 10 до sys.getrecursionlimit(). Добавлена возможность указывать опцию -o несколько раз.

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

Изменено в версии 3.5: Параметр quiet был изменен на многоуровневое значение.

Изменено в версии 3.5: Параметр legacy записывает только файлы .pyc, а не .pyo, независимо от значения параметра optimize.

Изменено в версии 3.6: Принимает path-like object.

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

Added in version 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)

См.также

Модуль py_compile

Байт-компиляция одного исходного файла.