"""Когда `PyFrameObject` действительно появляется.

Статья говорит, что данные вызова лежат в `_PyInterpreterFrame`, а
объект-фрейм (`types.FrameType`) надстраивается лениво. Скрипт показывает
запуском, **когда именно** эта надстройка происходит и во что обходится:

  1. `sys._getframe()` — материализация по требованию, ровно один объект на
     вызов: второй `sys._getframe()` в том же кадре возвращает тот же объект;
  2. `f_back` / `sys._getframe(depth)` — материализация предков по цепочке;
  3. `sys.setprofile` и `sys.settrace` — объект-фрейм выдаётся на **каждый**
     вызов, даже если код о фреймах ничего не знает;
  4. исключение — фреймы всей цепочки материализуются в traceback;
  5. генератор — `gi_frame` материализуется при обращении и живёт с генератором.

Цена меряется разностями внутри одного прогона; абсолютные наносекунды
привязаны к машине.

    for v in 3.12 3.13 3.14; do python$v bench/interpreter-loop/frame_materialization.py; done
"""
import sys
import timeit
import types

REPEAT = 5
NUMBER = 200_000


def ns(fn, number=NUMBER, repeat=REPEAT):
    return min(timeit.repeat(fn, number=number, repeat=repeat)) / number * 1e9


# --- 1. материализация по требованию и кеширование --------------------------

def once_per_frame():
    a = sys._getframe()
    b = sys._getframe()
    return a is b, type(a).__name__


def parents_are_lazy():
    def inner():
        return (sys._getframe(1) is sys._getframe().f_back,
                type(sys._getframe().f_back).__name__)
    return inner()


# --- 2. цена ----------------------------------------------------------------

def bare():
    return 1


def with_getframe():
    sys._getframe()
    return 1


def with_getframe_twice():
    sys._getframe()
    sys._getframe()
    return 1


def with_f_back():
    sys._getframe().f_back
    return 1


def call_costs():
    """Разложение цены: пустой вызов, первый _getframe, второй, f_back."""
    t_bare = ns(bare)
    t_one = ns(with_getframe)
    t_two = ns(with_getframe_twice)
    t_back = ns(with_f_back)
    return {
        "пустой вызов": t_bare,
        "+ первый sys._getframe() (материализация)": t_one - t_bare,
        "+ второй sys._getframe() (объект уже есть)": t_two - t_one,
        "+ .f_back (вызывающий уже материализован)": t_back - t_one,
    }


# --- 3. хуки: фрейм выдаётся на каждый вызов --------------------------------

def hook_costs():
    seen_profile = set()
    seen_trace = set()

    def profiler(frame, event, arg):
        if event == "call":
            seen_profile.add(id(frame))

    def tracer(frame, event, arg):
        if event == "call":
            seen_trace.add(id(frame))
        return None                      # без построчной трассировки

    def tracer_lines(frame, event, arg):
        return tracer_lines                # с построчной

    n_small = 20_000
    t_plain = ns(bare, number=n_small)

    sys.setprofile(profiler)
    t_profile = ns(bare, number=n_small)
    sys.setprofile(None)

    sys.settrace(tracer)
    t_trace = ns(bare, number=n_small)
    sys.settrace(None)

    sys.settrace(tracer_lines)
    t_trace_lines = ns(bare, number=n_small)
    sys.settrace(None)

    return {
        "без хуков": t_plain,
        "sys.setprofile": t_profile,
        "sys.settrace (только call)": t_trace,
        "sys.settrace (+ построчно)": t_trace_lines,
    }, len(seen_profile), len(seen_trace)


def distinct_frames_per_call(n=5):
    """Сколько РАЗНЫХ объектов-фреймов профайлер получает на n вызовов.

    id() переиспользуется после освобождения объекта, поэтому фреймы
    удерживаются ссылкой — иначе счёт был бы занижен.
    """
    kept = []

    def profiler(frame, event, arg):
        if event == "call" and frame.f_code.co_name == "target":
            kept.append(frame)

    def target():
        return 1

    sys.setprofile(profiler)
    for _ in range(n):
        target()
    sys.setprofile(None)
    return len(kept), len({id(f) for f in kept})


# --- 4. исключение --------------------------------------------------------

def traceback_frames(depth=5):
    def deep(k):
        if k:
            return deep(k - 1)
        raise ValueError("проба")

    try:
        deep(depth)
    except ValueError as exc:
        tb = exc.__traceback__
        frames = []
        while tb is not None:
            frames.append(tb.tb_frame)
            tb = tb.tb_next
        return len(frames), all(isinstance(f, types.FrameType) for f in frames)


# --- 5. генератор ---------------------------------------------------------

def generator_frame():
    def gen():
        yield 1

    g = gen()
    first = g.gi_frame
    second = g.gi_frame
    kind = type(first).__name__
    list(g)
    return kind, first is second, g.gi_frame


def main():
    print("PY", sys.version.split()[0])
    print("Время сравнивается только между строками этого прогона.")
    print()

    same, kind = once_per_frame()
    print("1. Материализация по требованию")
    print(f"   тип, который возвращает sys._getframe()  : {kind}")
    print(f"   два вызова в одном кадре — один объект   : {same}")
    same_back, back_kind = parents_are_lazy()
    print(f"   sys._getframe(1) is _getframe().f_back   : {same_back} ({back_kind})")
    print()

    print("2. Из чего складывается цена, нс")
    for label, value in call_costs().items():
        print(f"   {label:<44} {value:8.1f}")
    print()

    print("3. Под хуками фрейм выдаётся на каждый вызов, нс на вызов")
    costs, n_profile, n_trace = hook_costs()
    base = costs["без хуков"]
    for label, value in costs.items():
        print(f"   {label:<30} {value:9.1f}   x{value / base:6.1f}")
    n_calls, n_distinct = distinct_frames_per_call()
    print(f"   вызовов target(): {n_calls}, разных объектов-фреймов у профайлера:"
          f" {n_distinct}")
    print("   Это и есть ответ «когда»: под профайлером и отладчиком ленивость")
    print("   кончается — объект строится на каждый вызов, включая те, где он не нужен.")
    print()

    n_tb, all_frames = traceback_frames()
    print("4. Исключение")
    print(f"   звеньев traceback на глубине 5+1        : {n_tb}")
    print(f"   каждое звено держит объект-фрейм        : {all_frames}")
    print()

    kind_g, same_g, after = generator_frame()
    print("5. Генератор")
    print(f"   gi_frame тип                            : {kind_g}")
    print(f"   два обращения — один объект             : {same_g}")
    print(f"   gi_frame после исчерпания               : {after}")


if __name__ == "__main__":
    main()