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

from functools import cached_property
from graph_sitter.core.autocommit import reader, writer
from graph_sitter.core.interfaces.has_block import HasBlock
from graph_sitter.python.detached_symbols.code_block import PyCodeBlock
from graph_sitter.python.detached_symbols.decorator import PyDecorator
from graph_sitter.python.symbol_groups.comment_group import PyCommentGroup
from graph_sitter.writer_decorators import py_apidoc

@py_apidoc
class PyHasBlock(HasBlock[PyCodeBlock, PyDecorator]):
    """Extends HasBlock for Python codebases."""
    @property
    @reader
    def is_decorated(self) -> bool:
        """Returns whether the symbol is decorated with decorators.

        Checks if the symbol has a parent and if that parent's type is a decorated definition.

        Returns:
            bool: True if the symbol has decorators, False otherwise.
        """
        ...
    
    @property
    @reader
    def decorators(self) -> list[PyDecorator]:
        """Returns a list of decorators associated with this symbol.

        Retrieves all decorator nodes from the symbol's parent TreeSitter node and converts them into PyDecorator objects.

        Args:
            None

        Returns:
            list[PyDecorator]: A list of PyDecorator objects representing the decorators on the symbol. Returns an empty list if the symbol is not decorated.

        Note:
            This property should be used in conjunction with is_decorated to check if the symbol has any decorators.
        """
        ...
    
    @cached_property
    @reader
    def docstring(self) -> PyCommentGroup | None:
        """Gets the function's docstring.

        Retrieves the docstring of the function as a PyCommentGroup object. If the function has no docstring, returns None.

        Returns:
            PyCommentGroup | None: The docstring of the function as a PyCommentGroup, or None if no docstring exists.
        """
        ...
    
    @writer
    def set_docstring(self, docstring: str, auto_format: bool = ..., clean_format: bool = ..., force_multiline: bool = ...) -> None:
        """Sets or updates a docstring for a Python function or class.

        Updates the existing docstring if one exists, otherwise creates a new docstring. The docstring can be automatically formatted and cleaned before being set.

        Args:
            docstring (str): The docstring content to set.
            auto_format (bool, optional): Whether to format the text into a proper docstring format. Defaults to True.
            clean_format (bool, optional): Whether to clean and normalize the docstring format before insertion. Defaults to True.
            force_multiline (bool, optional): Whether to force single-line comments to be converted to multi-line format. Defaults to False.

        Returns:
            None
        """
        ...
    


