PyParameter - Codegen

Inherits from

Parameter, HasValue, Expression, Usable, Typeable, Editable, Importable, HasName

Properties

`default`

Returns the default value of a parameter if one exists.

Gets the default value of a parameter in a function definition. This is the value that would be used if the parameter is not provided in a function call.

Args: None

Returns: str | None: The string representation of the default value if one exists, None otherwise.

def default(self) -> str | None:
    ...

`dependencies`

Returns a list of symbols that this symbol depends on.

Returns a list of symbols (including imports) that this symbol directly depends on. The returned list is sorted by file location for consistent ordering.

Returns: list[Union[Symbol, Import]]: A list of symbols and imports that this symbol directly depends on, sorted by file location.

def dependencies(self) -> list[Union["Symbol", "Import"]]:
    ...

`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:
    ...

`full_name`

Returns the full name of the object, including the namespace path.

Returns the complete qualified name of an object, including any parent class or namespace paths. For class methods, this returns the parent class’s full name followed by the method name. For chained attributes (e.g., ‘a.b’), this returns the full chained name.

Args: None

Returns: str | None: The complete qualified name of the object. Returns None if no name is available. For class methods, returns ‘ParentClass.method_name’. For chained attributes, returns the full chain (e.g., ‘a.b’). For simple names, returns just the name.

def full_name(self) -> str | None:
    ...

`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]:
    ...

`index`

Returns the 0-based index of this parameter within its parent function’s parameter list.

Args: None

Returns: int: The position of the parameter in the function’s parameter list, 0-based.

def index(self) -> int:
    ...

`is_optional`

Determines if the parameter is optional in Python code.

A parameter is considered optional if it has a default value or if it is a list/dictionary splat pattern. This includes default parameters, typed default parameters, and list/dictionary splat patterns.

Returns: bool: True if the parameter is optional, False otherwise.

def is_optional(self) -> bool:
    ...

`is_typed`

Property indicating if a node has an explicit type annotation.

Checks whether the object has an explicit type annotation or is using a placeholder type.

Returns: bool: True if the object has an explicit type annotation, False if it is using a placeholder type.

def is_typed(self) -> bool:
    ...

`is_variadic`

Determines if a parameter is a variadic parameter.

Checks if this parameter is defined as a variadic parameter using the splat operator (*args or **kwargs).

Returns: bool: True if the parameter is variadic (uses * or ** syntax), False otherwise.

def is_variadic(self) -> bool:
    ...

`name`

Retrieves the name of the object excluding any namespace prefixes.

Returns the “base” name of the object without any namespace or module prefix. For instance, for an object ‘a.b’, this method returns ‘b’.

Returns: str | None: The base name of the object as a string, or None if there is no associated name node.

def name(self) -> str | None:
    ...

`parent_function`

Gets the function that this parameter belongs to.

Retrieves the parent function object that contains this parameter. This is a property that provides access to the function where this parameter is defined.

Returns: Function: The function object that contains this parameter.

def parent_function(self) -> Function:
    ...

`resolved_value`

Returns the resolved type of an Expression.

Returns the inferred type of the expression. For example a function call’s resolved value will be it’s definition.

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

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

`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:
    ...

`value`

Gets the value node of the object.

Returns the value node of the object implementing the HasValue interface. This node can represent various types of values, such as list elements, dictionary values, or expressions.

Returns: Expression | None: The value node of the object. None if no value is set.

def value(self) -> Expression | None:
    ...

`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]:
    ...

Attributes

`type`

The type annotation associated with this node

type: TType | TypePlaceholder[Self]

Methods

`add_trailing_comment`

Add a trailing comment to a parameter in a function signature.

Adds a trailing comment after the specified parameter in the parent function’s signature, followed by a newline.

Args: comment (str): The comment text to be added after the parameter.

Returns: None

def add_trailing_comment(self, comment: str) -> 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_name`

Returns the Name node of the object.

Retrieves the name node of the object which can be used for modification operations.

Returns: Name | ChainedAttribute | None: The name node of the object. Can be a Name node for simple names, a ChainedAttribute for names with namespaces (e.g., a.b), or None if the object has no name.

def get_name(self) -> Name | ChainedAttribute | None:
    ...

`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 code after this node.

Args: new_src (str): The source code to insert after this node. fix_indentation (bool, optional): Whether to adjust the indentation of new_src to match the current node. Defaults to False. newline (bool, optional): Whether to add a newline before the new_src. Defaults to True. priority (int, optional): Priority of the insertion transaction. Defaults to 0. dedupe (bool, optional): Whether to deduplicate identical transactions. 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 text before this node’s source with optional indentation and newline handling.

This method inserts the provided text before the current node’s source code. It can automatically handle indentation and newline placement.

Args: new_src (str): The text to insert before this node. fix_indentation (bool): Whether to fix the indentation of new_src to match the current node. Defaults to False. newline (bool): Whether to add a newline after new_src. Defaults to True. priority (int): Transaction priority for managing multiple edits. Defaults to 0. dedupe (bool): Whether to deduplicate identical transactions. 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:
    ...

`is_wrapped_in`

Check if this node is contained another node of the given class

def is_wrapped_in(self, cls: type[Expression]) -> bool:
    ...

`json`

def json(self, max_depth: int = 2, methods: bool = True) -> JSON:
    ...

`reduce_condition`

Reduces an editable to the following condition

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

`remove`

Removes the parameter from the function definition and all its call sites.

Removes the parameter from a function’s definition and also removes the corresponding argument from all call sites of the function. If an argument cannot be found at a call site, logs a message and continues with other call sites.

Args: delete_formatting (bool, optional): Whether to delete formatting around the parameter. Defaults to True. priority (int, optional): Priority level for 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:
    ...

`rename`

Renames a parameter in a function definition and updates all related references.

Performs a comprehensive rename operation by updating the parameter name in the function definition, all variable usages within the function body, and any keyword arguments in call sites.

Args: new_name (str): The new name for the parameter. priority (int, optional): The priority of the edit operation. Defaults to 0.

Returns: None

def rename(self, new_name: str, priority: int = 0) -> 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]:
    ...

`set_name`

Sets the name of a code element.

Modifies the name of the object’s underlying name node. Works with both simple names and chained attributes (e.g., ‘a.b’).

Args: name (str): The new name to set for the object.

Returns: None

def set_name(self, name: str) -> None:
    ...

`set_type_annotation`

Sets the type annotation of a parameter.

Sets or updates the type annotation for this parameter. This method is deprecated in favor of using type.edit directly.

Args: type_annotation (str): The type annotation to set for the parameter. include_comment (str, optional): A comment to include with the type annotation. Defaults to "".

Returns: None

Deprecated: Use type.edit instead.

def set_type_annotation(self, type_annotation: str, include_comment: str = "") -> None:
    ...

`set_value`

Sets the value of the node’s value Expression.

Updates the value of the underlying Expression node if it exists. No action is taken if the value node is None.

Args: value (str): The new value to set.

Returns: None

def set_value(self, value: str) -> None:
    ...

`symbol_usages`

Returns a list of symbols that use the exportable object or import it. Returns symbols that use this exportable object, including imports that import this exportable object. By default, returns all usages. This shows where this symbol is imported, but not where it is subsequently used.

Args: usage_types: The types of usages to search for. Defaults to any.

DIRECT: Direct uses of the symbol
CHAINED: Uses through method/attribute chains
INDIRECT: Uses through renamed imports
ALIASED: Uses through aliases

Returns: list[Import | Symbol | Export]: A list of symbols that use this exportable object, including imports that import it.

Note: This method can be called as both a property or a method. If used as a property, it is equivalent to invoking it without arguments.

def symbol_usages(self, usage_types: UsageType | None = None) -> list[Import | Symbol | Export]:
    ...

`usages`

Returns a list of usages of the exportable object.

Retrieves a list of all locations where the exportable object is used in the codebase. By default, returns all usages, such as imports or references within the same file.

Args: usage_types: Specifies which types of usages to include in the results. Default is any usages. (graph_sitter.core.dataclasses.usage.UsageType)

Returns: list[Usage]: A sorted list of Usage objects representing where this exportable is used, ordered by source location in reverse.

Raises: ValueError: If no usage types are specified or if only ALIASED and DIRECT types are specified together.

Note: This method can be called as both a property or a method. If used as a property, it is equivalent to invoking it without arguments.

def usages(self, usage_types: UsageType | None = None) -> list[Usage]:
    ...

Getting Started

Guides

Graph Visualization

How to

GraphSitter Reference

​Inherits from

​Properties

​default

​dependencies

​extended

​extended_source

​file

​filepath

​full_name

​function_calls

​index

​is_optional

​is_typed

​is_variadic

​name

​parent_function

​resolved_value

​source

​value

​variable_usages

​Attributes

​type

​Methods

​add_trailing_comment

​edit

​find

​find_string_literals

​flag

​get_name

​get_variable_usages

​insert_after

​insert_before

​is_wrapped_in

​json

​reduce_condition

​remove

​rename

​replace

​search

​set_name

​set_type_annotation

​set_value

​symbol_usages

​usages

Inherits from

Properties

`default`

`dependencies`

`extended`

`extended_source`

`file`

`filepath`

`full_name`

`function_calls`

`index`

`is_optional`

`is_typed`

`is_variadic`

`name`

`parent_function`

`resolved_value`

`source`

`value`

`variable_usages`

Attributes

`type`

Methods

`add_trailing_comment`

`edit`

`find`

`find_string_literals`

`flag`

`get_name`

`get_variable_usages`

`insert_after`

`insert_before`

`is_wrapped_in`

`json`

`reduce_condition`

`remove`

`rename`

`replace`

`search`

`set_name`

`set_type_annotation`

`set_value`

`symbol_usages`

`usages`