PyFile.mdx

title	PyFile
sidebarTitle	PyFile
icon
description	SourceFile representation for Python codebase

import {Parameter} from '/snippets/Parameter.mdx'; import {ParameterWrapper} from '/snippets/ParameterWrapper.mdx'; import {Return} from '/snippets/Return.mdx'; import {HorizontalDivider} from '/snippets/HorizontalDivider.mdx'; import {GithubLinkNote} from '/snippets/GithubLinkNote.mdx'; import {Attribute} from '/snippets/Attribute.mdx';

Inherits from

PyHasBlock, SourceFile, HasBlock, Usable, File, Expression, Importable, Editable, HasName

Attributes

### classes list[ PyClass ] } description="Returns all Classes in the file." />

code_block

PyCodeBlock } description="Represents the block of code contained in the file." />

content

str } description="Returns the content of the file as a UTF-8 encoded string." />

decorators

list[ PyDecorator ] } description="Returns a list of decorators associated with this symbol." />

directory

Directory | None } description="Returns the directory that contains this file." />

docstring

PyCommentGroup | None } description="Gets the function's docstring." />

extended

SymbolGroup } description="Returns a SymbolGroup of all extended nodes associated with this element." />

extended_source

str } description="Returns the source text representation of all extended nodes." />

extension

str } description="Returns the file extension." />

file

PyFile } description="A property that returns the file object for non-source files." />

file_path

str } description="The relative file path as a string." />

filepath

str } description="Retrieves the file path of the file that this Editable instance belongs to." />

full_name

str | None } description="Returns the full name of the object, including the namespace path." />

function_calls

list[ FunctionCall ] } description="Returns all function calls within the code block and its decorators." />

functions

list[ PyFunction ] } description="Returns all Functions in the file." />

global_vars

list[ PyAssignment ] } description="Returns all GlobalVars in the file." />

import_module_name

str } description="Returns the module name that this file gets imported as." />

import_statements

list[ PyImportStatement ] } description="Returns all ImportStatements in the file, where each import statement can contain" />

importers

list[ PyImport ] } description="Returns all imports that directly imports this file as a module." />

imports

list[ PyImport ] } description="List of all Imports in this file." />

inbound_imports

list[ PyImport ] } description="Returns all imports that are importing symbols contained in this file." />

is_binary

bool } description="Indicates whether the file contains binary data." />

is_decorated

bool } description="Returns whether the symbol is decorated with decorators." />

name

str | None } description="Retrieves the base name of the object without namespace prefixes." />

owners

set[str] } description="Returns the CODEOWNERS of the file." />

parent

Editable } description="The parent node of this Editable instance." />

parent_class

PyClass | None } description="Find the class this node is contained in" />

parent_function

PyFunction | None } description="Find the function this node is contained in" />

parent_statement

Statement | None } description="Find the statement this node is contained in" />

path

Path } description="The absolute path of the file as a Path object." />

programming_language

} description="The programming language of the file. Set to ProgrammingLanguage.PYTHON." />

resolved_value

Expression | list[ Expression ] } description="Returns the resolved type of an Expression." />

source

str } description="Text representation of the Editable instance." />

start_byte

int } description="Returns the starting byte position of a file in its content." />

symbols_sorted_topologically

list[ PySymbol ] } description="Returns all Symbols in the file, sorted topologically (parents first). Robust to" />

variable_usages

list[ Editable ] } description="Returns Editables for all TreeSitter node instances of variable usages within this node's" />

Methods

### add_decorator Adds a decorator to a function or method. str } description="The decorator to add, including the '@' symbol." defaultValue="" /> bool, optional } description="If True, skips adding if the decorator exists." defaultValue="False" />

<Return return_type={ bool } description="True if the decorator was added, False if skipped."/>

add_import

Adds an import to the file.

PySymbol | str } description="Either a Symbol to import or a string representation of an import statement." defaultValue="" /> str | None } description="Optional alias for the imported symbol. Only used when imp is a Symbol. Defaults to None." defaultValue="None" /> ImportType } description="The type of import to use. Only used when imp is a Symbol. Defaults to ImportType.UNKNOWN." defaultValue="ImportType.UNKNOWN" /> bool } description="Whether this is a type-only import. Only used when imp is a Symbol. Defaults to False." defaultValue="False" />

<Return return_type={ <><a href="/api-reference/python/PyImport" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyImport | None</> } description="The existing import for the symbol if found, otherwise None."/>

add_symbol

Adds symbol to the file.

PySymbol } description="The symbol to add to the file." defaultValue="" /> bool, optional } description="Whether to export the symbol. Defaults to True." defaultValue="True" />

<Return return_type={ <><a href="/api-reference/python/PySymbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PySymbol | None</> } description="The existing symbol if it already exists in the file or None if it was added."/>

add_symbol_from_source

Adds a symbol to a file from a string representation.

str } description="String representation of the symbol to be added. This should be valid source code for" defaultValue="" />

<Return return_type={ None } description="The symbol is added directly to the file's content."/>

ancestors

Find all ancestors of the node of the given type. Does not return itself

<Return return_type={ <>list[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable ]</> } description=""/>

dependencies

Returns a list of symbols that this symbol depends on.

UsageType | None } description="The types of dependencies to search for. Defaults to UsageType.DIRECT." defaultValue="UsageType.DIRECT" /> int | None } description="Maximum depth to traverse in the dependency graph. If provided, will recursively collect" defaultValue="None" />

<Return return_type={ <>list[Union[ <a href="/api-reference/python/PySymbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PySymbol , <a href="/api-reference/python/PyImport" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyImport ]]</> } description="A list of symbols and imports that this symbol depends on, sorted by file location."/>

edit

Replace the source of this file with new_src.

str } description="The new source text to replace the current text with." defaultValue="" /> bool } description="If True, adjusts the indentation of new_src to match the current" defaultValue="False" /> int } description="The priority of the edit transaction. Higher priority edits are" defaultValue="0" /> bool } description="If True, deduplicates identical transactions. Defaults to True." defaultValue="True" />

<Return return_type={ None } description=""/>

find

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

Union[list[str], str] } description="One or more strings to search for." defaultValue="" /> bool } description="If True, only return nodes whose source exactly matches one of the strings_to_match." defaultValue="False" />

<Return return_type={ <>list[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable ]</> } description="A list of Editable instances that match the search criteria."/>

find_by_byte_range

Finds all editable objects that overlap with the given byte range in the file.

Range } description="The byte range to search within the file." defaultValue="" />

<Return return_type={ <>list[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable ]</> } description="A list of all Editable objects that overlap with the given range."/>

find_string_literals

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

list[str] } description="A list of strings to search for in string literals." defaultValue="" /> bool } description="If True, matches substrings within string literals. If False, only matches exact strings. Defaults to False." defaultValue="False" />

<Return return_type={ <>list[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable [ <a href="/api-reference/python/PyFile" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyFile ]]</> } description="A list of Editable objects representing the matching string literals."/>

flag

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

<Return return_type={ <>CodeFlag[ <a href="/api-reference/python/PyFile" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyFile ]</> } description=""/>

get_class

Returns a specific Class by full name. Returns None if not found.

str } description="The full name of the class to search for." defaultValue="" />

<Return return_type={ <><a href="/api-reference/python/PyClass" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyClass | None</> } description="The matching Class object if found, None otherwise."/>

get_extensions

Returns the file extensions associated with Python files.

<Return return_type={ list[str] } description="A list containing '.py' as the only Python file extension."/>

get_function

Returns a specific Function by name.

str } description="The name of the function to find." defaultValue="" />

<Return return_type={ <><a href="/api-reference/python/PyFunction" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyFunction | None</> } description="The matching Function object if found, None otherwise."/>

get_global_var

Returns a specific global var by name. Returns None if not found.

str } description="The name of the global variable to find." defaultValue="" />

<Return return_type={ <><a href="/api-reference/python/PyAssignment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyAssignment | None</> } description="The global variable if found, None otherwise."/>

get_import

Returns the import with matching alias. Returns None if not found.

str } description="The alias name to search for. This can match either the direct import name or the aliased name." defaultValue="" />

<Return return_type={ <><a href="/api-reference/python/PyImport" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyImport | None</> } description="The import statement with the matching alias if found, None otherwise."/>

get_import_insert_index

Determines the index position where a new import statement should be inserted in a Python file.

str } description="The import statement to be inserted." defaultValue="" />

<Return return_type={ int | None } description="The index where the import should be inserted. Returns 0 for future imports or if there are no existing imports after future imports. Returns None if there are no imports in the file."/>

get_import_string

Generates an import string for a symbol.

str | None, optional } description="Alias to use for the imported symbol. Defaults to None." defaultValue="None" /> str | None, optional } description="Module path to import from. If None, uses module name from source. Defaults to None." defaultValue="None" /> ImportType , optional } description="Type of import statement to generate. Defaults to ImportType.UNKNOWN." defaultValue="ImportType.UNKNOWN" /> bool, optional } description="Whether this is a type import. Currently unused. Defaults to False." defaultValue="False" />

<Return return_type={ str } description="A formatted import string in the form of 'from {module} import {symbol}' with optional alias or wildcard syntax."/>

get_name

Returns the name node of the object.

<Return return_type={ <><a href="/api-reference/core/Name" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Name | <a href="/api-reference/python/PyChainedAttribute" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyChainedAttribute | None</> } description="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."/>

get_symbol

Gets a symbol by its name from the file.

str } description="The name of the symbol to find." defaultValue="" />

<Return return_type={ <><a href="/api-reference/python/PySymbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PySymbol | None</> } description="The found symbol, or None if not found."/>

get_variable_usages

Returns Editables for all TreeSitter nodes corresponding to instances of variable usage

str } description="The variable name to search for." defaultValue="" /> bool } description="If True, matches variables where var_name is a substring. If False, requires exact match. Defaults to False." defaultValue="False" />

<Return return_type={ <>Sequence[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable [ <a href="/api-reference/python/PyFile" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyFile ]]</> } description="List of Editable objects representing variable usage nodes matching the given name."/>

has_import

Returns True if the file has an import with the given alias.

str } description="The alias to check for in the import statements." defaultValue="" />

<Return return_type={ bool } description="True if an import with the given alias exists, False otherwise."/>

insert_after

Inserts code after this node.

str } description="The source code to insert after this node." defaultValue="" /> bool, optional } description="Whether to adjust the indentation of new_src to match the current node. Defaults to False." defaultValue="False" /> bool, optional } description="Whether to add a newline before the new_src. Defaults to True." defaultValue="True" /> int, optional } description="Priority of the insertion transaction. Defaults to 0." defaultValue="0" /> bool, optional } description="Whether to deduplicate identical transactions. Defaults to True." defaultValue="True" />

<Return return_type={ None } description=""/>

insert_before

Inserts text before this node's source with optional indentation and newline handling.

str } description="The text to insert before this node." defaultValue="" /> bool } description="Whether to fix the indentation of new_src to match the current node. Defaults to False." defaultValue="False" /> bool } description="Whether to add a newline after new_src. Defaults to True." defaultValue="True" /> int } description="Transaction priority for managing multiple edits. Defaults to 0." defaultValue="0" /> bool } description="Whether to deduplicate identical transactions. Defaults to True." defaultValue="True" />

<Return return_type={ None } description=""/>

is_child_of

Checks if this node is a descendant of the given editable instance in the AST.

<Return return_type={ bool } description=""/>

is_wrapped_in

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

<Return return_type={ bool } description=""/>

parent_of_type

Find the first ancestor of the node of the given type. Does not return itself

<Return return_type={ <><a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable | None</> } description=""/>

parent_of_types

Find the first ancestor of the node of the given type. Does not return itself

<Return return_type={ <><a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable | None</> } description=""/>

reduce_condition

Reduces an editable to the following condition

<Return return_type={ None } description=""/>

remove

Removes the file from the file system and graph.

<Return return_type={ None } description=""/>

rename

Renames a symbol and updates all its references in the codebase.

str } description="The new name for the symbol." defaultValue="" /> int } description="Priority of the edit operation. Defaults to 0." defaultValue="0" />

<Return return_type={ tuple[NodeId, NodeId] } description="A tuple containing the file node ID and the new node ID of the renamed symbol."/>

replace

Replace occurrences of text in the file.

str } description="The text to be replaced." defaultValue="" /> str } description="The text to replace with." defaultValue="" /> int } description="Maximum number of replacements to make. -1 means replace all occurrences." defaultValue="-1" /> bool } description="If True, treat 'old' as a regular expression pattern." defaultValue="False" /> int } description="The priority of the edit transaction. Higher priority edits are" defaultValue="0" />

<Return return_type={ int } description="List of affected Editable objects. For non-source files, always returns an empty list since they don't have Editable sub-components."/>

search

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

str } description="The regular expression pattern to search for." defaultValue="" /> bool } description="When False, excludes the contents of string literals from the search. Defaults to True." defaultValue="True" /> bool } description="When False, excludes the contents of comments from the search. Defaults to True." defaultValue="True" />

<Return return_type={ <>list[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable ]</> } description="A list of Editable objects corresponding to the matches found."/>

set_docstring

Sets or updates a docstring for a Python function or class.

str } description="The docstring content to set." defaultValue="" /> bool, optional } description="Whether to format the text into a proper docstring format. Defaults to True." defaultValue="True" /> bool, optional } description="Whether to clean and normalize the docstring format before insertion. Defaults to True." defaultValue="True" /> bool, optional } description="Whether to force single-line comments to be converted to multi-line format. Defaults to False." defaultValue="False" />

<Return return_type={ None } description=""/>

set_name

Sets the name of a code element.

str } description="The new name to set for the object." defaultValue="" />

<Return return_type={ None } description=""/>

symbol_can_be_added

Checks if a Python symbol can be added to this Python source file.

PySymbol } description="The Python symbol to check for compatibility with this file." defaultValue="" />

<Return return_type={ bool } description="Always returns True as Python files can contain any Python symbol type."/>

symbol_usages

Returns a list of symbols that use or import the exportable object.

UsageType | None } description="The types of usages to search for. Defaults to any." defaultValue="None" />

<Return return_type={ <>list[ <a href="/api-reference/python/PyImport" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyImport | <a href="/api-reference/python/PySymbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PySymbol | <a href="/api-reference/core/Export" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Export ]</> } description="A list of symbols that use or import the exportable object."/>

symbols

Returns all Symbols in the file, sorted by position in the file.

<Return return_type={ <>list[ <a href="/api-reference/python/PySymbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PySymbol | <a href="/api-reference/python/PyClass" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyClass | <a href="/api-reference/python/PyFunction" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyFunction | <a href="/api-reference/python/PyAssignment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyAssignment | <a href="/api-reference/core/Interface" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Interface ]</> } description="A list of all top-level symbols in the file, sorted by their position in the file. Symbols can be one of the following types: - Symbol: Base symbol class - TClass: Class definition - TFunction: Function definition - TGlobalVar: Global variable assignment - TInterface: Interface definition"/>

update_filepath

Renames the file and updates all imports to point to the new location.

str } description="The new filepath to move the file to." defaultValue="" />

<Return return_type={ None } description=""/>

usages

Returns a list of usages of the exportable object.

UsageType | None } description="Specifies which types of usages to include in the results. Default is any usages." defaultValue="None" />

<Return return_type={ <>list[ <a href="/api-reference/core/Usage" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Usage ]</> } description="A sorted list of Usage objects representing where this exportable is used, ordered by source location in reverse."/>