PyCommentGroup

A group of related symbols that represent a comment or docstring in Python For example: # Comment 1 # Comment 2 # Comment 3 would be 3 individual comments (accessible via symbols), but together they form a CommentGroup (accessible via self).

Inherits from

CommentGroup, SymbolGroup, Editable

Properties

---

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 contained within this expression.

Traverses the extended nodes of this expression to find all function calls within it. This is useful for tasks like analyzing call patterns or renaming function invocations.

Returns: list[FunctionCall]: A list of FunctionCall objects representing all function calls contained within this expression.

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

next_named_sibling

Returns the next named sibling of the symbol group.

Returns the next named sibling node of the last symbol in the group. A named sibling is a node that has a name field in the syntax tree.

Returns: Editable | None: The next named sibling node, or None if there is no next named sibling.

def next_named_sibling(self) -> Editable | None:
    ...

next_sibling

Returns the next sibling of the last symbol in the symbol group.

Provides access to the next sibling node of the last symbol in this symbol group. This property follows the tree structure of the AST.

Returns: Editable | None: The next sibling node of the last symbol in the group, or None if there is no next sibling.

def next_sibling(self) -> Editable | None:
    ...

source

Returns the source code of the symbol group.

Returns the concatenated source code of all symbols in the group, with each symbol’s source separated by a newline.

Returns: str: The concatenated source code of all symbols in the group.

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

symbols

Returns the list of symbols in the group.

Gets the list of symbols associated with this SymbolGroup. These symbols can be code elements like functions, classes, or variables that form a logical grouping.

Returns: list[Child]: A list of symbol objects that belong to this group.

def symbols(self) -> list[Child]:
    ...

text

Return the text content of all comments in the comment block.

Returns the text content without comment delimiters, combining multiple comment lines with newlines. For the full comment block including delimiters, use source instead.

Args: None

Returns: str: The concatenated text content of all comments in the block, joined by newlines, excluding comment delimiters.

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

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 node with new text.

Replaces the source of this SymbolGroup with new text, by replacing the first symbol’s source and removing all other symbols.

Args: new_src (str): The new source text to replace the current text with. fix_indentation (bool, optional): When True, adjusts the indentation of new_src to match the current text’s indentation. Defaults to False. priority (int, optional): Priority of the edit operation. Higher priority edits take precedence. Defaults to 0. dedupe (bool, optional): When True, prevents duplicate edits at the same location. Defaults to True.

Returns: None

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

edit_text

Replace the text content of a comment group with new text.

Updates the comment text while preserving and auto-formatting comment delimiters like # or /* */. Removes any additional comment lines from the comment group, leaving only the first line with the new text.

Args: new_text (str): The new text content to replace the existing comment text. The text should not include comment delimiters.

Returns: None

def edit_text(self, new_text: str) -> None:
    ...

find

Search through the given Symbol(s) for all substrings that match strings_to_match.

Similar to python’s str.find(..), this method searches through the source code of the symbol group for matches of the provided strings.

Args: strings_to_match (Union[list[str], str]): The string or list of strings to search for. exact (bool): When True, only return nodes that exactly match the query. Defaults to False.

Returns: list[Editable]: A list of Editable objects representing each match found.

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

find_string_literals

Searches for string literals within this SymbolGroup that match the given strings.

Iterates through all symbols in the group and aggregates the results of finding string literals in each symbol.

Args: strings_to_match (list[str]): List of strings to search for in string literals. fuzzy_match (bool, optional): If True, performs fuzzy matching instead of exact matching. Defaults to False.

Returns: list[Editable]: List of Editable nodes representing the matching string literals found within the symbols.

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_variable_usages

Returns Editables for all TreeSitter nodes corresponding to instances of variable usage that matches the given variable name.

Retrieves a list of variable usages that match a specified name, with an option for fuzzy matching. By default, excludes property identifiers and argument keywords.

Args: var_name (str): The variable name to search for. fuzzy_match (bool): If True, matches variables where var_name is a substring. If False, requires exact match. Defaults to False.

Returns: list[Editable]: List of Editable objects representing variable usage nodes matching the given name.

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

insert_after

Inserts source code after this node in the codebase.

If the symbol group is empty or the ts_node doesn’t match the first symbol’s ts_node, inserts after the group. Otherwise, inserts after the last symbol in the group.

Args: new_src (str): The source code to insert. fix_indentation (bool, optional): Whether to adjust indentation of new source to match current text. Defaults to False. newline (bool, optional): Whether to add a newline before the inserted code. Defaults to True. priority (int, optional): Priority of the edit operation. Defaults to 0. dedupe (bool, optional): Whether to deduplicate identical edits. Defaults to True.

Returns: None

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

insert_before

Inserts source code before this symbol group.

Inserts the provided source code before the first symbol in the group, while maintaining proper code formatting.

Args: new_src (str): The source code to insert. fix_indentation (bool, optional): Whether to adjust the indentation of the inserted code to match the current code. Defaults to False. newline (bool, optional): Whether to add a newline after the inserted code. Defaults to True. priority (int, optional): The priority of this edit operation. Higher priority edits are applied first. Defaults to 0. dedupe (bool, optional): Whether to prevent duplicate insertions of the same code. Defaults to True.

Returns: None

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

reduce_condition

Reduces an editable to the following condition

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

remove

Removes this node and its related extended nodes from the codebase.

Removes this node and all contained symbols, including any related formatting such as decorators and comments by delegating to the underlying symbols’ removal methods.

Args: delete_formatting (bool, optional): Whether to delete related extended nodes like decorators and comments. Defaults to True. priority (int, optional): Priority level of the removal operation. Defaults to 0. dedupe (bool, optional): Whether to deduplicate removal operations. Defaults to True.

Returns: None

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

replace

Replaces all instances of a string with a new string in all symbols within the group.

Args: old (str): The string to be replaced. new (str): The string to replace with. count (int, optional): Maximum number of replacements to make. Defaults to -1 (replace all). priority (int, optional): Priority of the replacement operation. Defaults to 0.

Returns: int: Number of replacements made.

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

search

Returns a list of all regex matches in the codebase that match the given pattern.

Searches through the source code to find text matching a regex pattern, with options to exclude string literals and comments from the search.

Args: regex_pattern (str): The regular expression pattern to search for. include_strings (bool, optional): Whether to include string literals in the search. Defaults to True. include_comments (bool, optional): Whether to include comments in the search. Defaults to True.

Returns: list[Editable]: A list of Editable objects representing matched text nodes in the codebase.

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

to_google_docstring

Convert a comment group into a Google-style docstring.

Processes the text content of the comment group and converts it into a properly formatted Google-style docstring, incorporating existing function signature information and merging any existing docstring content with the new format.

Args: function (PyFunction): The Python function whose signature will be used to extract parameter and return type information.

Returns: str: A formatted Google-style docstring string that includes the function’s description, parameters, and return value information.

def to_google_docstring(self, function: PyFunction) -> str:
    ...