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

from abc import abstractmethod
from typing import Generic, TYPE_CHECKING, 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.detached_symbols.parameter import Parameter
from graph_sitter.core.import_resolution import Import, WildcardImport
from graph_sitter.core.interfaces.callable import Callable
from graph_sitter.core.interfaces.chainable import Chainable
from graph_sitter.core.interfaces.has_block import HasBlock
from graph_sitter.core.interfaces.importable import Importable
from graph_sitter.core.interfaces.supports_generic import SupportsGenerics
from graph_sitter.core.statements.return_statement import ReturnStatement
from graph_sitter.core.symbol import Symbol
from graph_sitter.extensions.utils import cached_property
from graph_sitter.writer_decorators import apidoc, noapidoc
from graph_visualization.enums import VizNode
from graph_sitter.core.export import Export
from graph_sitter.core.expressions.type import Type
from graph_sitter.core.file import File

if TYPE_CHECKING:
    ...
TFunction = TypeVar("TFunction", bound="Function")
TDecorator = TypeVar("TDecorator", bound="Decorator")
TCodeBlock = TypeVar("TCodeBlock", bound="CodeBlock")
TParameter = TypeVar("TParameter", bound="Parameter")
TType = TypeVar("TType", bound="Type")
@apidoc
class Function(SupportsGenerics[TType], HasBlock[TCodeBlock, TDecorator], Callable[TParameter, TType], Chainable, Generic[TFunction, TDecorator, TCodeBlock, TParameter, TType]):
    """Abstract representation of a Function.

    Attributes:
        return_type: the return type annotation of the function
    """
    symbol_type = ...
    @property
    @abstractmethod
    def is_private(self) -> bool:
        """Determines if a function has a private access modifier.

        A function is considered private if it starts with an underscore (_) in Python, or has a private keyword in other languages.

        Returns:
            bool: True if the function has a private access modifier, False otherwise.
        """
        ...
    
    @property
    @abstractmethod
    def is_magic(self) -> bool:
        """Returns True if function is a magic method.

        Determines if the function is a magic method based on Python's double underscore naming convention.
        A magic method in Python is a special method surrounded by double underscores (e.g., __init__, __str__).

        Returns:
            bool: True if the function is a magic method, False otherwise.
        """
        ...
    
    @property
    def is_overload(self) -> bool:
        """Indicates whether the function is an overloaded function in a multi-function definition.

        Determines if this function is part of a function overload group in the codebase. This property helps identify
        functions that have multiple implementations with different parameter types.

        Returns:
            bool: False, as this base implementation does not support overloads.
        """
        ...
    
    @property
    @abstractmethod
    def is_property(self) -> bool:
        """Returns whether this function is a property.

        Determines if the function has been decorated with `@property` decorator.

        Returns:
            bool: True if the function is a property, False otherwise.
        """
        ...
    
    @property
    def is_method(self) -> bool:
        """Returns whether the function is a method of a class.

        Determines if this function is defined within a class context. It checks if the parent of the function is a Class.

        Returns:
            bool: True if the function is a method within a class, False otherwise.
        """
        ...
    
    @property
    def is_constructor(self) -> bool:
        """Determines if the current function is a constructor method.

        A constructor method is a special method associated with a class. This property checks if the function
        is both a class method and has a name that matches the class's constructor keyword.

        Returns:
            bool: True if the function is a constructor method of a class, False otherwise.
        """
        ...
    
    @property
    def is_async(self) -> bool:
        """Returns True if the function is asynchronous.

        A property that determines whether the function has been defined with the 'async' keyword.

        Returns:
            bool: True if the function is asynchronous, False otherwise.
        """
        ...
    
    @noapidoc
    @reader
    def resolve_name(self, name: str, start_byte: int | None = ...) -> Symbol | Import | WildcardImport | None:
        ...
    
    @cached_property
    @noapidoc
    def valid_symbol_names(self) -> list[Importable]:
        ...
    
    @property
    @abstractmethod
    @reader
    def function_signature(self) -> str:
        """Returns the signature of the function as a string.

        A property that returns the complete function signature including its declaration, parameters, and return type annotation. The signature format
        varies based on the language, but follows the standard syntax for function declarations in that language.

        Returns:
            str: A string representation of the function's complete signature.
        """
        ...
    
    @property
    @reader
    def return_statements(self) -> list[ReturnStatement]:
        """Returns a list of all return statements within this function's body.

        Provides access to return statements in the function's code block, which is useful for analyzing return patterns,
        identifying early returns, and examining return types.

        Args:
            None

        Returns:
            list[ReturnStatement]: A list of all return statements found within the function's body.
        """
        ...
    
    @property
    @reader
    def nested_functions(self) -> list[TFunction]:
        """Returns a list of nested functions defined within this function's code block.

        Retrieves all functions that are defined within the current function's body. The functions are sorted by their position in the file.

        Returns:
            list[TFunction]: A list of Function objects representing nested functions within this function's body, sorted by position in the file.
        """
        ...
    
    @writer
    def set_return_type(self, new_return_type: str) -> None:
        """Sets the return type annotation for the function.

        Sets or updates the return type annotation of the function. If an empty string is provided,
        the return type annotation will be removed.

        Args:
            new_return_type (str): The new return type annotation to be set. Use an empty string to remove
                the return type annotation.

        Returns:
            None
        """
        ...
    
    @writer
    def asyncify(self) -> None:
        """Modifies the function to be asynchronous.

        Converts a synchronous function to be asynchronous by adding the 'async' keyword to its definition if it is not already
        marked as asynchronous.

        Returns:
            None

        Note:
            This method has no effect if the function is already asynchronous.
        """
        ...
    
    @writer
    def rename_local_variable(self, old_var_name: str, new_var_name: str, fuzzy_match: bool = ...) -> None:
        """Renames a local variable and all its usages within a function body.

        The method searches for matches of the old variable name within the function's code block and replaces them with the new variable name. It excludes parameter names from being renamed.

        Args:
            old_var_name (str): The current name of the local variable to be renamed.
            new_var_name (str): The new name to give to the local variable.
            fuzzy_match (bool, optional): If True, matches variable names that contain old_var_name. Defaults to False.

        Returns:
            None: The method modifies the AST in place.
        """
        ...
    
    @writer
    def insert_statements(self, lines: str, index: int = ...): # -> None:
        """Inserts lines of code into the function body at the specified index.

        Adds the provided lines as statements within the function's body at the given position. If index is 0, the lines will be prepended at the start of the function body.

        Args:
            lines (str): The code lines to insert into the function body.
            index (int, optional): The position in the function body where the lines should be inserted. Defaults to 0.

        Raises:
            ValueError: If the provided index is out of range for the function's statements.
        """
        ...
    
    @writer
    def prepend_statements(self, lines: str) -> None:
        """Prepends the provided code to the beginning of the function body.

        Args:
            lines (str): The code to be prepended to the function body.

        Returns:
            None

        Note:
            This method handles indentation automatically to maintain proper code formatting.
        """
        ...
    
    @writer
    def add_statements(self, lines: str) -> None:
        """Adds statements to the end of a function body.

        Adds the provided lines of code to the end of the function's code block. The method handles proper indentation automatically.

        Args:
            lines (str): The lines of code to be added at the end of the function body.

        Returns:
            None
        """
        ...
    
    @property
    @noapidoc
    def viz(self) -> VizNode:
        ...
    
    @property
    @noapidoc
    def parent_symbol(self) -> Symbol | File | Import | Export:
        """Searches up its parent stack until it finds a top level symbol."""
        ...
    
    @property
    @reader
    def function_calls(self) -> list[FunctionCall]:
        """Gets all function calls within the function and its parameters.

        Retrieves all function calls that appear within this function's body and within its parameter
        declarations, sorted by position in the file.

        Args:
            None

        Returns:
            list[FunctionCall]: A sorted list of all function calls within the function and its parameters.
            Function calls may appear multiple times in the list.
        """
        ...
    
    @property
    @reader
    def inferred_return_type(self) -> str | None:
        """Gets the inferred type of the function from the language's native language engine / compiler.

        Only enabled for specific languages that support native type inference.
        """
        ...
    
    @property
    @noapidoc
    def descendant_symbols(self) -> list[Importable]:
        ...
    


