SourceFile
Represents a file with source code in the codebase. Enables creating, reading, updating, and deleting files and searching through their contents, etc.
Inherits from
File, HasBlock, Exportable, Importable, GraphSitterBase, Expression, Editable
Properties
classes
Returns all Classes in the file
content
Returns contents of the file as a string.
decorators
Returns list of all Decorators on this Symbol
dependencies
Symbols that this symbol depends on. Opposite of usages
directory
Returns the directory that contains this file
docstring
Returns the docstring of the function as a CommentGroup
export
Returns the export object that exports this symbol. Returns none if this symbol is not exported.
exported_name
Returns the name the symbol is exported as. If the symbol is not exported, returns None.
extended
Returns a SymbolGroup of all extended nodes. This allows a common edit interface for all of extended nodes.
extended_source
Text representation of all its extended nodes
extension
Returns the file extension
file
The file object that this Editable instance belongs to
filepath
The file path of the file that this Editable instance belongs to
function_calls
Returns a list of all function calls in the code block.
functions
Returns all Functions in the file
global_vars
Returns all GlobalVars in the file
import_statements
Returns all ImportStatements in the file, where each import statement can contain multiple imports
importers
All imports that directly imports this file as a module
eg. from a import <this file>
does NOT include imports that import symbols from this file
eg. from <this file> import a
does NOT count as an importer
imports
List of all Imports in this file
inbound_imports
Returns all imports that are importing symbols contained in this file
is_binary
is_decorated
Returns True if the symbol is decorated with a decorator.
is_exported
Returns True iff the symbol is exported from the file it’s defined in
is_reexported
Returns True if the symbol is re-exported from a file it is not defined in (if applicable)
owners
Returns the CODEOWNERS of the file.
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.
source
Text representation of the Editable instance
start_byte
The start byte of the Editable instance that appears in file
symbols
Returns all Symbols in the file, sorted by position in the file
symbols_sorted_topologically
Returns all Symbols in the file, sorted topologically (parents first). Robust to dependency loops.
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.
Methods
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
add_import_from_import_string
Adds import to the file from a string representation of an import statement
add_symbol
Adds symbol
to the file.
Arguments: should_export: If true, the symbol will be exported (if applicable).
add_symbol_from_source
Adds a symbol to a file from a string representation.
add_symbol_import
Adds an import to a file for a given symbol
commit
Commit just this node
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.
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
find_string_literals
Returns a list of all editable substrings within string literals that match strings_to_match
flag
Adds a comment so the developer can see this Editable
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)
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)
get_class
Returns a specific Class by full name. Returns None if not found.
get_function
Returns a specific Function by name. Returns None if not found.
get_global_var
Returns a specific global var by name. Returns None if not found.
get_import
Returns the import with matching alias. Returns None if not found.
For example:
get_import_module_name
Returns the module name that this file gets imported as
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
get_symbol
Returns a specific symbol by name. Returns None if not found.
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
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
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
has_import
Returns True if the file has an import with the given alias
insert_after
Inserts new_src after this node
insert_before
Inserts new_src before this node
remove
Removes the file from file directory
remove_unused_exports
Removes unused exports from the file
rename
Renames the file
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.
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.
set_docstring
Sets a docstring for this entity.
- If a docstring already exists, the existing docstring will be overridden
- If no docstring exists, a new docstring will be created.
symbol_can_be_added
Checks if the file type supports the symbol being added.
update_filepath
Renames the file and updates all imports to the file
Was this page helpful?