"""
This type stub file was generated by pyright.
"""

from typing import Generic, Self, TYPE_CHECKING, TypeVar
from tree_sitter import Node as TSNode
from typing_extensions import deprecated
from graph_sitter.core.assignment import Assignment
from graph_sitter.core.autocommit import reader, writer
from graph_sitter.core.detached_symbols.function_call import FunctionCall
from graph_sitter.core.expressions import Expression
from graph_sitter.core.interfaces.editable import Editable
from graph_sitter.core.interfaces.importable import Importable
from graph_sitter.core.statements.assignment_statement import AssignmentStatement
from graph_sitter.core.statements.attribute import Attribute
from graph_sitter.core.statements.return_statement import ReturnStatement
from graph_sitter.core.statements.statement import Statement, StatementType
from graph_sitter.core.statements.symbol_statement import SymbolStatement
from graph_sitter.core.symbol_groups.multi_line_collection import MultiLineCollection
from graph_sitter.writer_decorators import apidoc, noapidoc
from graph_sitter.core.interfaces.has_block import HasBlock
from graph_sitter.core.statements.comment import Comment
from graph_sitter.core.statements.if_block_statement import IfBlockStatement

if TYPE_CHECKING:
    ...
Parent = TypeVar("Parent", bound="HasBlock")
TAssignment = TypeVar("TAssignment", bound="Assignment")
@apidoc
class CodeBlock(Expression[Parent], Generic[Parent, TAssignment]):
    """Container class for a list of code Statements that share an indentation level, e.g. a
    function body or class body.

    Enables various types of queries and operations on the code block.
    """
    level: int
    parent_block: CodeBlock | None
    _statements: MultiLineCollection[Statement, Self]
    def __init__(self, ts_node: TSNode, level: int, parent_block: CodeBlock | None, parent: Parent) -> None:
        ...
    
    @noapidoc
    def parse(self) -> None:
        ...
    
    @property
    @reader
    def statements(self) -> MultiLineCollection[Statement, Self]:
        """Gets a view of the top-level statements in the code block.

        Returns a collection of statements that appear directly in this code block, ordered by their appearance.
        This does not include statements nested within other blocks (e.g., if statements, functions).

        Returns:
            MultiLineCollection[Statement, Self]: An ordered collection of top-level statements in the code block.
        """
        ...
    
    @reader
    def get_statements(self, statement_type: StatementType | None = ..., max_level: int | None = ...) -> list[Statement[Self]]:
        """Returns all statements of a given type up to the specified block level.

        This method retrieves statements from the code block and its nested blocks. Statements can be filtered by type and depth.

        Args:
            statement_type (StatementType | None): The type of statements to return. If None, returns all statement types.
            max_level (int | None): The maximum block depth level to search. If None, searches all levels.

        Returns:
            A sorted list of matching statements.
        """
        ...
    
    @property
    @reader
    def symbol_statements(self) -> list[SymbolStatement]:
        """Returns list of top level symbol statements in the code block.

        Retrieves all statements in the block that have a statement type of SYMBOL_STATEMENT.
        Symbol statements are statements that declare or manipulate symbols like functions or classes.

        Returns:
            list[SymbolStatement]: A list of all the symbol statements at the top level of this code block.
        """
        ...
    
    @property
    @reader
    def comments(self) -> list[Comment[Parent, Self]]:
        """Gets list of top level comments in the code block.

        Returns a list of comment statements that occur at the top level of this code block. Does not include nested comments.

        Returns:
            list[Comment[Parent, Self]]: A list of Comment objects that are immediate children of this code block.
        """
        ...
    
    @reader
    def get_comment(self, comment_src: str) -> Comment[Parent, Self] | None:
        """Gets the first comment statement containing a specific text string.

        Searches through all nested statement levels in the code block to find a comment that contains
        the specified text.

        Args:
            comment_src (str): The text string to search for within comment statements.

        Returns:
            Comment[Parent, Self] | None: The first comment statement containing the search text,
                or None if no matching comment is found.
        """
        ...
    
    @property
    @reader
    def if_blocks(self) -> list[IfBlockStatement[Self]]:
        """Returns a list of top level if statements in the code block.

        A property that retrieves all the immediate if statements within this code block.
        These are if statements that exist at the same indentation level as other statements in the block, not nested ones.

        Returns:
            list[IfBlockStatement[Parent, Self]]: A list of top-level if statement objects in the code block.
        """
        ...
    
    @property
    @reader
    def attributes(self) -> list[Attribute[Parent, Self]]:
        """Returns a list of top level class attribute statements in the code block.

        Get all attribute statements (Attribute objects) that are direct children of the current code block.
        These represent class-level attribute declarations.

        Returns:
            list[Attribute[Parent, Self]]: A list of Attribute objects representing the class-level attributes,
                ordered by their appearance in the code block.
        """
        ...
    
    @reader
    def get_attributes(self, private: bool) -> list[Attribute[Parent, Self]]:
        """Returns attributes from the code block, with the option to include or exclude private
        attributes.

        Retrieves a list of top level attribute statements from the code block, filtering based on the private parameter.
        When private is True, both private and public attributes are returned. When private is False, only public
        attributes are returned.

        Args:
            private (bool): Whether to include private attributes in the returned list. If True, returns both private and
                public attributes. If False, returns only public attributes.

        Returns:
            list[Attribute[Parent, Self]]: A list of attribute statements matching the privacy criteria.
        """
        ...
    
    @property
    @reader
    def assignment_statements(self) -> list[AssignmentStatement[Self, TAssignment]]:
        """Returns list of top level assignment statements in the code block.

        Retrieves all statements in the code block whose type is AssignmentStatement. These statements represent direct assignments
        at the current code block level (not nested within other blocks).

        Returns:
            A list of assignment statements found at the top level of the code block.
        """
        ...
    
    @property
    @reader
    def return_statements(self) -> list[ReturnStatement[Self]]:
        """Gets all return statements at the top level of the code block.

        Args:
            None

        Returns:
            list[ReturnStatement[Parent, Self]]: A list of return statements that appear at the top level of the code block. Does not include return statements in nested blocks.
        """
        ...
    
    @property
    @reader
    def assignments(self) -> list[Assignment[Parent, Self]]:
        """Returns all assignments in the code block across all nesting levels.

        Gets every assignment from every assignment statement in the code block, including assignments in nested blocks.

        Returns:
            list[Assignment[Parent, Self]]: A list of Assignment objects from all nested levels of the code block.
        """
        ...
    
    @reader
    def get_assignments(self, var_name: str, *, fuzzy: bool = ..., parameters: bool = ...) -> list[Assignment[Parent, Self]]:
        """Returns a list of assignments with the specified variable name.

        Returns all assignments in the code block that match the given variable name.

        Args:
            var_name (str): The name of the variable to find assignments for.

        Returns:
            list[Assignment[Parent, Self]]: A list of Assignment objects that match the variable name.
        """
        ...
    
    @property
    @reader
    def local_var_assignments(self) -> list[Assignment[Parent, Self]]:
        """Returns all local variable assignment in the code block, for all nest levels.

        A property that returns all variable assignments that are marked as local variables within the code block,
        including assignments in nested code blocks.

        Returns:
            list[Assignment[Parent, Self]]: A list of Assignment objects representing local variable assignments.
        """
        ...
    
    @reader
    def get_local_var_assignment(self, var_name: str) -> Assignment[Parent, Self] | None:
        """Returns the first code statement that assigns a local variable with the specified name.

        Searches through all local variable assignments in the code block and returns the first one that matches
        the given variable name.

        Args:
            var_name (str): The name of the local variable to search for.

        Returns:
            Assignment[Parent, Self] | None: The first matching local variable assignment, or None if no match is found.
        """
        ...
    
    @reader
    def get_local_var_assignments(self, var_name: str, fuzzy_match: bool = ...) -> list[Assignment[Parent, Self]]:
        """Returns all instances of local variable assignments that match the specified variable
        name.

        Finds local variable assignments within the code block that match the provided variable name, with optional fuzzy matching.

        Args:
            var_name (str): The name of the local variable to search for.
            fuzzy_match (bool, optional): If True, matches variables whose names contain var_name.
                If False, only matches exact variable names. Defaults to False.


        Returns:
            list[Assignment[Parent, Self]]: List of Assignment objects representing local variable assignments
                that match the specified name criteria.
        """
        ...
    
    @reader
    def get_variable_usages(self, var_name: str, fuzzy_match: bool = ...) -> list[Editable[Self]]:
        """Returns all instances of variable usages in a code block.

        This method searches through all statements in the code block to find variable usages that match the specified variable name.
        Variable usages are instances where the variable is referenced or used in expressions, function calls, or other code constructs.

        Args:
            var_name (str): The name of the variable to search for.
            fuzzy_match (bool): When True, matches on variable names that contain var_name. When False (default), only matches exact variable names.

        Returns:
            list[Editable[Self]]: A sorted list of variable usage instances as Editable objects.
        """
        ...
    
    @writer
    def rename_variable_usages(self, old_var_name: str, new_var_name: str, fuzzy_match: bool = ...) -> None:
        """Renames all instances of variable usages in the code block.

        This method modifies variable usages in the code block by replacing occurrences of the old variable name with a new one.
        It uses get_assignments() and rename() internally to find all instances of the variable.

        Args:
            old_var_name (str): The current name of the variable to rename.
            new_var_name (str): The new name to give the variable.
            fuzzy_match (bool): When True, matches variables containing old_var_name. When False, only exact matches. Defaults to False.

        Returns:
            None: This method mutates the code block in place.
        """
        ...
    
    @deprecated("Use `self.statements.insert(0, ...)` instead.")
    @writer
    def insert_before(self, new_src: str) -> None:
        """Inserts new source code at the top of the code block.

        This method has been deprecated in favor of using `self.statements.insert(0, ...)`.

        Args:
            new_src (str): The source code to insert at the top of the code block.

        Returns:
            None
        """
        ...
    
    @deprecated("Use `self.statements.append(...)` instead.")
    @writer
    def insert_after(self, new_src: str, fix_indentation=..., newline=...) -> None:
        """Inserts source code at the bottom of the code block.

        This method is deprecated. Use `self.statements.append(...)` instead.

        Args:
            new_src (str): The source code to insert.
            fix_indentation (bool): Whether to fix the indentation of the inserted code. Defaults to True.
            newline (bool): Whether to add a newline before the inserted code. Defaults to True.

        Returns:
            None
        """
        ...
    
    @writer
    def indent(self, level: int) -> None:
        """Adjusts the indentation level of the entire code block.

        Modifies the indentation of all lines in the code block by adding or removing spaces at the start of each line.
        The amount of indentation per level is determined by either the existing indentation level or defaults to 4 spaces.

        Args:
            level (int): The number of indentation levels to adjust. Positive values indent right, negative values indent left.

        Returns:
            None
        """
        ...
    
    @writer
    def wrap(self, before_src: str, after_src: str = ...) -> None:
        """Wraps a code block with a statement and indents it.

        This method wraps an existing code block with a preceding statement (and optionally a following statement),
        and indents the block appropriately. Common use cases include wrapping code blocks with if statements,
        try/except blocks, with statements, or other control flow structures.

        Args:
            before_src (str): The source code to insert before the block.
            after_src (str): The source code to insert after the block. Defaults to an empty string.

        Returns:
            None
        """
        ...
    
    @writer
    def unwrap(self) -> None:
        """Extracts a code block from its parent wrapper container by removing the wrapping
        statement and adjusting indentation.

        This method unwraps a code block from its parent container (like if statements, with statements, function definitions, etc.)
        by removing the parent wrapper code and unindenting the block content.

        This method handles two cases:
        1. When the wrapper is the only statement on its line
        2. When the wrapper shares a line with other statements

        For example, transforming:
            if a:
                return b
        into:
            return b

        Args:
            None

        Returns:
            None
        """
        ...
    
    @property
    @reader
    def function_calls(self) -> list[FunctionCall]:
        """Returns a list of all function calls in the code block.

        Gets a list of all function calls in the code block, including those within nested statements. The function calls are ordered by their appearance in the code block.

        Returns:
            list[FunctionCall]: A list of FunctionCall objects representing all function calls in the code block.
        """
        ...
    
    @property
    @noapidoc
    def descendant_symbols(self) -> list[Importable]:
        ...
    


