Skip to content

PyFile.mdx

Latest commit

 

History

History
949 lines (723 loc) · 44.1 KB

PyFile.mdx

File metadata and controls

949 lines (723 loc) · 44.1 KB
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[ Class ] } description="Returns all Classes in the file." />

code_block

CodeBlock } description=" " />

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." />

dependencies

list[Union[ Symbol , Import ]] } description="Returns a list of symbols that this symbol depends on." />

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_node_id

NodeId } description=" " />

file_path

str } description=" " />

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[ Function ] } description="Returns all Functions in the file." />

global_vars

list[ Assignment ] } 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[ ImportStatement ] } description="Returns all ImportStatements in the file, where each import statement can contain" />

importers

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

imports

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

inbound_imports

list[ Import ] } 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." />

node_type

Literal[NodeType.FILE] } description=" " />

owners

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

parent

Editable } description=" " />

parent_class

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

parent_function

Function | 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=" " />

programming_language

} description=" " />

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[ Symbol ] } description="Returns all Symbols in the file, sorted topologically (parents first). Robust to" />

ts_node

TSNode } description=" " />

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_from_import_string

Adds an import statement to the file from a string representation.

str } description="The string representation of the import statement to add (e.g., 'from module import symbol')." defaultValue="" />

<Return return_type={ None } description="This function modifies the file in place."/>

add_symbol

Adds symbol to the file.

Symbol } 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/core/Symbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Symbol | 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."/>

add_symbol_import

Adds an import to a file for a given symbol.

Symbol } description="The symbol to import." defaultValue="" /> str | None } description="Optional alias for the imported symbol. Defaults to None." defaultValue="None" /> ImportType } description="The type of import to use. Defaults to ImportType.UNKNOWN." defaultValue="ImportType.UNKNOWN" /> bool } description="Whether this is a type-only import. Defaults to False." defaultValue="False" />

<Return return_type={ <><a href="/api-reference/core/Import" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Import | None</> } description="The existing import for the symbol or None if it was added."/>

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=""/>

edit

Replace the source of this Editable 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 text's indentation level. Defaults to False." defaultValue="False" /> int } description="The priority of the edit transaction. Higher priority edits are applied first. Defaults to 0." 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 ]</> } 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/core/Class" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Class | 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/core/Function" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Function | 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/core/Assignment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Assignment | 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/core/Import" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Import | 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/core/ChainedAttribute" style={ {fontWeight: "inherit", fontSize: "inherit"} }>ChainedAttribute | 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/core/Symbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Symbol | 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={ <>list[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable ]</> } 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_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=""/>

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

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

str } description="The text or pattern to search for." defaultValue="" /> str } description="The text to replace matches with." defaultValue="" /> int, optional } description="Maximum number of replacements to make. Defaults to -1 (replace all)." defaultValue="-1" /> bool, optional } description="Whether to treat 'old' as a regex pattern. Defaults to False." defaultValue="False" /> int, optional } description="Priority of the replacement operation. Defaults to 0." defaultValue="0" />

<Return return_type={ int } description="The total number of replacements made."/>

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/core/Import" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Import | <a href="/api-reference/core/Symbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Symbol | <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/core/Symbol" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Symbol | <a href="/api-reference/core/Class" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Class | <a href="/api-reference/core/Function" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Function | <a href="/api-reference/core/Assignment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Assignment | TInterface]</> } 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."/>