Runtime Probe

A helper module that runs a callable under interpreter tracing and reports runtime activity plus garbage collector state.

Capabilities

Captures execution timeline

• Running run_with_probe on a callable returns events capturing "call", "line", "return", "exception" in order, each with function name, file path, and line number. @test
• Line events are only recorded when capture_lines is True and skipped when False. @test

Garbage collector accounting

• run_with_probe(..., force_collection=True) triggers a collection before running the target and records updated collection counts in gc_after while preserving previous counts in gc_before. @test
• When disable_gc=True, garbage collection is disabled during target execution, then restored to its prior enabled/disabled state afterward. @test

Exception reporting

• If the target raises, the report records the exception message and includes an "exception" event with the failing function and line; returned is None and raised flag is True. @test

Implementation

@generates

API

from typing import Any, Callable, Dict, List, Optional, Sequence, TypedDict

class TraceEvent(TypedDict):
    event: str              # "call" | "line" | "return" | "exception"
    function: str           # function name
    file: str               # absolute file path
    line: int               # line number associated with the event

class RunReport(TypedDict, total=False):
    events: List[TraceEvent]
    gc_before: Dict[str, int]    # collection counts per generation
    gc_after: Dict[str, int]
    gc_thresholds: Sequence[int] # thresholds snapshot before run
    gc_forced: bool
    gc_disabled_during_run: bool
    returned: Any
    raised: bool
    exception_message: Optional[str]

def run_with_probe(
    target: Callable[..., Any],
    *,
    args: Sequence[Any] = (),
    kwargs: Optional[Dict[str, Any]] = None,
    capture_lines: bool = True,
    force_collection: bool = False,
    disable_gc: bool = False,
) -> RunReport:
    ...

Dependencies { .dependencies }

cpython { .dependency }

Provides interpreter tracing hooks, profiling callbacks, and garbage collector controls required for runtime observation.