PyFunction

Extends Function for Python codebases.

Inherits from

Function, PyHasBlock, PySymbol, Symbol, HasBlock, Callable, GraphSitterBase, Exportable, Importable, HasName, Expression, Editable

Properties

---

body

Returns the body of the function as a string.

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

call_sites

All invocations of this function elsewhere in the codebase

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

comment

Returns the comment group associated with the symbol, if any.

def comment(self) -> PyCommentGroup | None:
    ...

decorators

Returns list of all Decorators on this Symbol

def decorators(self) -> list[PyDecorator]:
    ...

dependencies

Symbols that this symbol depends on. Opposite of usages

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

docstring

Returns the docstring of the function. The docstring is represented as a CommentGroup.

def docstring(self) -> PyCommentGroup | None:
    ...

export

Returns the import object that imports this symbol, if any.

def export(self) -> Export | None:
    ...

exported_name

Returns the name the symbol is exported as. If the symbol is not exported, returns None.

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

extended

Returns a SymbolGroup of all extended nodes. This allows a common edit interface for all of extended nodes.

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

extended_nodes

List of Editables with extended symbols like export, public or decorator

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

extended_source

Text representation of all its extended nodes

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

file

The file object that this Editable instance belongs to

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

filepath

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

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

full_name

The full name including the object lookup (if applicable).

Examples: For a.b, the full name is a.b

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

function_calls

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

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

function_signature

Signature of the function. Ex: def foo(bar: str) -> int:

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

inline_comment

Returns the inline comment group associated with the symbol, if any.

def inline_comment(self) -> PyCommentGroup | None:
    ...

is_async

Returns True if the function is asynchronous

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

is_class_method

Returns True if the function is a class method

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

is_constructor

Returns True if the function is a constructor

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

is_decorated

Returns True if the symbol is decorated with decorators

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

is_exported

Always returns true since python symbols are always exported by default.

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

is_magic

Is this method a magic method?

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

is_method

Returns True if the function is a method

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

is_overload

Is this function an overload?

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

is_private

Is this method a private method?

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

is_property

Returns True if the function is a property

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

is_reexported

Returns True if the symbol is re-exported from a file it is not defined in (if applicable)

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

is_static_method

Returns True if the function is a static method

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

name

The name of the object excluding whichever namespace precedes it, as a string.

Examples: For a.b, the name is b

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

nested_functions

Returns all Child functions in the file, sorted by position in the file

def nested_functions(self) -> list[TFunction]:
    ...

parameters

All parameters of this callable

def parameters(self) -> SymbolGroup[TParameter, Self] | None:
    ...

parent_statement

Returns the parent statement that contains this expression

def parent_statement(self) -> Statement:
    ...

resolved_value

If the expression is a resolvable value, returns the last assigned expression value. Else, returns itself.

Example: a = 1 b = a foo(b)

If we call resolve_value on b, it returns 1.

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

return_statements

All return statements within this function’s body. Good for identifying early returns, return types, etc.

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

source

Returns the source code of the function

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

variable_usages

Returns Editables for all TreeSitter node instances of variable usages. (Excludes: property identifiers and argument keywords) This is useful for renaming variables locally and analyzing variable usages.

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

Attributes

---

return_type

the return type annotation of the function

return_type: TType | Placeholder[Self]

Methods

---

add_comment

Adds a new comment to the symbol.

Args: comment (str): The comment to be added. auto_format (bool, optional): Flag to automatically format the text into a comment. Defaults to True. clean_format (bool, optional): Flag to clean the format of the docstring before inserting. Defaults to True. comment_type (PyCommentType, optional): Type of comment to add. Defaults to PyCommentType.SINGLE_LINE.

Returns: None

Notes: If a comment already exists, a new comment will be added to the end of the existing comment group. If no comment exists, a new comment group will be created.

Examples: If auto_format is True, the comment “Hello” will be formatted as:

# Hello

If auto_format is False, the comment string will be added as is, without any formatting.

def add_comment(self, comment: str, auto_format: bool = True, clean_format: bool = True, comment_type: PyCommentType = PyCommentType.SINGLE_LINE) -> None:
    ...

add_decorator

Adds a decorator to this function based on the source

• skip_if_exists: Do not add a decorator if it already exists
• returns bool: True if the decorator was added, False otherwise

def add_decorator(self, new_decorator: str, skip_if_exists: bool = False) -> bool:
    ...

add_keyword

Insert a keyword in the appropriate place if it is not already there.

def add_keyword(self, keyword: str):
    ...

add_statements

Adds lines to the end of the function body

def add_statements(self, lines: str) -> None:
    ...

asyncify

Modifies the function to be asynchronous, if it is not already.

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

call_graph_successors

Returns all Callable objects that are reachable from this Callable.

Args: include_classes (bool): If True, includes class definitions in the code paths. include_external (bool): If True, includes external modules in the code paths.

Returns: list[Function | ExternalModule]: A list of Function or ExternalModule objects that are reachable from this Callable.

def call_graph_successors(
        self,
        *,
        include_classes: bool = True,
        include_external: bool = True,
    ) -> list[FunctionCallDefinition]:
    ...

commit

Commit just this node

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

edit

Replace the source of this node with new_src. When fix_indentation is True, the indentation of the new_src will be adjusted to match the current text’s indentation.

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

find

Returns a list of all substring match in strings_to_match, similar to python’s str.find(..)

Args: exact: Only match individual nodes which exactly match the query

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

find_string_literals

Returns a list of all editable substrings within string literals that match strings_to_match

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

flag

Adds a comment so the developer can see this Editable

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

get_all_symbol_usages

Returns a list of all symbols that uses this exportable object, via direct or indirect usages. Equivalent to get_symbol_usages(UsageType.DIRECT | UsageType.INDIRECT | UsageType.ALIASED)

def get_all_symbol_usages(self) -> list[Import | Symbol | Export]:
    ...

get_all_usages

Returns a list of all usages of this exportable object, via direct or indirect usages. Equivalent to get_usages(UsageType.DIRECT | UsageType.INDIRECT | UsageType.ALIASED)

def get_all_usages(self) -> list[Usage]:
    ...

get_import_string

Returns the import string needed to import this symbol.

• If alias is specified, formats the import using the alias.
• If module is specified, uses the specified module, otherwise defaults to the current module.
• If import_type is ImportType.WILDCARD, imports the symbol’s module. e.g. from module import symbol as alias

def get_import_string(
        self,
        alias: str | None = None,
        module: str | None = None,
        import_type: ImportType = ImportType.UNKNOWN,
        is_type_import: bool = False,
    ) -> str:
    ...

get_name

Returns the Name of the object, as a Name (editable)

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

get_parameter

Returns the parameter with the given name, or None if it doesn’t exist.

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

get_parameter_by_index

Returns the parameter with the given index, or None if it doesn’t exist.

def get_parameter_by_index(self, index: int) -> TParameter | None:
    ...

get_parameter_by_type

Returns the parameter of specified type, or None if it doesn’t exist.

def get_parameter_by_type(self, type: "Symbol") -> TParameter | None:
    ...

get_symbol_usages

Symbols that uses this exportable object, or imports that imports this exportable object. By default, only returns direct usages, such as Imports or usages within the same file. In other words, it will tell you where this symbol is imported, but not where it is used. Inverse of dependencies.

Arguments: usage_types: What kind of usages to search for

def get_symbol_usages(self, usage_types: UsageType = UsageType.DIRECT | UsageType.CHAINED) -> list[Import | Symbol | Export]:
    ...

get_usages

Returns a list of usages of the exportable object. By default, only returns direct usages, such as Imports or usages within the same file. In other words, it will tell you where this symbol is imported, but not where it is used. Useful for dead code deletion.

Arguments: usage_types: What kind of usages to search for

def get_usages(self, usage_types: UsageType = UsageType.DIRECT | UsageType.CHAINED) -> list[Usage]:
    ...

get_variable_usages

Returns Editables for all TreeSitter nodes corresponding to instances of variable usage that matches the given variable name. (Excludes: property identifiers and argument keywords) fuzzy_match allows for partial matching of variable names and effectively does var_name in usage.name

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

insert_after

Inserts new_src after this node

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

insert_before

Inserts new_src before this node.

Arguments:

• extended (bool): If True, the source is inserted before the extended nodes (e.g. comments, docstrings, access identifiers).(Default: True)

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

insert_statements

Inserts lines into the function body at given index

def insert_statements(self, lines: str, index: int = 0):
    ...

move_to_file

Moves a symbol to the specified file and updates all imports. Import update strategy can be specified. Strategies:

• add_back_edge: just moves the symbol to the new file and adds an import to the old file
• update_all_imports: updates all imports and usages of the symbol to the new file

def move_to_file(self, file: SourceFile, include_dependencies: bool = True, strategy: str = "update_all_imports") -> None:
    ...

prepend_statements

Prepends lines to start of function body. Indentations will be taken care of by the method internals.

def prepend_statements(self, lines: str) -> None:
    ...

remove

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

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

rename

Renames the symbol and all its references in the codebase (imports/callsites/etc.)

def rename(self, new_name: str, priority: int = 0) -> tuple[NodeId, NodeId]:
    ...

rename_local_variable

Renames a local variable in a function body and all usages in the function body.

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

replace

Search and replace an instance of substring within this node’s source. Similar to python’s string.replace(..) Throws ValueError if there are more than one occurrence of substring in this node’s source.

Arguments: old: the occurrences of this string to replace new: the string to replace with count: the max number of occurrences to replace. Default value: -1 (replace all) is_regex: whether old is a regex pattern. Default value: False

Returns: The total count of old occurrences replaced.

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(…)

When include_strings is False, the search will exclude the contents of string literals from the search. When include_comments is False, the search will exclude the contents of comments from the search.

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

set_comment

Sets a comment to the symbol.

Args: comment (str): The comment to be added. auto_format (bool, optional): Flag to automatically format the text into a comment. Defaults to True. clean_format (bool, optional): Flag to clean the format of the docstring before inserting. Defaults to True. comment_type (PyCommentType, optional): Type of comment to add. Defaults to PyCommentType.SINGLE_LINE.

Returns: None

Notes: If a comment already exists, the existing comment will be edited. If no comment exists, a new comment group will be created.

Examples: If auto_format is True, the comment “Hello” will be formatted as:

# Hello

If auto_format is False, the comment string will be added as is, without any formatting.

def set_comment(self, comment: str, auto_format: bool = True, clean_format: bool = True, comment_type: PyCommentType = PyCommentType.SINGLE_LINE) -> None:
    ...

set_docstring

Sets a docstring to the function.

Args: docstring (str): The docstring to be added. auto_format (bool, optional): Flag to automatically format the text into a docstring. Defaults to True. clean_format (bool, optional): Flag to clean the format of the docstring before inserting. Defaults to True. force_multiline (bool, optional): Flag to force single line comments to be multi-line. Defaults to False.

Returns: None

Notes: If a docstring already exists, the existing docstring will be edited. If no docstring exists, a new docstring will be created.

Examples: If auto_format is True, the comment “Hello” will be formatted as:

'''Hello'''

If auto_format is False, the comment string will be added as is, without any formatting.

def set_docstring(self, docstring: str, auto_format: bool = True, clean_format: bool = True, force_multiline: bool = False) -> None:
    ...

set_inline_comment

Sets an inline comment to the symbol.

Args: comment (str): The inline comment to be added. auto_format (bool, optional): Flag to automatically format the text into a comment. Defaults to True. clean_format (bool, optional): Flag to clean the format of the docstring before inserting. Defaults to True.

Returns: None

Notes: If an inline comment already exists, it will be replaced with the new comment. If no inline comment exists, a new inline comment will be created.

Examples: If auto_format is True, the comment “Hello” will be formatted as:

# Hello

If auto_format is False, the comment string will be added as is, without any formatting.

def set_inline_comment(self, comment: str, auto_format: bool = True, clean_format: bool = True) -> None:
    ...

set_name

Sets the name of the object

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

set_return_type

Sets the return type of the function.

:param new_return_type: The new return type to be set for the function. If empty string, the return type is removed.

def set_return_type(self, new_return_type: str) -> None:
    ...