__pycache__: кэш компиляции Python

Каталог __pycache__ в проекте появляется без приглашения: первый же импорт модуля — и рядом с исходником лежит свежий pyc с magic-числом версии из пятого урока. Новички спрашивают, можно ли его удалить; опытные — когда он может наврать. Оба ответа следуют из одного устройства: это кэш, который интерпретатор сам создаёт, сам проверяет и сам пересобирает. Урок учит управлять этим механизмом, а не терпеть его.

Когда появляется каталог

Кэш пишется при импорте модуля — не при запуске скрипта. python app.py компилирует app.py и держит байткод в памяти: главный скрипт кэша не получает. А вот каждый импортированный модуль проекта честно компилируется один раз, и результат сохраняется:

with open('helper.py', 'w', encoding='utf-8') as f:
    f.write('def twice(n):\n    return n * 2\n')

import helper
import os

print('модуль работает:', helper.twice(21))
print('каталог кэша появился:', os.path.isdir('__pycache__'))

os.remove('helper.py')

модуль работает: 42
каталог кэша появился: True

Блок намеренно не запускается в песочнице: там импорт сработает и функция вернёт 42, но каталог не появится — запись кэша в браузерном интерпретаторе выключена. На локальной машине этот же код после первого запуска создаст __pycache__ с файлом helper.cpython-312.pyc (метка вашей версии). Именно поэтому главный файл проекта в кэше не ищут: его байткод живёт один запуск, а модулей — столько, сколько запусков.

В песочнице урока запись кэша при импорте отключена — но собрать pyc явно можно любым инструментом из третьего урока. Такой кэш в этой статье мы и разбираем на поля:

import glob
import os
import py_compile

with open('cached_demo.py', 'w', encoding='utf-8') as f:
    f.write('VALUE = 10\n')

py_compile.compile('cached_demo.py')
print('каталог кэша существует:', os.path.isdir('__pycache__'))
print('pyc в кэше:', len(glob.glob('__pycache__/*.pyc')))

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

каталог кэша существует: True
pyc в кэше: 1

Инвалидация: время и размер

Кэш полезен, только пока он соответствует исходнику. Проверка свежести опирается на два поля заголовка pyc из второго урока: время изменения и размер исходника. При импорте интерпретатор сравнивает поля с текущим файлом — не совпало, значит исходник менялся, и компиляция выполняется заново. Посмотрим на поля своими глазами — сначала время:

import glob
import os
import py_compile

with open('stamp_demo.py', 'w', encoding='utf-8') as f:
    f.write('VALUE = 10\n')

pyc = py_compile.compile('stamp_demo.py')
with open(pyc, 'rb') as f:
    data = f.read()
stored = int.from_bytes(data[8:12], 'little')
print('время исходника сохранено в pyc:', stored == int(os.path.getmtime('stamp_demo.py')))

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

время исходника сохранено в pyc: True

Поле с 8-го по 12-й байт заголовка — unix-время исходника на момент компиляции, и оно совпало с os.path.getmtime файла. Второе поле — размер — даёт проверке второе измерение: время может соврать на файловых системах, где копирование сбрасывает метки, а размер врёт реже:

import glob
import os
import py_compile

with open('stale_demo.py', 'w', encoding='utf-8') as f:
    f.write('VALUE = 10\n')

pyc = py_compile.compile('stale_demo.py')
with open(pyc, 'rb') as f:
    old_size = int.from_bytes(f.read()[12:16], 'little')

with open('stale_demo.py', 'w', encoding='utf-8') as f:
    f.write('VALUE = 10\nVALUE += 5\n')

new_size = os.path.getsize('stale_demo.py')
print('размер исходника изменился:', new_size != old_size)
print('старый pyc устарел:', old_size != new_size)

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

размер исходника изменился: True
старый pyc устарел: True

Мы дописали строку в исходник после компиляции — размер вырос, и кэш, собранный по старому содержимому, теперь числится устаревшим. Дальше события развиваются без нашего участия: при следующем импорте интерпретатор заметит несовпадение и молча перекомпилирует модуль. Никаких команд для обновления кэша вводить не надо.

import glob
import os
import py_compile

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

pyc = py_compile.compile('fresh_demo.py')
with open(pyc, 'rb') as f:
    old_stamp = int.from_bytes(f.read()[8:12], 'little')

os.utime('fresh_demo.py', (1000000000, 1000000000))
new_stamp = int(os.path.getmtime('fresh_demo.py'))
print('время исходника изменилось:', new_stamp != old_stamp)
print('Python заметит такое обновление:', new_stamp != old_stamp)

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

время исходника изменилось: True
Python заметит такое обновление: True

Функция os.utime передвинула время изменения исходника на 2001 год — содержимое то же, а вердикт изменился: pyc собран по свежему времени, исходник теперь «старше», проверка не сойдётся, и модуль будет перекомпилирован. Этим приёмом пользуются сборочные скрипты: коснуться времени файлов, чтобы кэш гарантированно пересобрался.

Управление кэшем

Кэш полностью управляем: создаётся любым из инструментов третьего урока, проверяется по полям заголовка и удаляется как обычный каталог. Соберём pyc и уберём за собой:

import glob
import os
import py_compile

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

py_compile.compile('cleanup_demo.py')
before = len(glob.glob('__pycache__/*.pyc'))
for p in glob.glob('__pycache__/*.pyc'):
    os.remove(p)
if os.path.isdir('__pycache__'):
    os.rmdir('__pycache__')
after = len(glob.glob('__pycache__/*.pyc'))
print('pyc до очистки:', before)
print('pyc после очистки:', after)
os.remove('cleanup_demo.py')

pyc до очистки: 1
pyc после очистки: 0

Удаление кэша — не поломка: второй урок показывал, что pyc восстанавливается при первом же импорте. Кэш компиляции самодостаточен: удалили каталог — интерпретатор соберёт его заново при первом же импорте. Из-за этого каталог и исключают из git: репозиторий хранит исходники, кэш у каждой машины свой.

find . -type d -name __pycache__ -exec rm -rf {} +

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

• кэш пишется при импорте модулей; главный скрипт запуска не кэшируется;
• свежесть проверяется по двум полям заголовка pyc: времени и размеру исходника;
• изменился исходник — pyc пересобирается сам при следующем импорте, команд не нужно;
• очистка безопасна: __pycache__ восстанавливается автоматически;
• запись отключается флагом -B или переменной PYTHONDONTWRITEBYTECODE, а не правкой кода.

Кэш — забота интерпретатора, и после этого урока — ваша тоже: вы знаете, когда он появляется, как проверяется и как им управлять. Дальше по разделу — marshal в седьмом уроке: формат, которым байткод упаковывается внутрь pyc.