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

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

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

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

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

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

32.11.2. Общедоступные функции

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Введено в версии 3.2.

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

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

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

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

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