objwatch.tracer module

class objwatch.tracer.Tracer(config: ObjWatchConfig)

Bases: object

Tracer class to monitor and trace function calls, returns, and variable updates within specified target modules.

__init__(config: ObjWatchConfig) → None

Initialize the Tracer with configuration parameters.

Parameters:

config (ObjWatchConfig) – Configuration parameters for ObjWatch.

property call_depth: int

_build_target_index()

Build fast lookup indexes for monitoring targets.

Creates three-level indexes: - module_index: Set of monitored module names - class_index: Nested mapping of modules to their classes - function_index: Nested mapping of modules to their functions - global_index: Nested mapping of modules to their global variables

Final structure example: index_map = {

‘class’: {‘module1’: {‘ClassA’, ‘ClassB’}, …}, ‘function’: {‘module1’: {‘func1’, ‘func2’}, …}, ‘global’: {‘module1’: {‘var1’, ‘var2’}, …}

}

_build_exclude_index()

Build indexes for exclusion targets to handle track_all scenarios.

load_wrapper(wrapper)

Load a custom function wrapper if provided.

Parameters:

wrapper – The custom wrapper to load.

Returns:

The initialized wrapper or None.

_should_trace_module(module: str) → bool

Check if a module is within monitoring scope.

Parameters:

module (str) – Full module name to check

Returns:

True if the module is in monitoring targets

Return type:

bool

_should_trace_class(module: str, class_name: str) → bool

Check if a specific class should be traced.

Parameters:

• module (str) – Parent module name

• class_name (str) – Class name to check

Returns:

True if the class should be traced

Return type:

bool

_should_trace_method(module: str, class_name: str, method_name: str) → bool

Check if a specific method should be traced.

Parameters:

• module (str) – Parent module name

• class_name (str) – Class name containing the method

• method_name (str) – Method name to check

Returns:

True if the method should be traced

Return type:

bool

_should_trace_attribute(module: str, class_name: str, attr_name: str) → bool

Check if a specific attribute should be traced.

Parameters:

• module (str) – Parent module name

• class_name (str) – Class name containing the attribute

• attr_name (str) – Attribute name to check

Returns:

True if the attribute should be traced

Return type:

bool

_should_trace_function(module: str, func_name: str) → bool

Check if a specific function should be traced.

Parameters:

• module (str) – Parent module name

• func_name (str) – Function name to check

Returns:

True if the function should be traced

Return type:

bool

_should_trace_global(module: str, global_name: str) → bool

Check if a specific global variable should be traced.

Parameters:

• module (str) – Parent module name

• global_name (str) – Global variable name to check

Returns:

True if the global variable should be traced

Return type:

bool

_filename_endswith(filename: str) → bool

Check if the filename does not end with any of the target extensions.

Parameters:

filename (str) – The filename to check.

Returns:

True if the filename does not end with the target extensions, False otherwise.

Return type:

bool

_should_trace_frame(frame: FrameType) → bool

Determine if a stack frame should be traced.

Parameters:

frame (FrameType) – Execution frame to evaluate

Returns:

True if tracing should occur for this frame

Return type:

bool

_check_global_changes(frame: FrameType) → bool

Detect monitored global variables in current frame.

Parameters:

frame (FrameType) – Execution frame containing globals

Returns:

True if any tracked global variables exist

Return type:

bool

_update_objects_lens(frame: FrameType) → None

Update tracked objects’ sequence-type attribute lengths.

Parameters:

frame (FrameType) – Current stack frame to inspect.

_get_function_info(frame: FrameType) → dict

Extract information about the currently executing function.

Parameters:

frame (FrameType) – The current stack frame.

Returns:

Dictionary containing function information.

Return type:

dict

_handle_change_type(lineno: int, class_name: str, key: str, old_value: Any | None, current_value: Any, old_value_len: int | None, current_value_len: int | None) → None

Helper function to handle the change type for both object attributes and local variables.

Parameters:

• lineno (int) – Line number where the change occurred.

• class_name (str) – Class name if the change relates to an object attribute.

• key (str) – The key (variable or attribute) being tracked.

• old_value (Optional[Any]) – The old value of the variable or attribute.

• current_value (Any) – The current value of the variable or attribute.

• old_value_len (Optional[int]) – The length of the old value (if applicable).

• current_value_len (Optional[int]) – The length of the current value (if applicable).

_track_object_change(frame: FrameType, lineno: int)

Handle changes in object attributes and track updates.

Parameters:

• frame (FrameType) – The current stack frame.

• lineno (int) – The line number where the change occurred.

_track_locals_change(frame: FrameType, lineno: int)

Handle changes in local variables and track updates.

Parameters:

• frame (FrameType) – The current stack frame.

• lineno (int) – The line number where the change occurred.

_track_globals_change(frame: FrameType, lineno: int)

Handle changes in global variables and track updates.

Parameters:

• frame (FrameType) – The current stack frame.

• lineno (int) – The line number where the change occurred.

trace_factory()

Create the tracing function to be used with sys.settrace.

Returns:

The trace function.

start() → None

Start the tracing process by setting the trace function.

stop() → None

Stop the tracing process by removing the trace function and saving XML logs.