pyc-файл: устройство скомпилированного файла Python

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

Создаём первый pyc

Для опытов возьмём py_compile — модуль стандартной библиотеки, который компилирует файл и пишет результат на диск. Подробный разбор его настроек — в третьем уроке, здесь он просто поставщик подопытного файла:

import os
import py_compile

with open('app_demo.py', 'w', encoding='utf-8') as f:
    f.write('RATIO = 2\n\n\ndef scaled(n):\n    return n * RATIO\n')

py_compile.compile('app_demo.py')
print('исходник на месте:', os.path.exists('app_demo.py'))
print('каталог pyc появился:', os.path.isdir('__pycache__'))

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

исходник на месте: True
каталог pyc появился: True

Компиляция положила результат в каталог __pycache__ рядом с исходником. Имя файла внутри повторяет имя модуля и добавляет метку версии интерпретатора — у CPython 3.12 она выглядит как cpython-312, поэтому мы не печатаем имя целиком: на вашей машине хвост будет другим. Структура при этом одна и та же на всех версиях начиная с 3.7: 16 байт заголовка и marshal-блок.

Заголовок: первые 16 байт

Заголовок pyc — четыре числа по четыре байта каждое, записанные в младшем порядке (little-endian). Первое — magic-число версии, а три остальных — паспорт исходника:

Читается заголовок обычной работой с байтами: читаем файл в режиме rb, режем срезами по четыре байта и собираем числа через int.from_bytes(..., 'little'). Первый опыт — сверить magic-число файла с тем, что выдает наш собственный интерпретатор через importlib.util.MAGIC_NUMBER:

import importlib.util
import os
import py_compile

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

pyc = py_compile.compile('header_demo.py')
with open(pyc, 'rb') as f:
    data = f.read()

print('файл прочитан, данных больше нуля:', len(data) > 0)
print('первые 4 байта совпали с MAGIC_NUMBER:', data[:4] == importlib.util.MAGIC_NUMBER)
print('магическое число занимает 4 байта:', len(importlib.util.MAGIC_NUMBER) == 4)
print('флаги равны нулю:', int.from_bytes(data[4:8], 'little') == 0)
print('время исходника записано:', int.from_bytes(data[8:12], 'little') > 0)

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

файл прочитан, данных больше нуля: True
первые 4 байта совпали с MAGIC_NUMBER: True
магическое число занимает 4 байта: True
флаги равны нулю: True
время исходника записано: True

Пять проверок, пять True. Magic-число самого файла совпало с magic-числом работающего интерпретатора — это и есть та самая проверка версии, из-за которой pyc с одной версии не запускается на другой (пятый урок). Флаги равны нулю — файл собран в обычном временном режиме, а не в hash-режиме для деплоя. Поле времени — не ноль: интерпретатор записал mtime исходника на момент компиляции.

import glob
import os
import py_compile

with open('size_demo.py', 'w', encoding='utf-8') as f:
    f.write('N = 1\nN += 2\n')

pyc = py_compile.compile('size_demo.py')
with open(pyc, 'rb') as f:
    data = f.read()
stored = int.from_bytes(data[12:16], 'little')
print('размер из заголовка совпал с исходником:', stored == os.path.getsize('size_demo.py'))

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

размер из заголовка совпал с исходником: True

В заголовке лежит точный размер исходника в байтах: N = 1 и N += 2 с переводами строк — тринадцать байт, и os.path.getsize дал то же число. Пара «время + размер» — это те самые два поля, по которым интерпретатор решает, устарел ли кэш: тема шестого урока про __pycache__.

Как выглядит заголовок в байтах

Вот настоящий дамп первых 16 байт pyc для исходника N = 1 (7 байт текста), разбитый на поля:

f3 0d 0d 0a   magic
00 00 00 00   флаги = 0
d5 65 f0 6a   время изменения исходника
07 00 00 00   размер исходника = 7 байт

Первые два байта magic меняются от версии к версии, последние два всегда 0d 0a — перевод строки в стиле Windows: это история формата, оставшаяся с ранних версий. Время d5 65 f0 6a — просто unix-timestamp компиляции. Проверить этот дамп на своей машине можно тем же кодом из предыдущего блока — только байты будут свои.

Тело файла: marshal-блок

С 16-го байта начинается тело — marshal-сериализация кодового объекта из первого урока. Marshal — встроенный формат CPython для своих объектов; его тонкости — седьмой урок. Здесь достаточно того, что marshal.loads превращает тело обратно в кодовый объект, который можно исполнить:

import glob
import marshal
import os
import py_compile
import types

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

pyc = py_compile.compile('body_demo.py')
with open(pyc, 'rb') as f:
    data = f.read()

code = marshal.loads(data[16:])
print('тело pyc — кодовый объект:', isinstance(code, types.CodeType))
print('имя кодового объекта модуля:', code.co_name)

ns = {}
exec(code, ns)
print('функция из pyc работает:', ns['area'](5))

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

тело pyc — кодовый объект: True
имя кодового объекта модуля: <module>
функция из pyc работает: 25

Три шага — и pyc полностью расшифрован: срез [16:] отделил заголовок, marshal.loads собрал кодовый объект, exec исполнил его как обычный модуль. Функция area из файла, который мы никогда не импортировали, честно вернула 25. Именно эти три шага выполняет интерпретатор, когда грузит модуль из кэша, — только заголовок он ещё и проверяет.

Чего внутри pyc нет

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

import os
import py_compile

with open('rebuild_demo.py', 'w', encoding='utf-8') as f:
    f.write('K = 3\n')

pyc = py_compile.compile('rebuild_demo.py')
os.remove(pyc)
print('pyc после удаления существует:', os.path.exists(pyc))
py_compile.compile('rebuild_demo.py')
print('pyc после повторной компиляции:', os.path.exists(pyc))

os.remove(pyc)
os.rmdir('__pycache__')
os.remove('rebuild_demo.py')

pyc после удаления существует: False
pyc после повторной компиляции: True

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

python -m dis __pycache__/app_demo.cpython-312.pyc

python -c "data = open('__pycache__/app_demo.cpython-312.pyc', 'rb').read(16); print(data[4:8] == b'\x00\x00\x00\x00')"

True

• pyc — кэш компиляции: кодовый объект, записанный на диск рядом с исходником;
• заголовок — 16 байт: magic версии, флаги, mtime и размер исходника, все числа little-endian;
• тело — marshal-блок: marshal.loads(data[16:]) возвращает кодовый объект, exec исполняет его;
• исходного текста внутри нет, ускоряется только загрузка модуля, а не его исполнение;
• pyc привязан к версии: magic-число и формат байткода меняются в каждой минорной версии.

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