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

from abc import abstractmethod
from typing import Generic, TypeVar
from graph_sitter.core.autocommit import reader, writer
from graph_sitter.core.detached_symbols.code_block import CodeBlock
from graph_sitter.core.detached_symbols.decorator import Decorator
from graph_sitter.core.detached_symbols.function_call import FunctionCall
from graph_sitter.core.expressions import Expression
from graph_sitter.core.symbol_groups.comment_group import CommentGroup
from graph_sitter.writer_decorators import apidoc

TCodeBlock = TypeVar("TCodeBlock", bound="CodeBlock")
TDecorator = TypeVar("TDecorator", bound="Decorator")
@apidoc
class HasBlock(Expression, Generic[TCodeBlock, TDecorator]):
    """An interface for any code object that has a block of code, e.g. a function, class, etc."""
    code_block: TCodeBlock
    @property
    @reader
    def function_calls(self) -> list[FunctionCall]:
        """Returns all function calls within the code block and its decorators.

        Args:
            None

        Returns:
            list[FunctionCall]: A sorted list of FunctionCall objects representing all
            function calls in the code block and its decorators. The list may contain
            duplicates.
        """
        ...
    
    @property
    @abstractmethod
    def is_decorated(self) -> bool:
        """Check if the symbol has decorators.

        A helper method to determine if a function, class, or method has any
        applied decorators.

        Returns:
            bool: True if the symbol has one or more decorators, False otherwise.
        """
        ...
    
    @property
    @abstractmethod
    def decorators(self) -> list[TDecorator]:
        """Returns list of all decorators on this Symbol.

        Gets all decorators associated with a code entity (function, class, method).

        Returns:
            list[TDecorator]: A list of Decorator objects. Empty list if no decorators are present.
        """
        ...
    
    @writer
    def add_decorator(self, new_decorator: str, skip_if_exists: bool = ...) -> bool:
        """Adds a decorator to a function or method.

        Adds a new decorator to the symbol's definition before the first non-comment extended node with proper indentation.

        Args:
            new_decorator (str): The decorator to add, including the '@' symbol.
            skip_if_exists (bool, optional): If True, skips adding if the decorator exists.

        Returns:
            bool: True if the decorator was added, False if skipped.
        """
        ...
    
    @property
    @abstractmethod
    @reader
    def docstring(self) -> CommentGroup | None:
        """Retrieves the docstring of the expression.

        Args:
            None

        Returns:
            CommentGroup | None: The docstring as a CommentGroup if it exists, None otherwise.
        """
        ...
    
    @abstractmethod
    @writer
    def set_docstring(self, docstring: str) -> None:
        """Sets or updates the docstring for the current entity.

        Modifies the entity's docstring by either replacing an existing one or creating a new one.

        Args:
            docstring (str): The new docstring content to set.

        Returns:
            None: This method doesn't return anything.
        """
        ...
    


