"""Ячейка: где живёт переменная, которую видят сразу несколько функций.

ЗАЧЕМ ЭТОТ СКРИПТ. Замыкание обычно объясняют словами «функция помнит
окружение», и из этого объяснения не следует ни одного из наблюдаемых
поведений: почему изменение переменной видно во всех замыканиях сразу, почему
цикл выдаёт десять функций с одинаковым ответом, почему `nonlocal` нужен, а
`global` — нет. Всё это следует из одного факта: переменная, которую видит
вложенная функция, лежит НЕ в кадре, а в отдельном объекте — ячейке. Ячейка
наблюдаема из Python, и этот скрипт её показывает.

ЧТО ЗДЕСЬ НЕ МЕРЯЕТСЯ. Время. Цену чтения имени из ячейки против локального и
глобального меряет `cost.py` внутри одного запуска.

ЗАПУСК:

    for v in 3.12 3.13 3.14; do python$v bench/calls/cells.py; done
"""

import dis
import platform
import sys


def head(n: int, title: str) -> None:
    line = f"{n}. {title}"
    print(f"\n{line}\n{'-' * len(line)}")


def make_counter():
    count = 0

    def increment():
        nonlocal count
        count += 1
        return count

    def read():
        return count

    return increment, read


def make_by_loop():
    return [lambda: i for i in range(3)]


def make_by_default():
    return [lambda i=i: i for i in range(3)]


def main() -> None:
    print(f"Python {platform.python_version()}")
    print(f"Сборка: {sys.version.split('[')[-1].rstrip('] ')}")
    print("\nЗдесь разбираются объекты и байт-код — не время.")

    head(1, "ЯЧЕЙКА — ЭТО ОБЪЕКТ, И ЕЁ ВИДНО ИЗ PYTHON")
    increment, read = make_counter()
    print(f"  increment.__closure__            {increment.__closure__}")
    print(f"  тип элемента                     {type(increment.__closure__[0]).__name__}")
    print(f"  increment.__code__.co_freevars   {increment.__code__.co_freevars}")
    print(f"  значение внутри ячейки           {increment.__closure__[0].cell_contents}")
    print("\n  Ячейка — не «сохранённая копия переменной», а коробка, на которую")
    print("  ссылается функция. Значение лежит в коробке, а не в функции.")

    head(2, "ДВЕ ФУНКЦИИ ДЕЛЯТ ОДНУ КОРОБКУ")
    same = increment.__closure__[0] is read.__closure__[0]
    print(f"  increment.__closure__[0] is read.__closure__[0]   {same}")
    print(f"  read() до вызова increment                       {read()}")
    increment()
    increment()
    print(f"  read() после двух increment()                    {read()}")
    print(f"  значение в ячейке                                "
          f"{increment.__closure__[0].cell_contents}")
    print("\n  Ни одна из двух функций не передавала другой ничего. Они просто")
    print("  ссылаются на одну и ту же коробку — это и есть «общая переменная».")

    head(3, "ПОЧЕМУ ЦИКЛ ВЫДАЁТ ТРИ ОДИНАКОВЫЕ ФУНКЦИИ")
    by_loop = make_by_loop()
    by_default = make_by_default()
    print(f"  [lambda: i for i in range(3)]      → {[f() for f in by_loop]}")
    print(f"  [lambda i=i: i for i in range(3)]  → {[f() for f in by_default]}")
    cells = {id(f.__closure__[0]) for f in by_loop if f.__closure__}
    print(f"\n  разных ячеек у первых трёх функций: {len(cells)}")
    print(f"  есть ли ячейка у вторых трёх:       "
          f"{'нет' if by_default[0].__closure__ is None else 'да'}")
    print("\n  Первая строка — не ошибка Python и не «позднее связывание» как")
    print("  отдельное правило. Коробка одна на все три функции, к моменту")
    print("  вызова в ней лежит последнее значение. Вторая строка обходит это")
    print("  тем, что значение попадает в аргумент по умолчанию — а он")
    print("  вычисляется в момент создания функции, а не вызова.")

    head(4, "КТО РЕШАЕТ, ЧТО ПЕРЕМЕННАЯ СТАНЕТ ЯЧЕЙКОЙ")
    src = """
G = 1

def outer(param):
    local = 2
    box = 3
    def inner():
        return box
    return param, local, G, inner()
"""
    ns: dict = {}
    exec(src, ns)  # noqa: S102 — код свой, не из ввода
    outer = ns["outer"]
    inner_code = next(c for c in outer.__code__.co_consts if hasattr(c, "co_name"))
    print(f"  outer.__code__.co_varnames   {outer.__code__.co_varnames}")
    print(f"  outer.__code__.co_cellvars   {outer.__code__.co_cellvars}")
    print(f"  inner.co_freevars            {inner_code.co_freevars}")
    print("\n  box не попал в co_varnames, хотя присваивается в outer: компилятор")
    print("  увидел, что его берёт вложенная функция, и перевёл его в ячейку.")
    print("  Решение принято ОДИН РАЗ, при компиляции, и по коду видно, какое:")
    print("\n  в outer:")
    for ins in dis.get_instructions(outer):
        if ins.opname in ("MAKE_CELL", "STORE_DEREF") and ins.argrepr == "box":
            print(f"    {ins.opname} {ins.argrepr}".rstrip())
    print("  в inner:")
    for ins in dis.get_instructions(inner_code):
        if ins.opname in ("COPY_FREE_VARS", "LOAD_DEREF"):
            print(f"    {ins.opname} {ins.argrepr}".rstrip())
    print("\n  MAKE_CELL заводит коробку при входе в outer, STORE_DEREF кладёт в")
    print("  неё тройку, COPY_FREE_VARS отдаёт ту же коробку в inner, LOAD_DEREF")
    print("  достаёт из неё значение. Ни на одном шаге значение не копируется.")

    head(5, "ЯЧЕЙКА ПЕРЕЖИВАЕТ КАДР, В КОТОРОМ РОДИЛАСЬ")
    def short_lived():
        temp = "значение из функции, которая уже вернулась"

        def keeper():
            return temp

        return keeper

    keeper = short_lived()
    print(f"  функция short_lived вернулась, её кадра больше нет")
    print(f"  keeper() возвращает: {keeper()!r}")
    print(f"  keeper.__closure__[0].cell_contents живо: "
          f"{keeper.__closure__[0].cell_contents is not None}")
    print("\n  Вот зачем коробка вообще нужна. Кадр функции живёт до возврата,")
    print("  а переменная, взятая замыканием, должна жить дольше — значит, она")
    print("  не может лежать в кадре.")


main()