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