py_compile и compileall: компилируем Python сами

В первом уроке мы выяснили, что компиляция происходит при каждом запуске и импорте, а второй урок разобрал устройство pyc-файла. Остался вопрос практики: когда компилировать нужно самим. Ответов три: проверка синтаксиса большого проекта без запуска ни одной строки, прогрев кэша перед выкладкой на сервер и сборка дистрибутива, где pyc едут вместе с исходниками. Компиляция без запуска — это проверка синтаксиса всего проекта за секунды: ни одна строка кода не исполнилась. Стандартная библиотека закрывает всё это двумя модулями: py_compile компилирует один файл, compileall — каталог целиком.

py_compile: один файл

Функция py_compile.compile принимает путь к исходнику, компилирует его и пишет pyc туда же, куда его положил бы обычный импорт — в __pycache__ рядом. Возвращаемое значение — путь к созданному файлу:

import glob
import os
import py_compile

with open('tool_demo.py', 'w', encoding='utf-8') as f:
    f.write('def run():\n    return 1 + 1\n')

pyc = py_compile.compile('tool_demo.py')
print('исходник на месте:', os.path.exists('tool_demo.py'))
print('pyc создан:', os.path.exists(pyc))
print('компилятор вернул строку-путь:', isinstance(pyc, str))

for p in glob.glob('__pycache__/*.pyc'):
    os.remove(p)
if os.path.isdir('__pycache__'):
    os.rmdir('__pycache__')
os.remove('tool_demo.py')

исходник на месте: True
pyc создан: True
компилятор вернул строку-путь: True

Три факта о поведении: компиляция не трогает исходник, результат действительно появился и путь вернулся строкой. Имя файла внутри __pycache__ содержит метку версии интерпретатора, поэтому мы проверяем существование, а не печатаем путь: на CPython 3.12 и 3.13 хвосты имени разные. Если имя нужно своё — есть параметр cfile.

import os
import py_compile

with open('pack_demo.py', 'w', encoding='utf-8') as f:
    f.write('VERSION = 1\n')

py_compile.compile('pack_demo.py', cfile='pack_compiled.pyc')
print('компиляция по своему пути сработала:', os.path.exists('pack_compiled.pyc'))

os.remove('pack_compiled.pyc')
os.remove('pack_demo.py')

компиляция по своему пути сработала: True

Параметр cfile отправил результат по указанному пути — файл появился в текущем каталоге, а не в __pycache__. Так собирают pyc для дистрибутивов с заранее известной структурой каталогов. Назвали файл сами — значит, и метку версии в имени можно не тащить: интерпретатор всё равно сверит magic-число из заголовка (пятый урок).

Ошибки компиляции: doraise

Главный сценарий ручной компиляции — проверка кода без запуска. Файл с ошибкой синтаксиса компилятор замечает мгновенно, но по умолчанию py_compile не считает это ЧП: он печатает ошибку в поток ошибок и возвращает None. Чтобы ошибка стала исключением, включают doraise=True:

import os
import py_compile

with open('cracked_demo.py', 'w', encoding='utf-8') as f:
    f.write('x = (1 +\n')

try:
    py_compile.compile('cracked_demo.py', doraise=True)
    print('скомпилировалось без ошибок')
except py_compile.PyCompileError:
    print('поймали PyCompileError: файл с ошибкой')

os.remove('cracked_demo.py')

поймали PyCompileError: файл с ошибкой

Незакрытая скобка превратилась в исключение PyCompileError, которое скрипт ловит и обрабатывает: так строятся проверки всего проекта в CI. Без doraise тот же файл проскочил бы молча — функция вернула None, и если код не проверяет возвращаемое значение, битый файл уехал бы в продакшен незамеченным.

compileall: каталог целиком

Для проекта из десятков файлов вызывать py_compile по одному — мучение. compileall.compile_dir проходит каталог рекурсивно и компилирует каждый .py файл. Возвращаемое значение — True, если всё скомпилировалось; посчитать результат можно любым способом, здесь — количеством pyc в кэше:

import compileall
import glob
import os
import shutil

shutil.rmtree('pkg_demo', ignore_errors=True)
os.makedirs('pkg_demo')
for name in ('alpha', 'beta', 'gamma'):
    with open('pkg_demo/' + name + '.py', 'w', encoding='utf-8') as f:
        f.write('N = 1\n')

result = compileall.compile_dir('pkg_demo', quiet=1)
print('каталог скомпилирован:', result)
print('pyc собрано:', len(glob.glob('pkg_demo/__pycache__/*.pyc')))

shutil.rmtree('pkg_demo')

каталог скомпилирован: True
pyc собрано: 3

Три модуля — три pyc, по одному на каждый исходник. Параметр quiet=1 убрал стандартный дот-репорт компилятора (по точке на файл), чтобы вывод остался читаемым. Когда понадобится перекомпилировать всё принудительно, даже если кэш кажется свежим, — параметр force=True: по умолчанию compileall пропускает файлы, у которых pyc уже актуален.

import compileall
import glob
import os
import shutil

os.makedirs('single_demo', exist_ok=True)
with open('single_demo/report.py', 'w', encoding='utf-8') as f:
    f.write('M = 2\n')

ok = compileall.compile_file('single_demo/report.py', quiet=1)
print('одиночный файл скомпилирован:', ok)
print('pyc в кэше модуля:', len(glob.glob('single_demo/__pycache__/*.pyc')))

shutil.rmtree('single_demo')

одиночный файл скомпилирован: True
pyc в кэше модуля: 1

У compileall есть и функция для одного файла — compile_file. Она удобна, когда скрипт уже импортирует compileall, а отдельный py_compile ради одного вызова тянуть не хочется. Имя __pycache__ внутри single_demo — то же правило: кэш живёт рядом с исходником.

Командная строка

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

python -m py_compile app.py
python -m compileall мой_проект/

python -m py_compile app.py settings.py utils.py

python -m compileall -q мой_проект/

• py_compile.compile компилирует один файл и возвращает путь к pyc в __pycache__;
• cfile задаёт свой путь результата — удобно для сборки дистрибутивов;
• doraise=True превращает SyntaxError в PyCompileError: без него ошибка печатается в stderr и функция возвращает None;
• compileall.compile_dir компилирует каталог рекурсивно, compile_file — один файл, force=True игнорирует свежий кэш;
• из консоли работают обе формы: python -m py_compile и python -m compileall.

Ручная компиляция — про кэш и проверку синтаксиса. Дальше по разделу: как прочитать байткод глазами — дизассемблер dis в четвёртом уроке, почему pyc строго привязан к версии интерпретатора — пятый урок про magic-число, а про то, как интерпретатор сам управляет этим кэшем — шестой урок про __pycache__.