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

import rich.repr
from abc import abstractmethod
from typing import Generic, Literal, TYPE_CHECKING, TypeVar
from tree_sitter import Node as TSNode
from graph_sitter.codebase.codebase_graph import CodebaseGraph
from graph_sitter.core.autocommit import commiter, reader, writer
from graph_sitter.core.expressions import Name
from graph_sitter.core.interfaces.editable import Editable
from graph_sitter.core.interfaces.importable import Importable
from graph_sitter.core.interfaces.usable import Usable
from graph_sitter.core.node_id_factory import NodeId
from graph_sitter.core.statements.statement import Statement
from graph_sitter.core.symbol_groups.comment_group import CommentGroup
from graph_sitter.enums import NodeType, SymbolType
from graph_sitter.writer_decorators import apidoc, noapidoc
from graph_sitter.core.detached_symbols.code_block import CodeBlock
from graph_sitter.core.export import Export
from graph_sitter.core.file import SourceFile
from graph_sitter.core.import_resolution import Import
from graph_sitter.core.interfaces.has_block import HasBlock

if TYPE_CHECKING:
    ...
Parent = TypeVar("Parent", bound="HasBlock")
TCodeBlock = TypeVar("TCodeBlock", bound="CodeBlock")
@apidoc
class Symbol(Usable[Statement["CodeBlock[Parent, ...]"]], Generic[Parent, TCodeBlock]):
    """Abstract representation of a Symbol in a Codebase. A Symbol is a top-level entity in a file,
    e.g. a Function, Class, GlobalVariable, etc.

    """
    symbol_type: SymbolType
    node_type: Literal[NodeType.SYMBOL] = ...
    def __init__(self, ts_node: TSNode, file_id: NodeId, G: CodebaseGraph, parent: Statement[CodeBlock[Parent, ...]], name_node: TSNode | None = ..., name_node_type: type[Name] = ...) -> None:
        ...
    
    def __rich_repr__(self) -> rich.repr.Result:
        ...
    
    @property
    @noapidoc
    def parent_symbol(self) -> Symbol | SourceFile | Import | Export:
        """Returns the parent symbol of the symbol."""
        ...
    
    @property
    @reader(cache=False)
    def extended_nodes(self) -> list[Editable]:
        """Returns a list of Editable nodes associated with this symbol, including extended symbols.

        Extended symbols include `export`, `public`, `decorator`, comments, and inline comments.

        Args:
            self: The symbol instance.

        Returns:
            list[Editable]: A list of Editable nodes containing the current symbol and its extended symbols,
                sorted in the correct order.
        """
        ...
    
    @writer
    def edit(self, new_src: str, fix_indentation: bool = ..., priority: int = ..., dedupe: bool = ...) -> None:
        """Replace the source of this node with new_src.

        Edits the source code of this node by replacing it with the provided new source code. If specified, the indentation of
        the new source can be adjusted to match the current text's indentation.

        Args:
            new_src (str): The new source code to replace the current source with.
            fix_indentation (bool): If True, adjusts the indentation of new_src to match the current text's indentation. Defaults to False.
            priority (int): The priority of this edit. Higher priority edits take precedence. Defaults to 0.
            dedupe (bool): If True, prevents duplicate edits. Defaults to True.

        Returns:
            None
        """
        ...
    
    @property
    @reader
    def source(self) -> str:
        """Returns the source code of the symbol.

        Gets the source code of the symbol from its extended representation, which includes any comments, docstrings, access identifiers, or decorators.

        Returns:
            str: The complete source code of the symbol including any extended nodes.
        """
        ...
    
    @source.setter
    @writer
    def source(self, value) -> None:
        """Sets the source code text of this Symbol.

        Replaces the current source code text with a new value by calling the edit method.

        Args:
            value (str): The new source code text to replace the current text with.

        Returns:
            None
        """
        ...
    
    @property
    @abstractmethod
    @reader
    def comment(self) -> CommentGroup | None:
        """Returns the comment group associated with the symbol, if any.

        Returns:
            CommentGroup | None: The comment group containing all comments associated with the symbol if it exists, None otherwise.
        """
        ...
    
    @property
    @abstractmethod
    @reader
    def inline_comment(self) -> CommentGroup | None:
        """Returns the inline comment group associated with the symbol, if any.

        Returns:
            CommentGroup | None: The inline comment group object associated with the symbol, or None if no inline comment exists.
        """
        ...
    
    @abstractmethod
    @writer
    def set_comment(self, comment: str) -> None:
        """Sets a comment to the symbol.

        Updates or creates a comment for the symbol. If a comment already exists, it will be overridden.
        If no comment exists, a new comment group will be created.

        Args:
            comment (str): The comment text to set.

        Returns:
            None
        """
        ...
    
    @abstractmethod
    @writer
    def add_comment(self, comment: str) -> None:
        """Adds a comment to the symbol.

        Adds a comment to the top of a symbol. If a comment group already exists, the new comment will be appended
        to the existing comment group. If no comment group exists, a new comment group will be created.

        Args:
            comment (str): The comment text to add.

        Returns:
            None
        """
        ...
    
    @abstractmethod
    @writer
    def set_inline_comment(self, comment: str) -> None:
        """Sets an inline comment to the symbol.

        Adds or updates an inline comment for the symbol with the provided text. If an inline comment already exists,
        it will be overridden. If no inline comment exists, a new inline comment will be created.

        Args:
            comment (str): The text of the inline comment to be added or updated.

        Returns:
            None
        """
        ...
    
    @noapidoc
    @commiter
    def parse(self, G: CodebaseGraph) -> None:
        """Adds itself as a symbol node in the graph, and an edge from the parent file to itself."""
        ...
    
    @writer
    def insert_before(self, new_src: str, fix_indentation: bool = ..., newline: bool = ..., priority: int = ..., dedupe: bool = ..., extended: bool = ...) -> None:
        """Inserts text before the current symbol node in the Abstract Syntax Tree.

        Handles insertion of new source code before a symbol, with special handling for extended nodes like comments and decorators.
        The insertion can be done either before the symbol itself or before its extended nodes.

        Args:
            new_src (str): The source code text to insert.
            fix_indentation (bool): Whether to adjust the indentation of new_src to match current text. Defaults to False.
            newline (bool): Whether to add a newline after insertion. Defaults to True.
            priority (int): Priority of this edit operation. Higher priority edits are applied first. Defaults to 0.
            dedupe (bool): Whether to remove duplicate insertions. Defaults to True.
            extended (bool): Whether to insert before extended nodes like comments and decorators. Defaults to True.

        Returns:
            None
        """
        ...
    
    def move_to_file(self, file: SourceFile, include_dependencies: bool = ..., strategy: str = ...) -> None:
        """Moves the given symbol to a new file and updates its imports and references.

        This method moves a symbol to a new file and updates all references to that symbol throughout the codebase. The way imports are handled can be controlled via the strategy parameter.

        Args:
            file (SourceFile): The destination file to move the symbol to.
            include_dependencies (bool): If True, moves all dependencies of the symbol to the new file. If False, adds imports for the dependencies. Defaults to True.
            strategy (str): The strategy to use for updating imports. Can be either 'add_back_edge' or 'update_all_imports'. Defaults to 'update_all_imports'.
                - 'add_back_edge': Moves the symbol and adds an import in the original file
                - 'update_all_imports': Updates all imports and usages of the symbol to reference the new file

        Returns:
            None

        Raises:
            AssertionError: If an invalid strategy is provided.
        """
        ...
    
    @property
    @reader
    @noapidoc
    def is_top_level(self) -> bool:
        """Is this symbol a top-level symbol: does it have a level of 0?"""
        ...
    
    @writer
    def add_keyword(self, keyword: str): # -> None:
        """Insert a keyword in the appropriate place before this symbol if it doesn't already exist.

        This method adds a keyword (e.g., 'public', 'async', 'static') in the syntactically appropriate
        position relative to other keywords. If the keyword already exists, no action is taken.

        Args:
            keyword (str): The keyword to be inserted. Must be a valid keyword in the language context.

        Raises:
            AssertionError: If the provided keyword is not in the language's valid keywords list.
        """
        ...
    
    @property
    @noapidoc
    def descendant_symbols(self) -> list[Importable]:
        ...
    


