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

from enum import StrEnum
from typing import TYPE_CHECKING
from graph_sitter.core.autocommit import reader
from graph_sitter.core.statements.comment import Comment
from graph_sitter.writer_decorators import py_apidoc

if TYPE_CHECKING:
    ...
@py_apidoc
class PyCommentType(StrEnum):
    """Enum representing different types of comments."""
    SINGLE_LINE = ...
    MULTI_LINE_QUOTE = ...
    MULTI_LINE_DOUBLE_QUOTE = ...
    UNKNOWN = ...


@py_apidoc
class PyComment(Comment):
    """Abstract representation of python comments"""
    @property
    @reader
    def comment_type(self) -> PyCommentType:
        """Determines the type of Python comment based on its syntax.

        Parses the comment and determines its type based on the leading characters.
        For Python comments, it identifies if it is a single-line comment (#),
        a multi-line comment with single quotes ('''), or a multi-line comment with double quotes (\"\"\").

        Returns:
            PyCommentType: The type of comment, one of:
                - SINGLE_LINE: For comments starting with '#'
                - MULTI_LINE_QUOTE: For comments wrapped in '''
                - MULTI_LINE_DOUBLE_QUOTE: For comments wrapped in \"\"\"
                - UNKNOWN: If the comment type cannot be determined
        """
        ...
    
    @property
    @reader
    def google_style(self) -> bool:
        """Determines if a Python docstring follows Google style formatting.

        Checks if a multi-line docstring follows Google style conventions by starting with descriptive text
        immediately after the opening quotes rather than on a new line.

        Returns:
            bool: True if the docstring follows Google style formatting, False otherwise.
        """
        ...
    
    @staticmethod
    def generate_comment(new_src: str, comment_type: PyCommentType, force_multiline: bool = ..., google_style: bool = ...) -> str:
        """Converts text content into a Python comment block.

        Takes a string of text content and converts it into a Python comment block based on the specified comment type.
        Supports single-line comments and multi-line comments with either single or double quotes.

        Args:
            new_src (str): The text content to be converted into a comment.
            comment_type (PyCommentType): The type of comment to generate (SINGLE_LINE, MULTI_LINE_QUOTE, or MULTI_LINE_DOUBLE_QUOTE).
            force_multiline (bool, optional): When True, forces multi-line format even for single-line content. Defaults to False.
            google_style (bool, optional): When True, formats multi-line comments in Google style without newline after opening quotes. Defaults to True.

        Returns:
            str: The formatted comment block with appropriate comment syntax.
        """
        ...
    
    @staticmethod
    def clean_comment(comment: str) -> str:
        """Cleans a comment block by removing comment symbols, leading/trailing whitespace, and standardizing indentation.

        Takes a comment string and processes it to extract just the content by removing comment symbols (# or triple quotes),
        adjusting indentation, and stripping excess whitespace.

        Args:
            comment (str): The raw comment block to be cleaned. Can be a single-line comment or multi-line docstring.

        Returns:
            str: The cleaned comment text with comment symbols and excess whitespace removed.
        """
        ...
    


