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

from dataclasses import dataclass
from typing import Generic, Literal, Self, TYPE_CHECKING, TypeVar, overload
from graph_sitter.core.autocommit import reader
from graph_sitter.core.detached_symbols.function_call import FunctionCall
from graph_sitter.core.detached_symbols.parameter import Parameter
from graph_sitter.core.interfaces.usable import Usable
from graph_sitter.core.placeholder.placeholder import Placeholder
from graph_sitter.core.symbol_group import SymbolGroup
from graph_sitter.writer_decorators import apidoc
from graph_sitter.core.class_definition import Class
from graph_sitter.core.expressions.type import Type
from graph_sitter.core.external_module import ExternalModule
from graph_sitter.core.function import Function
from graph_sitter.core.symbol import Symbol

if TYPE_CHECKING:
    ...
@dataclass
class FunctionCallDefinition:
    """Represents a function call and its definitions.

    This class encapsulates information about a function call and the possible
    callable entities that define it.

    Attributes:
        call (FunctionCall): The function call object representing the invocation.
        callables (List[Union[Function, Class, ExternalModule]]): A list of callable
            entities that define the function being called.
    """
    call: FunctionCall
    callables: list[Function | Class | ExternalModule]
    ...


TParameter = TypeVar("TParameter", bound="Parameter")
TType = TypeVar("TType", bound="Type")
@apidoc
class Callable(Usable, Generic[TParameter, TType]):
    """Any symbol that can be invoked with arguments eg.

    Function, Class, Decorator, ExternalModule
    """
    _parameters: SymbolGroup[TParameter, Self] | list[TParameter]
    return_type: TType | Placeholder[Self]
    @property
    @reader(cache=False)
    def call_sites(self) -> list[FunctionCall]:
        """Returns all call sites (invocations) of this callable in the codebase.

        Finds all locations in the codebase where this callable is invoked/called. Call sites exclude imports, certain exports, and external references.

        Returns:
            list[FunctionCall]: A list of FunctionCall objects representing each invocation of this callable.
            Returns empty list if the callable has no name.
        """
        ...
    
    @property
    @reader
    def parameters(self) -> SymbolGroup[TParameter, Self] | list[TParameter]:
        """Retrieves all parameters of a callable symbol.

        This property provides access to all parameters of a callable symbol (function, class, decorator, or external module).
        Parameters are stored as a SymbolGroup containing Parameter objects.

        Returns:
            SymbolGroup[TParameter, Self] | list[TParameter]: A group of Parameter objects representing the callable's parameters,
            or an empty list if the callable has no parameters.
        """
        ...
    
    @reader
    def get_parameter(self, name: str) -> TParameter | None:
        """Gets a specific parameter from the callable's parameters list by name.

        Args:
            name (str): The name of the parameter to retrieve.

        Returns:
            TParameter | None: The parameter with the specified name, or None if no parameter with that name exists or if there are no parameters.
        """
        ...
    
    @reader
    def get_parameter_by_index(self, index: int) -> TParameter | None:
        """Returns the parameter at the given index.

        Retrieves a parameter from the callable's parameter list based on its positional index.

        Args:
            index (int): The index of the parameter to retrieve.

        Returns:
            TParameter | None: The parameter at the specified index, or None if the parameter list
                is empty or the index does not exist.
        """
        ...
    
    @reader
    def get_parameter_by_type(self, type: Symbol) -> TParameter | None:
        """Retrieves a parameter from the callable by its type.

        Searches through the callable's parameters to find a parameter with the specified type.

        Args:
            type (Symbol): The type to search for.

        Returns:
            TParameter | None: The parameter with the specified type, or None if no parameter is found or if the callable has no parameters.
        """
        ...
    
    @overload
    def call_graph_successors(self, *, include_classes: Literal[False], include_external: Literal[False]) -> list[Function]:
        ...
    
    @overload
    def call_graph_successors(self, *, include_classes: Literal[False], include_external: Literal[True] = ...) -> list[Function | ExternalModule]:
        ...
    
    @overload
    def call_graph_successors(self, *, include_classes: Literal[True] = ..., include_external: Literal[False]) -> list[Function | Class]:
        ...
    
    @overload
    def call_graph_successors(self, *, include_classes: Literal[True] = ..., include_external: Literal[True] = ...) -> list[Function | Class | ExternalModule]:
        ...
    
    @reader
    def call_graph_successors(self, *, include_classes: bool = ..., include_external: bool = ...) -> list[FunctionCallDefinition]:
        """Returns all function call definitions that are reachable from this callable.

        Analyzes the callable's implementation to find all function calls and their corresponding definitions. For classes, if a constructor exists,
        returns the call graph successors of the constructor; otherwise returns an empty list.

        Args:
            include_classes (bool): If True, includes class definitions in the results. Defaults to True.
            include_external (bool): If True, includes external module definitions in the results. Defaults to True.

        Returns:
            list[FunctionCallDefinition]: A list of FunctionCallDefinition objects, each containing a function call and its
                possible callable definitions (Functions, Classes, or ExternalModules based on include flags). Returns empty list
                for non-block symbols or classes without constructors.
        """
        ...
    


