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

Исходный код: Lib/compileall.py

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

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

Этот модуль может работать как скрипт (используя python -m compileall) для компиляции исходного кода Python.

directory ...

file ...

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

-l

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

-f

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

-q

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

-d destdir

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

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

Нет опции в командной строке для управления уровнем оптимизации, используемым функцией compile(), так как сам интерпретатор Python уже предоставляет эту опцию: python -O -m compileall.

Публичные функции

compileall.compile_dir(dir, maxlevels=10, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, workers=1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP)

Рекурсивно спускается по дереву каталогов, заданному dir, компилируя все .py файлы по пути. Возвращает True, если все файлы были успешно скомпилированы, и False в противном случае.

Параметр maxlevels используется для ограничения глубины рекурсии; он по умолчанию равен 10.

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

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

Если задано rx, его метод поиска вызывается для полного пути каждого файла, рассматриваемого для компиляции, и если он возвращает True, файл пропускается.

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

Если legacy имеет значение True, файлы байт-кода записываются в их устаревшие расположения и имена, что может перезаписать файлы байт-кода, созданные другой версией Python. По умолчанию файлы записываются в их расположения и имена согласно PEP 3147, что позволяет файлам байт-кода из нескольких версий Python сосуществовать.

optimize задает уровень оптимизации для компилятора. Он передается встроенной функции compile().

Аргумент workers указывает, сколько потоков используется для параллельной компиляции файлов. По умолчанию не используется несколько потоков. Если платформа не может использовать несколько потоков, и аргумент workers задан, используется последовательная компиляция в качестве резервного варианта. Если workers меньше 0, будет поднято исключение ValueError.

invalidation_mode должен быть членом перечисления py_compile.PycInvalidationMode и управляет тем, как сгенерированные pycs аннулируются во время выполнения.

Изменено в версии 3.2: Добавлены параметры legacy и optimize.

Изменено в версии 3.5: Добавлен параметр workers.

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

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

Изменено в версии 3.6: Принимает объект-путь.

Изменено в версии 3.7: Добавлен параметр invalidation_mode.

compileall.compile_file(fullname, ddir=None, force=False, rx=None, quiet=0, legacy=False, optimize=-1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP)

Компилирует файл с путем fullname. Возвращает значение true, если файл был успешно скомпилирован, и false в противном случае.

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

Если задан rx, его метод поиска передаёт полное имя файла, который компилируется, и если он возвращает значение true, файл не компилируется и True возвращается.

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

Если legacy имеет значение true, файлы байткода записываются в устаревшие места и имена, что может перезаписать файлы байткода, созданные другой версией Python. По умолчанию файлы записываются в места и с именами согласно PEP 3147, что позволяет файлам байткода из нескольких версий Python сосуществовать.

optimize задаёт уровень оптимизации для компилятора. Он передаётся встроенной функции compile().

invalidation_mode должен быть членом перечисления py_compile.PycInvalidationMode и управляет тем, как сгенерированные pycs аннулируются во время выполнения.

Новое в версии 3.2.

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

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

Изменено в версии 3.7: Параметр invalidation_mode был добавлен.

compileall.compile_path(skip_curdir=True, maxlevels=0, force=False, quiet=0, legacy=False, optimize=-1, invalidation_mode=py_compile.PycInvalidationMode.TIMESTAMP)

Компилирует все .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 был добавлен.

Чтобы принудительно перекомпилировать все .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)