"""
Замер и наблюдение для урока «Замыкания и области видимости».

ЗАПУСК (числа урока сняты на 3.13.7):

    for v in 3.12 3.13 3.14; do python$v bench/closures/scopes.py; done

ЧТО ЗДЕСЬ ДВЕ РАЗНЫЕ ВЕЩИ, И ИХ НЕЛЬЗЯ ПУТАТЬ.

НАБЛЮДЕНИЯ (разделы 1-5) — про устройство: какие опкоды порождает компилятор,
что лежит в `__closure__`, где проходит граница областей. Они не зависят от
машины и обязаны совпадать у любого, кто запустит скрипт на той же версии.

ЗАМЕР (раздел 6) — про время, и он от машины зависит. Сравнивать его можно
только между строками ОДНОГО запуска: три вида доступа к имени меряются подряд,
в одинаковых условиях. Сравнивать абсолютные наносекунды с другой машиной или
между версиями бессмысленно — 3.12 собран GCC, а 3.13 и 3.14 Clang.

ПОЧЕМУ ДОСТУП МЕРЯЕТСЯ БЕЗ ЦИКЛА. Первая версия замера ставила обращение внутрь
`for` — и разница утонула: на каждое обращение приходились ещё итерация, сложение
и проверка границы, то есть мерился в основном цикл. Здесь тело функции — двести
обращений к одному имени подряд, сложенных в одно выражение, и накладного расхода
на них почти нет.
"""

import dis
import sys
import timeit


def header(title: str) -> None:
    print(f"\n--- {title} ---")


def observe_cells() -> None:
    """Ячейка: кто её заводит, кто на неё ссылается, и одна ли она на всех."""
    header("1. Ячейки замыкания")

    def outer():
        x = 1

        def inner():
            return x

        return inner

    inner = outer()
    print(f"  co_cellvars у внешней   : {outer.__code__.co_cellvars}")
    print(f"  co_freevars у внутренней: {inner.__code__.co_freevars}")
    print(f"  cell_contents           : {inner.__closure__[0].cell_contents}")

    def two():
        x = 1

        def a():
            return x

        def b():
            return x

        return a, b

    a, b = two()
    # Ключевой факт урока: ячейка ОДНА, а не по копии на функцию.
    print(f"  одна ячейка у двух функций: {a.__closure__[0] is b.__closure__[0]}")

    def plain():
        def f():
            return 42

        return f

    print(f"  __closure__ без свободных переменных: {plain().__closure__}")


def observe_runtime_resolution() -> None:
    """Захвачена ПЕРЕМЕННАЯ, а не значение: свободное имя читается при вызове."""
    header("2. Свободное имя читается во время выполнения")

    def make():
        v = "первое"

        def show():
            return v

        v = "второе"  # меняем ПОСЛЕ создания show
        return show

    print(f"  значение менялось после создания функции, отдаётся: {make()()!r}")


def observe_local_trap() -> None:
    """Присваивание где угодно в теле делает имя локальным для ВСЕГО тела."""
    header("3. Ловушка локального имени")

    x = "из объемлющей"  # noqa: F841 — нужна, чтобы показать, что её не видно

    def trap_real():
        try:
            value = x
        except UnboundLocalError as exc:
            return f"UnboundLocalError: {exc}"
        x = "локальная"  # noqa: F841
        return value

    print(f"  {trap_real()}")
    # Решение принято КОМПИЛЯТОРОМ: имя лежит в co_varnames, а не в co_names.
    print(f"  co_varnames: {trap_real.__code__.co_varnames}")


def observe_class_skip() -> None:
    """Тело класса пропускается в цепочке областей (PEP 227)."""
    header("4. Тело класса в цепочку не входит")

    def make():
        x = "из функции"

        class C:
            x = "из класса"

            def get(self):
                return x  # берёт из ФУНКЦИИ, минуя одноимённый атрибут класса

        return C

    print(f"  метод видит: {make()().get()!r}")

    def make_fail():
        class C:
            y = "класс"

            def get(self):
                try:
                    return y
                except NameError as exc:
                    return f"NameError: {exc}"

        return C

    print(f"  имя из тела класса: {make_fail()().get()}")


def observe_bytecode() -> None:
    """Опкоды, которыми ячейка заводится и читается."""
    header("5. Байткод")
    src = "def outer():\n    x = 1\n    def inner():\n        return x\n    return inner\n"
    module = compile(src, "<bench>", "exec")
    outer = next(c for c in module.co_consts if getattr(c, "co_name", None) == "outer")
    inner = next(c for c in outer.co_consts if getattr(c, "co_name", None) == "inner")
    print("  внешняя:")
    for ins in dis.get_instructions(outer):
        print(f"    {ins.opname:24s} {ins.argrepr}")
    print("  внутренняя:")
    for ins in dis.get_instructions(inner):
        print(f"    {ins.opname:24s} {ins.argrepr}")


ACCESS_COUNT = 200


def _body(indent: int) -> str:
    pad = " " * indent
    return pad + "t = " + " + ".join(["x"] * ACCESS_COUNT) + "\n" + pad + "return t\n"


def measure_access() -> None:
    """Сколько стоит обращение к локальной, к ячейке и к глобальной."""
    header(f"6. Цена обращения к имени ({ACCESS_COUNT} обращений в одном вызове)")

    setups = {
        "LOAD_FAST  (локальная)": "def f():\n    x = 1\n" + _body(4),
        "LOAD_DEREF (ячейка)": (
            "def outer():\n    x = 1\n    def f():\n" + _body(8) + "    return f\nf = outer()\n"
        ),
        "LOAD_GLOBAL (глобальная)": "x = 1\ndef f():\n" + _body(4),
    }

    # min из девяти повторов, а не среднее: измеряется нижняя граница, на которую
    # не влияют посторонние процессы. Среднее меряло бы заодно и соседей по машине.
    def one_pass() -> dict[str, float]:
        return {
            name: min(timeit.repeat("f()", setup=setup, number=20_000, repeat=9)) / 20_000
            for name, setup in setups.items()
        }

    # ЗАЧЕМ ВЕСЬ ЗАМЕР ПОВТОРЯЕТСЯ ЦЕЛИКОМ.
    #
    # Урок утверждает не только числа, но и то, КАК их читать: что ячейка и
    # глобальная стоят «примерно одинаково». Такое утверждение держится лишь
    # тогда, когда расстояние между этими двумя строками меньше, чем шатание
    # каждой из них от повтора к повтору. Одиночный прогон этого не знает: он
    # печатает три числа и молчит о том, воспроизводимы ли они. Поэтому весь
    # замер повторяется OUTER раз, и рядом с кратностями печатается размах —
    # чтобы читатель (и следующий правящий эту статью) видел прибор, а не
    # только показание.
    OUTER = 5
    series: dict[str, list[float]] = {name: [] for name in setups}
    for _ in range(OUTER):
        for name, t in one_pass().items():
            series[name].append(t)

    times = {name: min(vals) for name, vals in series.items()}
    base = times["LOAD_FAST  (локальная)"]
    for name, t in times.items():
        per = t / ACCESS_COUNT * 1e9
        print(f"    {name:26s} {t * 1e6:6.2f} мкс   x{t / base:.2f}   {per:5.1f} нс на обращение")

    print(f"\n    РАЗМАХ ПО {OUTER} ПОВТОРАМ ВСЕГО ЗАМЕРА, в кратностях к локальной")
    ratios = {name: sorted(v / base for v in vals) for name, vals in series.items()}
    for name in setups:
        lo, hi = ratios[name][0], ratios[name][-1]
        print(f"    {name:26s} x{lo:.2f} .. x{hi:.2f}   размах {hi - lo:.2f}")

    cell = ratios["LOAD_DEREF (ячейка)"]
    glob = ratios["LOAD_GLOBAL (глобальная)"]
    gap = abs(min(glob) - min(cell))
    spread = max(cell[-1] - cell[0], glob[-1] - glob[0])
    print(f"\n    расстояние между ячейкой и глобальной   {gap:.2f}")
    print(f"    наибольший размах этих же двух строк    {spread:.2f}")
    print(f"    различима ли разница прибором           {'да' if gap > spread else 'нет'}")


def main() -> None:
    print(f"Python {sys.version.split()[0]}")
    observe_cells()
    observe_runtime_resolution()
    observe_local_trap()
    observe_class_skip()
    observe_bytecode()
    measure_access()


if __name__ == "__main__":
    main()