PyImport

Extends Import for Python codebases.

Inherits from

Import, GraphSitterBase, Exportable, Importable, HasName, Expression, Editable

Properties

---

dependencies

Symbols that this symbol depends on. Opposite of usages

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

export

Returns the export object that exports this symbol. Returns none if this symbol is not exported.

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

from_file

SourceFile that we are importing from. Goes through Symbol edge

def from_file(self) -> TSourceFile | None:
    ...

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 all contained function calls. Useful for renaming function invocations etc.

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

import_specifier

Returns the specific editable text representation of the import identifier within the import statement e.g. import { a as b } from 'c' -> a as b e.g. from a.b import c -> c

def import_specifier(self) -> Editable:
    ...

import_statement

Returns the ImportStatement that this import belongs to

def import_statement(self) -> ImportStatement:
    ...

imported_exports

Returns the enumerated list of symbols imported from a module import. If the import is not a module import, returns the single imported symbol.

def imported_exports(self) -> list[Exportable]:
    ...

imported_symbol

Returns the symbol directly being imported, including an indirect import and an External Module.

def imported_symbol(self) -> Symbol | ExternalModule | TSourceFile | Import | None:
    ...

is_exported

Returns True iff the symbol is exported from the file it’s defined in

def is_exported(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:
    ...

name

Returns the name or alias of the symbol being imported. Alias if it exists, otherwise name.

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

namespace

Returns the namespace prefix that must be used with dot notation to reference the imported symbol. For symbol imports or unnamed wildcard imports, the namespace is None. For module imports, the namespace is the module name or the module alias.

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

resolved_symbol

Returns the Symbol, SourceFile or External module this import resolves to (hops through indirect imports).

def resolved_symbol(self) -> Symbol | ExternalModule | TSourceFile | None:
    ...

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

source

Text representation of the Editable instance

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

to_file

SourceFile that this import resides in

def to_file(self) -> TSourceFile:
    ...

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

---

symbol_name

The name of the symbol being imported. For instance import a as b has a symbol_name of a.

symbol_name: Editable | None

Methods

---

commit

Commit just this node

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

edit

Replace the source of this Editable with new_src. When fix_indentation is True, the indentation of 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_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

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

is_aliased_import

Returns True if this import is aliased.

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

is_module_import

Returns True if this import is importing an entire module/file.

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

is_reexport

Returns true if the Import object is also an Export object. If the import is an export, it implies there are no usages of the import within the file it is defined in.

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

is_symbol_import

Returns True if this import is importing a symbol rather than a module. Opposite of is_module_import

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

is_wildcard_import

Returns True if the import symbol is a wildcard import. Wildcard imports only import named exports.

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

remove

Remove this import from the import statement

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

rename

Renames the import symbol name as well as its usages

Sets name (not alias) of an import JUST at the declaration, e.g. doing d -> XYZ in:

from a.b.c import d as e # before
from a.b.c import XYZ as e # after (renames d)

import { d as e } from 'a/b/c' # before
import { XYZ as e } from 'a/b/c' # after (renames d)

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

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_import_module

Sets the module of an import.

For example, original: from a.b.c import d Then, you do set_import_module(imp, "x.y.z"), you get: from x.y.z import d

For example, original: import from ‘a/b/c’ Then, you do set_import_module(imp, "x/y/z"), you get: import from ‘x/y/z’

def set_import_module(self, new_module: str) -> None:
    ...

set_import_symbol_alias

Sets alias (including name if no alias) of an import JUST at the declaration, e.g. doing e -> XYZ in:

from a.b.c import d as e # before
from a.b.c import d as XYZ # after (renames e)

import { d as e } from 'a/b/c' # before
import { d as XYZ } from 'a/b/c' # after (renames e)

Breaks imports and callsites.

def set_import_symbol_alias(self, new_alias: str) -> None:
    ...

set_name

Sets the name of the object

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