compileall – байт-компиляция библиотек Python¶compileall – Byte-compile Python libraries

Использование в командной строке¶Command-line use

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

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

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

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

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 равен 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 и управляет тем, как сгенерированные pyc становятся недействительными во время выполнения.

Аргументы stripdir, prependdir и limit_sl_dest соответствуют опциям -s, -p и -e, описанным выше. Они могут быть указаны как str или os.PathLike.

Если hardlink_dupes равен true и два файла .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)

# Выполнить ту же компиляцию, исключая файлы в каталогах .svn.
import re
compileall.compile_dir('Lib/', rx=re.compile(r'[/\\][.]svn'), force=True)

# Объекты pathlib.Path также можно использовать.
import pathlib
compileall.compile_dir(pathlib.Path('Lib/'), force=True)