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

import rich.repr
from collections.abc import Callable, Generator, Iterable
from functools import cached_property
from typing import Generic, Self, TYPE_CHECKING, TypeVar, Unpack, final, overload
from rich.console import Console, ConsoleOptions, RenderResult
from tree_sitter import Node as TSNode, Point, Range
from graph_sitter.codebase.flagging.code_flag import CodeFlag
from graph_sitter.codebase.flagging.enums import FlagKwargs
from graph_sitter.codebase.span import Span
from graph_sitter.codebase.transaction_manager import TransactionManager
from graph_sitter.core.autocommit import commiter, reader, remover, repr_func, writer
from graph_sitter.core.dataclasses.usage import UsageKind
from graph_sitter.core.node_id_factory import NodeId
from graph_sitter.core.placeholder.placeholder import Placeholder
from graph_sitter.enums import NodeType
from graph_sitter.output.ast import AST
from graph_sitter.output.jsonable import JSONable
from graph_sitter.writer_decorators import apidoc, noapidoc
from graph_sitter.codebase.codebase_graph import CodebaseGraph
from graph_sitter.core.class_definition import Class
from graph_sitter.core.detached_symbols.function_call import FunctionCall
from graph_sitter.core.export import Export
from graph_sitter.core.expressions import Expression
from graph_sitter.core.file import File, SourceFile
from graph_sitter.core.function import Function
from graph_sitter.core.import_resolution import Import, WildcardImport
from graph_sitter.core.interfaces.importable import Importable
from graph_sitter.core.statements.statement import Statement
from graph_sitter.core.symbol import Symbol
from graph_sitter.core.symbol_group import SymbolGroup
from graph_visualization.enums import VizNode

if TYPE_CHECKING:
    ...
CONTAINER_CHARS = ...
MAX_REPR_LEN: int = ...
_EXCLUDE_FROM_REPR: list[str] = ...
Parent = TypeVar("Parent", bound="Editable")
P = TypeVar("P", bound=Placeholder)
T = TypeVar("T", bound="Editable")
@apidoc
class Editable(JSONable, Generic[Parent]):
    """An editable instance is an abstract text representation of any text in a file.

    The editable APIs enables text search and edit within the given Editable wrapper around any
    group of text in a file.
    """
    ts_node: TSNode
    file_node_id: NodeId
    G: CodebaseGraph
    parent: Parent
    node_type: NodeType
    _file: File | None = ...
    _hash: int | None = ...
    def __init__(self, ts_node: TSNode, file_node_id: NodeId, G: CodebaseGraph, parent: Parent) -> None:
        ...
    
    def __hash__(self) -> int:
        ...
    
    def __str__(self) -> str:
        ...
    
    @repr_func
    def __repr__(self) -> str:
        """Represent the string for logging purposes."""
        ...
    
    def __rich_repr__(self) -> rich.repr.Result:
        ...
    
    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
        ...
    
    @reader
    def __eq__(self, other: object) -> bool:
        ...
    
    @reader
    def __contains__(self, item: str | Editable) -> bool:
        ...
    
    @property
    @noapidoc
    def transaction_manager(self) -> TransactionManager:
        ...
    
    @cached_property
    @noapidoc
    @reader
    def start_byte(self) -> int:
        """The start byte of the Editable instance that appears in file."""
        ...
    
    @cached_property
    @noapidoc
    @reader
    @final
    def end_byte(self) -> int:
        """The end byte of the Editable instance that appears in file."""
        ...
    
    @property
    @noapidoc
    @reader
    @final
    def start_point(self) -> Point:
        """The start point (row, column) of the Editable instance that appears in file."""
        ...
    
    @property
    @noapidoc
    @reader
    @final
    def end_point(self) -> Point:
        """The end point (row, column) of the Editable instance that appears in file."""
        ...
    
    @property
    @noapidoc
    @reader
    def line_range(self) -> range:
        """The 0-indexed line/row range that the Editable instance spans in the file."""
        ...
    
    @property
    @reader
    def source(self) -> str:
        """Text representation of the Editable instance.

        Returns the source text of the Editable instance. This is the main property used to access the text content of any code element in GraphSitter.

        Returns:
            str: The text content of this Editable instance.
        """
        ...
    
    @source.setter
    @writer
    def source(self, value) -> None:
        """Sets the source (text representation) of the Editable instance using .edit(..).

        Only edits if the new value is different from the current source.

        Args:
            value (str): The new text representation to set.

        Returns:
            None: The method returns nothing.
        """
        ...
    
    @property
    @noapidoc
    @reader(cache=False)
    def extended_nodes(self) -> list[Editable]:
        """List of Editable instances that includes itself and its extended symbols like `export`,
        `public` or `decorator`
        """
        ...
    
    @property
    def extended(self) -> SymbolGroup:
        """Returns a SymbolGroup of all extended nodes associated with this element.

        Creates a SymbolGroup that provides a common interface for editing all extended nodes,
        such as decorators, modifiers, and comments associated with the element.

        Args:
            None

        Returns:
            SymbolGroup: A group containing this node and its extended nodes that allows
            batch modification through a common interface.
        """
        ...
    
    @property
    @reader
    def extended_source(self) -> str:
        """Returns the source text representation of all extended nodes.

        Gets the source text of all extended nodes combined. This property allows reading the source text
        of all extended nodes (e.g. decorators, export statements) associated with this node.

        Returns:
            str: The combined source text of all extended nodes.
        """
        ...
    
    @extended_source.setter
    def extended_source(self, value: str) -> None:
        """Set the source of all extended nodes.

        Updates the source of all nodes in the extended nodes list by calling .edit(..). This is useful for updating multiple related nodes (e.g. decorators, export statements) at once.

        Args:
            value (str): The new source text to set for all extended nodes.

        Returns:
            None
        """
        ...
    
    @property
    @reader
    @noapidoc
    def children(self) -> list[Editable]:
        """List of Editable instances that are children of this node."""
        ...
    
    @property
    @reader
    @noapidoc
    def next_sibling(self) -> Editable | None:
        """Returns the Editable instance that next appears in the file."""
        ...
    
    @property
    @reader
    @noapidoc
    def next_named_sibling(self) -> Editable | None:
        ...
    
    @property
    @reader
    @noapidoc
    def previous_named_sibling(self) -> Editable | None:
        ...
    
    @property
    def file(self) -> SourceFile:
        """The file object that this Editable instance belongs to.

        Retrieves or caches the file object associated with this Editable instance.

        Returns:
            File: The File object containing this Editable instance.
        """
        ...
    
    @property
    def filepath(self) -> str:
        """The file path of the file that this Editable instance belongs to.

        Returns a string representing the absolute file path of the File that contains this Editable instance.

        Returns:
            str: The absolute file path.
        """
        ...
    
    @reader
    def find_string_literals(self, strings_to_match: list[str], fuzzy_match: bool = ...) -> list[Editable]:
        """Returns a list of string literals within this node's source that match any of the given
        strings.

        Args:
            strings_to_match (list[str]): A list of strings to search for in string literals.
            fuzzy_match (bool): If True, matches substrings within string literals. If False, only matches exact strings. Defaults to False.

        Returns:
            list[Editable]: A list of Editable objects representing the matching string literals.
        """
        ...
    
    @writer
    def replace(self, old: str, new: str, count: int = ..., is_regex: bool = ..., priority: int = ...) -> int:
        """Search and replace occurrences of text within this node's source and its extended nodes.

        This method performs string replacement similar to Python's string.replace(), with support for regex patterns.
        It operates on both the main node and any extended nodes (e.g. decorators, exports).

        Args:
            old (str): The text or pattern to search for.
            new (str): The text to replace matches with.
            count (int, optional): Maximum number of replacements to make. Defaults to -1 (replace all).
            is_regex (bool, optional): Whether to treat 'old' as a regex pattern. Defaults to False.
            priority (int, optional): Priority of the replacement operation. Defaults to 0.

        Returns:
            int: The total number of replacements made.

        Raises:
            ValueError: If there are multiple occurrences of the substring in a node's source.
        """
        ...
    
    @reader
    def find(self, strings_to_match: list[str] | str, *, exact: bool = ...) -> list[Editable]:
        """Find and return matching nodes or substrings within an Editable instance.

        This method searches through the extended_nodes of the Editable instance and returns all nodes or substrings that match the given search criteria.

        Args:
            strings_to_match (Union[list[str], str]): One or more strings to search for.
            exact (bool): If True, only return nodes whose source exactly matches one of the strings_to_match.
                         If False, return nodes that contain any of the strings_to_match as substrings.
                         Defaults to False.

        Returns:
            list[Editable]: A list of Editable instances that match the search criteria.
        """
        ...
    
    @reader
    def search(self, regex_pattern: str, include_strings: bool = ..., include_comments: bool = ...) -> list[Editable]:
        """Returns a list of all regex match of `regex_pattern`, similar to python's re.search().

        Searches for matches of a regular expression pattern within the text of this node and its extended nodes.

        Args:
            regex_pattern (str): The regular expression pattern to search for.
            include_strings (bool): When False, excludes the contents of string literals from the search. Defaults to True.
            include_comments (bool): When False, excludes the contents of comments from the search. Defaults to True.

        Returns:
            list[Editable]: A list of Editable objects corresponding to the matches found.
        """
        ...
    
    @writer(commit=False)
    @noapidoc
    def insert_at(self, byte: int, new_src: str | Callable[[], str], *, priority: int | tuple = ..., dedupe: bool = ..., exec_func: Callable[[], None] | None = ...) -> None:
        ...
    
    @writer(commit=False)
    def insert_before(self, new_src: str, fix_indentation: bool = ..., newline: bool = ..., priority: int = ..., dedupe: bool = ...) -> None:
        """Inserts text before this node's source with optional indentation and newline handling.

        This method inserts the provided text before the current node's source code. It can automatically handle indentation and newline placement.

        Args:
            new_src (str): The text to insert before this node.
            fix_indentation (bool): Whether to fix the indentation of new_src to match the current node. Defaults to False.
            newline (bool): Whether to add a newline after new_src. Defaults to True.
            priority (int): Transaction priority for managing multiple edits. Defaults to 0.
            dedupe (bool): Whether to deduplicate identical transactions. Defaults to True.

        Returns:
            None
        """
        ...
    
    @writer(commit=False)
    def insert_after(self, new_src: str, fix_indentation: bool = ..., newline: bool = ..., priority: int = ..., dedupe: bool = ...) -> None:
        """Inserts code after this node.

        Args:
            new_src (str): The source code to insert after this node.
            fix_indentation (bool, optional): Whether to adjust the indentation of new_src to match the current node. Defaults to False.
            newline (bool, optional): Whether to add a newline before the new_src. Defaults to True.
            priority (int, optional): Priority of the insertion transaction. Defaults to 0.
            dedupe (bool, optional): Whether to deduplicate identical transactions. Defaults to True.

        Returns:
            None
        """
        ...
    
    @writer
    def edit(self, new_src: str, fix_indentation: bool = ..., priority: int = ..., dedupe: bool = ...) -> None:
        """Replace the source of this `Editable` with `new_src`.

        Replaces the text representation of this Editable instance with new text content. The method handles indentation adjustments and transaction management.

        Args:
            new_src (str): The new source text to replace the current text with.
            fix_indentation (bool): If True, adjusts the indentation of `new_src` to match the current text's indentation level. Defaults to False.
            priority (int): The priority of the edit transaction. Higher priority edits are applied first. Defaults to 0.
            dedupe (bool): If True, deduplicates identical transactions. Defaults to True.

        Returns:
            None
        """
        ...
    
    @remover
    @noapidoc
    def remove_byte_range(self, start_byte: int, end_byte: int) -> None:
        ...
    
    @remover
    def remove(self, delete_formatting: bool = ..., priority: int = ..., dedupe: bool = ...) -> None:
        """Deletes this Node and its related extended nodes (e.g. decorators, comments).

        Removes the current node and its extended nodes (e.g. decorators, comments) from the codebase.
        After removing the node, it handles cleanup of any surrounding formatting based on the context.

        Args:
            delete_formatting (bool): Whether to delete surrounding whitespace and formatting. Defaults to True.
            priority (int): Priority of the removal transaction. Higher priority transactions are executed first. Defaults to 0.
            dedupe (bool): Whether to deduplicate removal transactions at the same location. Defaults to True.

        Returns:
            None
        """
        ...
    
    @overload
    def child_by_field_name(self, field_name: str, *, placeholder: type[P], default: type[Expression] | None = ...) -> Expression[Self] | P:
        ...
    
    @overload
    def child_by_field_name(self, field_name: str, *, placeholder: None = ..., default: type[Expression] | None = ...) -> Expression[Self] | None:
        ...
    
    @reader
    @noapidoc
    def child_by_field_name(self, field_name: str, *, placeholder: type[P] | None = ..., **kwargs) -> Expression[Self] | P | None:
        """Get child by field name."""
        ...
    
    @reader
    @noapidoc
    def children_by_field_types(self, field_types: str | Iterable[str]) -> Generator[Expression[Self], None, None]:
        """Get child by field types."""
        ...
    
    @reader
    @noapidoc
    def child_by_field_types(self, field_types: str | Iterable[str]) -> Expression[Self] | None:
        """Get child by field types."""
        ...
    
    @property
    @reader
    @noapidoc
    def ts_node_type(self) -> str:
        """This is the underlying type of the TreeSitter node corresponding to this entity, and the
        value will correspond to the tree-sitter language grammar.
        """
        ...
    
    @commiter
    @noapidoc
    def commit(self) -> None:
        """Commits any pending transactions for the current node to the codebase.

        Commits only the transactions that affect the file this node belongs to. This is useful when you want to
        commit changes made to a specific node without committing all pending transactions in the codebase.

        Args:
            None

        Returns:
            None
        """
        ...
    
    @property
    @reader
    def variable_usages(self) -> list[Editable]:
        """Returns Editables for all TreeSitter node instances of variable usages within this node's
        scope.

        This method finds all variable identifier nodes in the TreeSitter AST, excluding:
        - Function names in function calls
        - Import names in import statements
        - Property access identifiers (except the base object)
        - Keyword argument names (in Python and TypeScript)

        This is useful for variable renaming and usage analysis within a scope.

        Returns:
            list[Editable]: A list of Editable nodes representing variable usages. Each
                Editable corresponds to a TreeSitter node instance where the variable
                is referenced.
        """
        ...
    
    @reader
    def get_variable_usages(self, var_name: str, fuzzy_match: bool = ...) -> list[Editable]:
        """Returns Editables for all TreeSitter nodes corresponding to instances of variable usage
        that matches the given variable name.

        Retrieves a list of variable usages that match a specified name, with an option for fuzzy matching. By default, excludes property identifiers and argument keywords.

        Args:
            var_name (str): The variable name to search for.
            fuzzy_match (bool): If True, matches variables where var_name is a substring. If False, requires exact match. Defaults to False.

        Returns:
            list[Editable]: List of Editable objects representing variable usage nodes matching the given name.
        """
        ...
    
    def flag(self, **kwargs: Unpack[FlagKwargs]) -> CodeFlag[Self]:
        """Adds a visual flag comment to the end of this Editable's source text.

        Flags this Editable by appending a comment with emoji flags at the end of its source text.
        This is useful for visually highlighting specific nodes in the source code during development
        and debugging.

        Returns:
            None
        """
        ...
    
    @commiter
    @noapidoc
    def add_all_identifier_usages_for_child_node(self, usage_type: UsageKind, child: TSNode, dest=...) -> None:
        ...
    
    @property
    @noapidoc
    def viz(self) -> VizNode:
        ...
    
    @noapidoc
    @reader
    def resolve_name(self, name: str, start_byte: int | None = ...) -> Symbol | Import | WildcardImport | None:
        ...
    
    @cached_property
    @noapidoc
    def github_url(self) -> str | None:
        ...
    
    @property
    @noapidoc
    def parent_symbol(self) -> Symbol | File | Import | Export:
        """Returns the parent symbol of the symbol."""
        ...
    
    @property
    @noapidoc
    @final
    def range(self) -> Range:
        ...
    
    @cached_property
    @noapidoc
    @final
    def span(self) -> Span:
        ...
    
    @property
    @noapidoc
    def descendant_symbols(self) -> list[Importable]:
        """Returns the nested symbols of the importable object, including itself."""
        ...
    
    @writer
    def reduce_condition(self, bool_condition: bool, node: Editable | None = ...) -> None:
        """Reduces an editable to the following condition"""
        ...
    
    @property
    @reader
    def function_calls(self) -> list[FunctionCall]:
        """Returns a list of all function calls contained within this expression.

        Traverses the extended nodes of this expression to find all function calls within it. This is useful for tasks like analyzing call patterns or renaming function invocations.

        Returns:
            list[FunctionCall]: A list of FunctionCall objects representing all function calls contained within this expression.
        """
        ...
    
    @property
    @noapidoc
    def self_dest(self) -> Importable:
        """Returns the symbol usage resolution destination node for the symbol."""
        ...
    
    @reader
    def is_wrapped_in(self, cls: type[Expression]) -> bool:
        """Check if this node is contained another node of the given class"""
        ...
    
    @reader
    def parent_of_type(self, type: type[T]) -> T | None:
        """Find the first ancestor of the node of the given type. Does not return itself"""
        ...
    
    @reader
    def ancestors(self, type: type[T]) -> list[T]:
        """Find all ancestors of the node of the given type. Does not return itself"""
        ...
    
    @reader
    @noapidoc
    def first_ancestors(self, type: type[T]) -> T | None:
        """Find the first ancestor of the node of the given type."""
        ...
    
    @property
    @reader
    def parent_statement(self) -> Statement | None:
        """Find the statement this node is contained in"""
        ...
    
    @property
    @reader
    def parent_function(self) -> Function | None:
        """Find the function this node is contained in"""
        ...
    
    @property
    @reader
    def parent_class(self) -> Class | None:
        """Find the class this node is contained in"""
        ...
    
    @noapidoc
    @final
    def ast(self) -> AST:
        ...
    


