CodeBlock

Container class for a list of code Statements that share an indentation level, e.g. a function body or class body. Enables various types of queries and operations on the code block.

Inherits from

Expression, Editable

Properties

---

assignment_statements

Returns list of top level assignment statements in the code block.

Retrieves all statements in the code block whose type is AssignmentStatement. These statements represent direct assignments at the current code block level (not nested within other blocks).

Returns: list[AssignmentStatement[Parent, Self]]: A list of assignment statements found at the top level of the code block.

def assignment_statements(self) -> list[AssignmentStatement[Parent, Self]]:
    ...

assignments

Returns all assignments in the code block across all nesting levels.

Gets every assignment from every assignment statement in the code block, including assignments in nested blocks.

Returns: list[Assignment[Parent, Self]]: A list of Assignment objects from all nested levels of the code block.

def assignments(self) -> list[Assignment[Parent, Self]]:
    ...

attributes

Returns a list of top level class attribute statements in the code block.

Get all attribute statements (Attribute objects) that are direct children of the current code block. These represent class-level attribute declarations.

Returns: list[Attribute[Parent, Self]]: A list of Attribute objects representing the class-level attributes, ordered by their appearance in the code block.

def attributes(self) -> list[Attribute[Parent, Self]]:
    ...

comments

Gets list of top level comments in the code block.

Returns a list of comment statements that occur at the top level of this code block. Does not include nested comments.

Returns: list[Comment[Parent, Self]]: A list of Comment objects that are immediate children of this code block.

def comments(self) -> list[Comment[Parent, Self]]:
    ...

extended

Returns a SymbolGroup of all extended nodes associated with this element.

Creates a SymbolGroup that provides a common interface for editing all extended nodes, such as decorators, modifiers, and comments associated with the element.

Args: None

Returns: SymbolGroup: A group containing this node and its extended nodes that allows batch modification through a common interface.

def extended(self) -> SymbolGroup:
    ...

extended_source

Returns the source text representation of all extended nodes.

Gets the source text of all extended nodes combined. This property allows reading the source text of all extended nodes (e.g. decorators, export statements) associated with this node.

Returns: str: The combined source text of all extended nodes.

def extended_source(self) -> str:
    ...

file

The file object that this Editable instance belongs to.

Retrieves or caches the file object associated with this Editable instance.

Returns: File: The File object containing this Editable instance.

def file(self) -> SourceFile:
    ...

filepath

The file path of the file that this Editable instance belongs to.

Returns a string representing the absolute file path of the File that contains this Editable instance.

Returns: str: The absolute file path.

def filepath(self) -> str:
    ...

function_calls

Returns a list of all function calls in the code block.

Gets a list of all function calls in the code block, including those within nested statements. The function calls are ordered by their appearance in the code block.

Returns: list[FunctionCall]: A list of FunctionCall objects representing all function calls in the code block.

def function_calls(self) -> list[FunctionCall]:
    ...

if_blocks

Returns a list of top level if statements in the code block.

A property that retrieves all the immediate if statements within this code block. These are if statements that exist at the same indentation level as other statements in the block, not nested ones.

Returns: list[IfBlockStatement[Parent, Self]]: A list of top-level if statement objects in the code block.

def if_blocks(self) -> list[IfBlockStatement[Parent, Self]]:
    ...

local_var_assignments

Returns all local variable assignment in the code block, for all nest levels.

A property that returns all variable assignments that are marked as local variables within the code block, including assignments in nested code blocks.

Returns: list[Assignment[Parent, Self]]: A list of Assignment objects representing local variable assignments.

def local_var_assignments(self) -> list[Assignment[Parent, Self]]:
    ...

resolved_value

Returns the resolved value of an Expression.

Returns the last assigned expression value if the expression is resolvable, otherwise returns itself. For example, if ‘b = a’ where ‘a = 1’, resolving ‘b’ returns 1.

Returns: Union[Expression, list[Expression]]: The resolved expression value(s). Returns a single Expression if there is only one resolved value, or a list of Expressions if there are multiple resolved values. Returns self if the expression is not resolvable or has no resolved types.

def resolved_value(self) -> Expression | list[Expression]:
    ...

return_statements

Gets all return statements at the top level of the code block.

Args: None

Returns: list[ReturnStatement[Parent, Self]]: A list of return statements that appear at the top level of the code block. Does not include return statements in nested blocks.

def return_statements(self) -> list[ReturnStatement[Parent, Self]]:
    ...

source

Text representation of the Editable instance.

Returns the source text of the Editable instance. This is the main property used to access the text content of any code element in GraphSitter.

Returns: str: The text content of this Editable instance.

def source(self) -> str:
    ...

statements

Gets a view of the top-level statements in the code block.

Returns a collection of statements that appear directly in this code block, ordered by their appearance. This does not include statements nested within other blocks (e.g., if statements, functions).

Returns: MultiLineCollection[Statement, Self]: An ordered collection of top-level statements in the code block.

def statements(self) -> MultiLineCollection[Statement, Self]:
    ...

symbol_statements

Returns list of top level symbol statements in the code block.

Retrieves all statements in the block that have a statement type of SYMBOL_STATEMENT. Symbol statements are statements that declare or manipulate symbols like functions or classes.

Returns: list[SymbolStatement]: A list of all the symbol statements at the top level of this code block.

def symbol_statements(self) -> list[SymbolStatement]:
    ...

variable_usages

Returns Editables for all TreeSitter node instances of variable usages within this node’s scope.

This method finds all variable identifier nodes in the TreeSitter AST, excluding:

• Function names in function calls
• Import names in import statements
• Property access identifiers (except the base object)
• Keyword argument names (in Python and TypeScript)

This is useful for variable renaming and usage analysis within a scope.

Returns: list[Editable]: A list of Editable nodes representing variable usages. Each Editable corresponds to a TreeSitter node instance where the variable is referenced.

def variable_usages(self) -> list[Editable]:
    ...

Methods

---

commit

Commits any pending transactions for the current node to the codebase.

Commits only the transactions that affect the file this node belongs to. This is useful when you want to commit changes made to a specific node without committing all pending transactions in the codebase.

Args: None

Returns: None

def commit(self) -> None:
    ...

edit

Replace the source of this Editable with new_src.

Replaces the text representation of this Editable instance with new text content. The method handles indentation adjustments and transaction management.

Args: new_src (str): The new source text to replace the current text with. fix_indentation (bool): If True, adjusts the indentation of new_src to match the current text’s indentation level. Defaults to False. priority (int): The priority of the edit transaction. Higher priority edits are applied first. Defaults to 0. dedupe (bool): If True, deduplicates identical transactions. Defaults to True.

Returns: None

def edit(self, new_src: str, fix_indentation: bool = False, priority: int = 0, dedupe: bool = True) -> None:
    ...

find

Find and return matching nodes or substrings within an Editable instance.

This method searches through the extended_nodes of the Editable instance and returns all nodes or substrings that match the given search criteria.

Args: strings_to_match (Union[list[str], str]): One or more strings to search for. exact (bool): If True, only return nodes whose source exactly matches one of the strings_to_match. If False, return nodes that contain any of the strings_to_match as substrings. Defaults to False.

Returns: list[Editable]: A list of Editable instances that match the search criteria.

def find(self, strings_to_match: list[str] | str, *, exact: bool = False) -> list[Editable]:
    ...

find_string_literals

Returns a list of string literals within this node’s source that match any of the given strings.

Args: strings_to_match (list[str]): A list of strings to search for in string literals. fuzzy_match (bool): If True, matches substrings within string literals. If False, only matches exact strings. Defaults to False.

Returns: list[Editable]: A list of Editable objects representing the matching string literals.

def find_string_literals(self, strings_to_match: list[str], fuzzy_match: bool = False) -> list[Editable]:
    ...

flag

Adds a visual flag comment to the end of this Editable’s source text.

Flags this Editable by appending a comment with emoji flags at the end of its source text. This is useful for visually highlighting specific nodes in the source code during development and debugging.

Returns: None

def flag(self, **kwargs: Unpack[FlagKwargs]) -> CodeFlag[Self]:
    ...

get_assignments

Returns a list of assignments with the specified variable name.

Returns all assignments in the code block that match the given variable name.

Args: var_name (str): The name of the variable to find assignments for.

Returns: list[Assignment[Parent, Self]]: A list of Assignment objects that match the variable name.

def get_assignments(self, var_name: str, *, fuzzy: bool = False, parameters: bool = False) -> list[Assignment[Parent, Self]]:
    ...

get_attributes

Returns attributes from the code block, with the option to include or exclude private attributes.

Retrieves a list of top level attribute statements from the code block, filtering based on the private parameter. When private is True, both private and public attributes are returned. When private is False, only public attributes are returned.

Args: private (bool): Whether to include private attributes in the returned list. If True, returns both private and public attributes. If False, returns only public attributes.

Returns: list[Attribute[Parent, Self]]: A list of attribute statements matching the privacy criteria.

def get_attributes(self, private: bool) -> list[Attribute[Parent, Self]]:
    ...

get_comment

Gets the first comment statement containing a specific text string.

Searches through all nested statement levels in the code block to find a comment that contains the specified text.

Args: comment_src (str): The text string to search for within comment statements.

Returns: Comment[Parent, Self] | None: The first comment statement containing the search text, or None if no matching comment is found.

def get_comment(self, comment_src: str) -> Comment[Parent, Self] | None:
    ...

get_local_var_assignment

Returns the first code statement that assigns a local variable with the specified name.

Searches through all local variable assignments in the code block and returns the first one that matches the given variable name.

Args: var_name (str): The name of the local variable to search for.

Returns: Assignment[Parent, Self] | None: The first matching local variable assignment, or None if no match is found.

def get_local_var_assignment(self, var_name: str) -> Assignment[Parent, Self] | None:
    ...

get_local_var_assignments

Returns all instances of local variable assignments that match the specified variable name.

Finds local variable assignments within the code block that match the provided variable name, with optional fuzzy matching.

Args: var_name (str): The name of the local variable to search for. fuzzy_match (bool, optional): If True, matches variables whose names contain var_name. If False, only matches exact variable names. Defaults to False.

Returns: list[Assignment[Parent, Self]]: List of Assignment objects representing local variable assignments that match the specified name criteria.

def get_local_var_assignments(self, var_name: str, fuzzy_match: bool = False) -> list[Assignment[Parent, Self]]:
    ...

get_statements

Returns all statements of a given type up to the specified block level.

This method retrieves statements from the code block and its nested blocks. Statements can be filtered by type and depth.

Args: statement_type (StatementType | None): The type of statements to return. If None, returns all statement types. max_level (int | None): The maximum block depth level to search. If None, searches all levels.

Returns: list[Statement[Parent, Self]]: A sorted list of matching statements.

def get_statements(self, statement_type: StatementType | None = None, max_level: int | None = None) -> list[Statement[Parent, Self]]:
    ...

get_variable_usages

Returns all instances of variable usages in a code block.

This method searches through all statements in the code block to find variable usages that match the specified variable name. Variable usages are instances where the variable is referenced or used in expressions, function calls, or other code constructs.

Args: var_name (str): The name of the variable to search for. fuzzy_match (bool): When True, matches on variable names that contain var_name. When False (default), only matches exact variable names.

Returns: list[Editable[Self]]: A sorted list of variable usage instances as Editable objects.

def get_variable_usages(self, var_name: str, fuzzy_match: bool = False) -> list[Editable[Self]]:
    ...

indent

Adjusts the indentation level of the entire code block.

Modifies the indentation of all lines in the code block by adding or removing spaces at the start of each line. The amount of indentation per level is determined by either the existing indentation level or defaults to 4 spaces.

Args: level (int): The number of indentation levels to adjust. Positive values indent right, negative values indent left.

Returns: None

def indent(self, level: int) -> None:
    ...

insert_after

Inserts source code at the bottom of the code block.

This method is deprecated. Use self.statements.append(...) instead.

Args: new_src (str): The source code to insert. fix_indentation (bool): Whether to fix the indentation of the inserted code. Defaults to True. newline (bool): Whether to add a newline before the inserted code. Defaults to True.

Returns: None

def insert_after(self, new_src: str, fix_indentation=True, newline=True) -> None:
    ...

insert_before

Inserts new source code at the top of the code block.

This method has been deprecated in favor of using self.statements.insert(0, ...).

Args: new_src (str): The source code to insert at the top of the code block.

Returns: None

def insert_before(self, new_src: str) -> None:
    ...

reduce_condition

Reduces an editable to the following condition

def reduce_condition(self, bool_condition: bool, node: Editable | None = None) -> None:
    ...

remove

Deletes this Node and its related extended nodes (e.g. decorators, comments).

Removes the current node and its extended nodes (e.g. decorators, comments) from the codebase. After removing the node, it handles cleanup of any surrounding formatting based on the context.

Args: delete_formatting (bool): Whether to delete surrounding whitespace and formatting. Defaults to True. priority (int): Priority of the removal transaction. Higher priority transactions are executed first. Defaults to 0. dedupe (bool): Whether to deduplicate removal transactions at the same location. Defaults to True.

Returns: None

def remove(self, delete_formatting: bool = True, priority: int = 0, dedupe: bool = True) -> None:
    ...

rename_variable_usages

Renames all instances of variable usages in the code block.

This method modifies variable usages in the code block by replacing occurrences of the old variable name with a new one. It uses get_assignments() and rename() internally to find all instances of the variable.

Args: old_var_name (str): The current name of the variable to rename. new_var_name (str): The new name to give the variable. fuzzy_match (bool): When True, matches variables containing old_var_name. When False, only exact matches. Defaults to False.

Returns: None: This method mutates the code block in place.

def rename_variable_usages(self, old_var_name: str, new_var_name: str, fuzzy_match: bool = False) -> None:
    ...

replace

Search and replace occurrences of text within this node’s source and its extended nodes.

This method performs string replacement similar to Python’s string.replace(), with support for regex patterns. It operates on both the main node and any extended nodes (e.g. decorators, exports).

Args: old (str): The text or pattern to search for. new (str): The text to replace matches with. count (int, optional): Maximum number of replacements to make. Defaults to -1 (replace all). is_regex (bool, optional): Whether to treat ‘old’ as a regex pattern. Defaults to False. priority (int, optional): Priority of the replacement operation. Defaults to 0.

Returns: int: The total number of replacements made.

Raises: ValueError: If there are multiple occurrences of the substring in a node’s source.

def replace(self, old: str, new: str, count: int = -1, is_regex: bool = False, priority: int = 0) -> int:
    ...

search

Returns a list of all regex match of regex_pattern, similar to python’s re.search().

Searches for matches of a regular expression pattern within the text of this node and its extended nodes.

Args: regex_pattern (str): The regular expression pattern to search for. include_strings (bool): When False, excludes the contents of string literals from the search. Defaults to True. include_comments (bool): When False, excludes the contents of comments from the search. Defaults to True.

Returns: list[Editable]: A list of Editable objects corresponding to the matches found.

def search(self, regex_pattern: str, include_strings: bool = True, include_comments: bool = True) -> list[Editable]:
    ...

unwrap

Extracts a code block from its parent wrapper container by removing the wrapping statement and adjusting indentation.

This method unwraps a code block from its parent container (like if statements, with statements, function definitions, etc.) by removing the parent wrapper code and unindenting the block content.

This method handles two cases:

1. When the wrapper is the only statement on its line
2. When the wrapper shares a line with other statements

For example, transforming: if a: return b into: return b

Args: None

Returns: None

def unwrap(self) -> None:
    ...

wrap

Wraps a code block with a statement and indents it.

This method wraps an existing code block with a preceding statement (and optionally a following statement), and indents the block appropriately. Common use cases include wrapping code blocks with if statements, try/except blocks, with statements, or other control flow structures.

Args: before_src (str): The source code to insert before the block. after_src (str): The source code to insert after the block. Defaults to an empty string.

Returns: None

def wrap(self, before_src: str, after_src: str = "") -> None:
    ...