compileall — Byte-compile Python libraries

Вихідний код: Lib/compileall.py

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

Використання командного рядка

Цей модуль може працювати як сценарій (за допомогою python -m compileall) для компіляції вихідних кодів Python.

directory ...
file ...

Positional arguments are files to compile or directories that contain source files, traversed recursively. If no argument is given, behave as if the command line was -l <directories from sys.path>.

-l

Не повертайтеся до підкаталогів, лише компілюйте файли вихідного коду, які безпосередньо містяться в названих або неявних каталогах.

-f

Примусове відновлення, навіть якщо мітки часу актуальні.

-q

Не друкуйте список зібраних файлів. Якщо передати один раз, повідомлення про помилку все одно друкуватимуться. Якщо передати двічі (-qq), весь вивід пригнічується.

-d destdir

Каталог додається до шляху до кожного файлу, що компілюється. Це відображатиметься у відстеженнях під час компіляції, а також буде скомпільовано у файл байт-коду, де воно використовуватиметься у відстеженнях та інших повідомленнях у випадках, коли вихідний файл не існує під час виконання файлу байт-коду.

-s strip_prefix
-p prepend_prefix

Видаліть (-s) або додайте (-p) заданий префікс шляхів, записаних у файлах .pyc. Не можна поєднувати з -d.

-x regex

регулярний вираз використовується для пошуку повного шляху до кожного файлу, який розглядається для компіляції, і якщо регулярний вираз видає збіг, файл пропускається.

-i list

Прочитайте файл список і додайте кожен рядок, який він містить, до списку файлів і каталогів для компіляції. Якщо список -, читати рядки з stdin.

-b

Запишіть файли байт-коду в їхні застарілі розташування та імена, які можуть перезаписати файли байт-коду, створені іншою версією Python. За замовчуванням файли записуються в їхні розташування та імена PEP 3147, що дозволяє співіснувати файлам байт-коду з кількох версій Python.

-r

Контролюйте максимальний рівень рекурсії для підкаталогів. Якщо це задано, то параметр -l не буде взято до уваги. python -m compileall <directory> -r 0 еквівалентно python -m compileall <directory> -l.

-j N

Use N workers to compile the files within the given directory. If 0 is used, then the result of os.cpu_count() will be used.

--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

Ігноруйте символічні посилання, що вказують за межі даного каталогу.

Якщо два файли .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.

Similarly, the compile() function respects the sys.pycache_prefix setting. The generated bytecode cache will only be useful if compile() is run with the same sys.pycache_prefix (if any) that will be used at runtime.

Громадські функції

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

The stripdir, prependdir and limit_sl_dest arguments correspond to the -s, -p and -e options described above. They may be specified as str, bytes or os.PathLike.

Якщо hardlink_dupes має значення true і два файли .pyc з різним рівнем оптимізації мають однаковий вміст, використовуйте жорсткі посилання для об’єднання дублікатів файлів.

Змінено в версії 3.2: Додано параметр legacy і optimize.

Змінено в версії 3.5: Додано параметр workers.

Змінено в версії 3.5: Параметр quiet змінено на багаторівневе значення.

Змінено в версії 3.5: Параметр legacy записує лише файли .pyc, а не файли .pyo незалежно від значення optimize.

Змінено в версії 3.6: Приймає path-like object.

Змінено в версії 3.7: Додано параметр invalidation_mode.

Змінено в версії 3.7.2: The invalidation_mode parameter’s default value is updated to 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 і керувати тим, як згенеровані pyc стають недійсними під час виконання.

The stripdir, prependdir and limit_sl_dest arguments correspond to the -s, -p and -e options described above. They may be specified as str, bytes or os.PathLike.

Якщо hardlink_dupes має значення true і два файли .pyc з різним рівнем оптимізації мають однаковий вміст, використовуйте жорсткі посилання для об’єднання дублікатів файлів.

Нове в версії 3.2.

Змінено в версії 3.5: Параметр quiet змінено на багаторівневе значення.

Змінено в версії 3.5: Параметр legacy записує лише файли .pyc, а не файли .pyo незалежно від значення optimize.

Змінено в версії 3.7: Додано параметр invalidation_mode.

Змінено в версії 3.7.2: The invalidation_mode parameter’s default value is updated to 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: The invalidation_mode parameter’s default value is updated to 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

Байтова компіляція єдиного вихідного файлу.