PyCodeBlock.mdx

title	PyCodeBlock
sidebarTitle	PyCodeBlock
icon
description	Extends CodeBlock for Python codebases.

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

CodeBlock, Expression, Editable

Attributes

### assignment_statements list[ PyAssignmentStatement [ PyCodeBlock , PyAssignment ]] } description="Returns list of top level assignment statements in the code block." />

assignments

list[ PyAssignment [ Editable , PyCodeBlock ]] } description="Returns all assignments in the code block across all nesting levels." />

attributes

list[ PyAttribute [ Editable , PyCodeBlock ]] } description="Returns a list of top level class attribute statements in the code block." />

comments

list[ PyComment [ Editable , PyCodeBlock ]] } description="Gets list of top level comments in the code block." />

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

file

PyFile } description="The file object that this Editable instance belongs to." />

filepath

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

function_calls

list[ FunctionCall ] } description="Returns a list of all function calls in the code block." />

if_blocks

list[ PyIfBlockStatement [ PyCodeBlock ]] } description="Returns a list of top level if statements in the code block." />

level

int } description="The indentation level of the code block." />

local_var_assignments

list[ PyAssignment [ Editable , PyCodeBlock ]] } description="Returns all local variable assignment in the code block, for all nest levels." />

parent

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

parent_block

PyCodeBlock | None } description="The parent code block containing this block, or None if it is a top-level block." />

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

resolved_value

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

return_statements

list[ ReturnStatement [ PyCodeBlock ]] } description="Gets all return statements at the top level of the code block." />

source

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

statements

MultiLineCollection [ Statement , PyCodeBlock ] } description="Gets a view of the top-level statements in the code block." />

symbol_statements

list[ SymbolStatement ] } description="Returns list of top level symbol statements in the code block." />

variable_usages

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

with_statements

list[ WithStatement ] } description="Returns a list of all 'with' statements within the code block." />

Methods

### 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_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/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ]]</> } 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/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ]</> } description=""/>

get_assignments

Returns a list of assignments with the specified variable name.

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

<Return return_type={ <>list[ <a href="/api-reference/python/PyAssignment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyAssignment [ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable , <a href="/api-reference/python/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ]]</> } description="A list of Assignment objects that match the variable name."/>

get_attributes

Returns attributes from the code block, with the option to include or exclude private

bool } description="Whether to include private attributes in the returned list. If True, returns both private and" defaultValue="" />

<Return return_type={ <>list[ <a href="/api-reference/python/PyAttribute" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyAttribute [ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable , <a href="/api-reference/python/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ]]</> } description="A list of attribute statements matching the privacy criteria."/>

get_comment

Gets the first comment statement containing a specific text string.

str } description="The text string to search for within comment statements." defaultValue="" />

<Return return_type={ <><a href="/api-reference/python/PyComment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyComment [ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable , <a href="/api-reference/python/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ] | None</> } description="The first comment statement containing the search text, or None if no matching comment is found."/>

get_local_var_assignment

Returns the first code statement that assigns a local variable with the specified name.

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

<Return return_type={ <><a href="/api-reference/python/PyAssignment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyAssignment [ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable , <a href="/api-reference/python/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ] | None</> } description="The first matching local variable assignment, or None if no match is found."/>

get_local_var_assignments

Returns all instances of local variable assignments that match the specified variable

str } description="The name of the local variable to search for." defaultValue="" /> bool, optional } description="If True, matches variables whose names contain var_name." defaultValue="False" />

<Return return_type={ <>list[ <a href="/api-reference/python/PyAssignment" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyAssignment [ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable , <a href="/api-reference/python/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ]]</> } description="List of Assignment objects representing local variable assignments that match the specified name criteria."/>

get_statements

Returns all statements of a given type up to the specified block level.

StatementType | None } description="The type of statements to return. If None, returns all statement types." defaultValue="None" /> int | None } description="The maximum block depth level to search. If None, searches all levels." defaultValue="None" />

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

get_variable_usages

Returns all instances of variable usages in a code block.

str } description="The name of the variable to search for." defaultValue="" /> bool } description="When True, matches on variable names that contain var_name. When False (default), only matches exact variable names." defaultValue="False" />

<Return return_type={ <>list[ <a href="/api-reference/core/Editable" style={ {fontWeight: "inherit", fontSize: "inherit"} }>Editable [ <a href="/api-reference/python/PyCodeBlock" style={ {fontWeight: "inherit", fontSize: "inherit"} }>PyCodeBlock ]]</> } description="A sorted list of variable usage instances as Editable objects."/>

get_with_statements

Gets with statements at a specific block level.

int } description="The block level to filter by. 0 represents the top level." defaultValue="" />

<Return return_type={ <>list[ <a href="/api-reference/python/WithStatement" style={ {fontWeight: "inherit", fontSize: "inherit"} }>WithStatement ]</> } description="A list of WithStatement objects at the specified block level."/>

indent

Adjusts the indentation level of the entire code block.

int } description="The number of indentation levels to adjust. Positive values indent right, negative values indent left." defaultValue="" />

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

insert_after

Inserts source code at the bottom of the code block.

str } description="The source code to insert." defaultValue="" /> bool } description="Whether to fix the indentation of the inserted code. Defaults to True." defaultValue="True" /> bool } description="Whether to add a newline before the inserted code. Defaults to True." defaultValue="True" />

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

insert_before

Inserts new source code at the top of the code block.

str } description="The source code to insert at the top of the code block." defaultValue="" />

<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

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

bool } description="Whether to delete surrounding whitespace and formatting. Defaults to True." defaultValue="True" /> int } description="Priority of the removal transaction. Higher priority transactions are executed first. Defaults to 0." defaultValue="0" /> bool } description="Whether to deduplicate removal transactions at the same location. Defaults to True." defaultValue="True" />

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

rename_variable_usages

Renames all instances of variable usages in the code block.

str } description="The current name of the variable to rename." defaultValue="" /> str } description="The new name to give the variable." defaultValue="" /> bool } description="When True, matches variables containing old_var_name. When False, only exact matches. Defaults to False." defaultValue="False" />

<Return return_type={ None } description="This method mutates the code block in place."/>

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

unwrap

Extracts a code block from its parent wrapper container by removing the wrapping

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

wrap

Wraps a code block with a statement and indents it.

str } description="The source code to insert before the block." defaultValue="" /> str } description="The source code to insert after the block. Defaults to an empty string." defaultValue="""" />

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