knit_script.debugger.knitscript_frame module

Frame tracking for KnitScript execution tracing.

This module provides frame-level execution tracking for KnitScript programs, similar to how Python’s sys.settrace() provides frame objects during debugging.

class Knit_Script_Frame(scope, parent_frame=None)[source]

Bases: object

Execution frame for KnitScript programs.

This class tracks the execution state of a KnitScript program at a specific point in time, analogous to Python’s frame objects in sys.settrace().

frame_id

Unique identifier for this frame.

Type:: int

parent_frame

Reference to the calling frame.

Type:: Knit_Script_Frame | None

child_frames

List of frames called from this frame.

Type:: list[Knit_Script_Frame]

__init__(scope, parent_frame=None)[source]

Initialize a KnitScript execution frame.

Parameters:

scope (Knit_Script_Scope) – The scope that this frame is being executed in.
parent_frame (Knit_Script_Frame, optional) – Optional parent frame in call stack.

property depth: int

Returns:: The depth of this frame in the call stack.
Return type:: int

Notes

The first frame created when running the file is 0 and the call stack depth increments for the depth of the tree.

property first_statement: Debuggable_Element | None: Returns: Statement | None: The first statement executed in this frame, or None if this frame is empty.

property last_statement: Debuggable_Element | None: Returns: Statement | None: The last statement executed in this frame, or None if this frame is empty.

property first_line_number: int: Returns: int: Line number of the first statement executed in this frame. 0 if no statements have been executed.

property last_line_number: int: Returns: int: Line number of the last statement executed in this frame. 0 if no statements have been executed.

property source_file: str | None: Returns: str | None: The source file of the knitscript being executed or None if it is being executed from a python string.

property is_function: bool: Returns: bool: True if the current frame is execution of a named function. False otherwise.

property function_name: str | None: Returns: str | None: The name of this frame’s scope if it represents a function.

property module_name: str | None: Returns: str | None: The name of this frame’s scope if it represents a module.

property is_module: bool: Returns: bool: True if the current frame is execution of a named module. False otherwise.

get_call_stack()[source]

Get the complete call stack from root to current frame.

Returns:: List of frames from root to current
Return type:: list[Knit_Script_Frame]

is_above(frame)[source]

Parameters:: frame (Knit_Script_Frame) – The other frame to compare depth to.
Returns:: True if this frame is above the other frame in the call stack.
Return type:: bool

is_below(frame)[source]

Parameters:: frame (Knit_Script_Frame) – The other frame to compare depth to.
Returns:: True if this frame is below the other frame in the call stack.
Return type:: bool

same_depth(frame)[source]

Parameters:: frame (Knit_Script_Frame) – The other frame to compare depth to.
Returns:: True if this frame is at the same level as the other frame in the call stack.
Return type:: bool

add_child_frame(child_frame)[source]

Register a child frame that was called from this frame.

Parameters:: child_frame (Knit_Script_Frame) – The child frame to register

add_statement(statement)[source]

Add a statement to the execution history.

Parameters:: statement (Statement) – The statement that was executed to add to the execution history.

get_var(name)[source]

Parameters:: name (str) – Variable name to get from frame’s scope.
Returns:: Variable value
Return type:: Any
Raises:: KeyError – If variable not found in the frame’s scope

has_var(name)[source]

Parameters:: name (str) – Variable name to search for in frame’s scope.
Returns:: True if variable exists in the frame’s scope. False otherwise.
Return type:: bool

__repr__()[source]

String representation of the frame.

Returns:: Formatted string showing frame details
Return type:: str

__str__()[source]

String representation of the frame.

Returns:: Formatted string showing frame details
Return type:: str

__eq__(other)[source]

Compares frames by order in which frames were created.

Parameters:: other (int | Frame) – A frame or a frame id to compare to.
Returns:: True if this frame matches the given frame or frame id. False, otherwise.
Return type:: bool

__lt__(other)[source]

Compares frames by order in which frames were created.

Parameters:: other (int | Frame) – A frame or a frame id to compare to.
Returns:: If this frame comes before the other frame.
Return type:: bool
Raises:: TypeError – If the item to compare to is not a frame or an integer.