objwatch.targets module

objwatch.targets.iter_parents(node)

Generator for traversing AST node parent hierarchy.

Yields:

ast.AST – Parent nodes in bottom-up order (nearest ancestor first)

Example

for parent in iter_parents(some_node):

if isinstance(parent, ast.ClassDef):

break

objwatch.targets.set_parents(node, parent)

Recursively set parent references in AST nodes.

Enables parent traversal via node.parent attribute Required for accurate scope determination during analysis

objwatch.targets.deep_merge(source: dict, update: dict) → dict

Recursively merge two dictionaries.

Parameters:

• source – Base dictionary to be updated

• update – Dictionary with update values

Returns:

Reference to the modified source dictionary

class objwatch.targets.Targets(targets: List[str | ModuleType], exclude_targets: List[str | ModuleType] | None = None)

Bases: object

Target processor for monitoring file changes and module structures.

Supported syntax: 1. Module: ‘package.module’ 2. Class: ‘package.module:ClassName’ 3. Class attribute: ‘package.module:ClassName.attribute’ 4. Class method: ‘package.module:ClassName.method()’ 5. Function: ‘package.module:function()’ 6. Global variable: ‘package.module::GLOBAL_VAR’

__init__(targets: List[str | ModuleType], exclude_targets: List[str | ModuleType] | None = None)

Initialize target processor.

Parameters:

• targets – Monitoring targets in various formats

• exclude_targets – Exclusion targets in same formats

_validate_filename_targets()

Validate that no filename target ends with any exclude filename pattern. Collects all validation errors and raises them at once for better diagnostics.

_check_targets(targets: List[str | ModuleType], exclude_targets: List[str | ModuleType] | None) → Tuple[List[str | ModuleType], List[str | ModuleType] | None]

Normalize and validate target inputs.

Parameters:

• targets – Raw monitoring targets input

• exclude_targets – Raw exclusion targets input

Returns:

Normalized (targets, exclude_targets)

Return type:

Tuple[TargetsType, TargetsType]

_process_targets(targets: List[str | ModuleType] | None) → Tuple[dict, Set[str]]

Convert heterogeneous targets to structured data model.

Parameters:

targets – List of targets

Returns:

Hierarchical structure and filename targets

Return type:

Tuple[dict, Set[str]]

_parse_target(target: str | ModuleType | type | LambdaType | MethodType) → tuple

Parse different target formats into module structure.

Parameters:

target – Target specification

Returns:

(module_path, parsed_structure)

Return type:

tuple

_parse_function(func: LambdaType | MethodType) → tuple

Parse function object and create module structure containing this function or method

Parameters:

func – Function object to parse

Returns:

(module name, module structure containing only this function or method)

Return type:

tuple

_parse_module(module: ModuleType) → tuple

Parse module structure using AST analysis.

Parameters:

module – Python module object to analyze

Returns:

(module_name, parsed_structure) pair

Return type:

tuple

_parse_class(cls: type) → tuple

Parse class object and create module structure containing this class

Parameters:

cls – Class object to parse

Returns:

(module name, module structure containing only this class)

Return type:

tuple

_parse_string(target: str) → tuple

Parse string-formatted target definitions

Parameters:

target – Target definition string

Returns:

(module_path, parsed_structure)

Return type:

tuple

_parse_module_by_name(module_name: str, recursive: bool = True) → dict

Locate and parse module structure by its import name, supporting recursive parsing.

Parameters:

• module_name – Full dotted import path (e.g. ‘package.module’)

• recursive – Whether to recursively parse submodules

Returns:

Parsed module structure with submodules if recursive=True

Return type:

dict

_parse_py_file(file_path: str) → dict

Analyze Python file structure using Abstract Syntax Tree.

Parameters:

file_path – Absolute path to Python file

Returns:

Parsed file structure dictionary

Return type:

dict

Raises:

Logs error on parsing failure –

_extract_class_attributes(class_node: ClassDef) → List[str]

Extract class attributes from AST node.

Includes: - Assignment statements - Annotated assignments

_flatten_module_structure(module_path: str, module_structure: dict, result: dict)

Flatten nested module structure into a dict.

Parameters:

• module_path – Full module path

• module_structure – Module structure dictionary

• result – dict to populate

_process_assignment(node: Assign, result: dict)

Extract global variables from assignment AST nodes.

Handles two patterns: 1. Simple assignments: var = value 2. Tuple unpacking: a, b = (1, 2)

Parameters:

• node – AST assignment node to analyze

• result – dict to update with found globals

get_targets() → dict

Retrieve targets.

Returns:

Target dictionary containing:

• classes: Class methods

• functions: Functions

• globals: Global variables

Return type:

dict

Example

{

‘module.path’: {

‘classes’: {

‘ClassName’: {

‘methods’: […], ‘attributes’: […]

}

}, ‘functions’: […], ‘globals’: […]

}

}

get_exclude_targets() → dict

Retrieve excluded targets.

Returns:

Exclude dictionary containing:

• classes: Excluded class methods

• functions: Excluded functions

• globals: Excluded global variables

Return type:

dict

Example

{

‘module.path’: {

‘classes’: {

‘ClassName’: {

‘methods’: […], ‘attributes’: […]

}

}, ‘functions’: […], ‘globals’: […]

}

}

get_filename_targets() → Set

Get monitored filesystem paths. Path matching is determined using string.endswith() method.

Returns:

Paths to Python files being monitored

Return type:

Set[str]

get_exclude_filename_targets() → Set

Get monitored excluded filesystem paths. Path matching is determined using string.endswith() method.

Returns:

Paths to Python files being excluded

Return type:

Set[str]

static serialize_targets(targets: dict, indent=2)

Serialize objects that JSON cannot handle by default.

Converts sets to lists, and other objects to their __dict__ or string representation. If the input is a dictionary with more than 8 top-level keys, only the keys are retained with a placeholder value and a warning message is added.

Parameters:

indent – Number of spaces for JSON indentation

Returns:

JSON serialized string

Return type:

str