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

from typing import TYPE_CHECKING
from tree_sitter import Node as TSNode
from graph_sitter.codebase.codebase_graph import CodebaseGraph
from graph_sitter.core.autocommit import reader, writer
from graph_sitter.core.interfaces.has_block import HasBlock
from graph_sitter.core.node_id_factory import NodeId
from graph_sitter.core.symbol import Symbol
from graph_sitter.enums import ImportType
from graph_sitter.python.statements.comment import PyCommentType
from graph_sitter.python.symbol_groups.comment_group import PyCommentGroup
from graph_sitter.writer_decorators import noapidoc, py_apidoc

if TYPE_CHECKING:
    ...
@py_apidoc
class PySymbol(Symbol["PyHasBlock", "PyCodeBlock"]):
    """Extends `Symbol` for Python codebases."""
    @classmethod
    @noapidoc
    def from_decorated_definition(cls, ts_node: TSNode, file_id: NodeId, G: CodebaseGraph, parent: HasBlock) -> Symbol:
        ...
    
    @property
    @reader
    def is_exported(self) -> bool:
        """Indicates whether a Python symbol is exported.

        In Python, all symbols are exported by default, so this property always returns True.

        Returns:
            bool: Always True, as Python symbols are exported by default.
        """
        ...
    
    @reader
    def get_import_string(self, alias: str | None = ..., module: str | None = ..., import_type: ImportType = ..., is_type_import: bool = ...) -> str:
        """Generates an import string for a Python symbol.

        Returns a string representation of how to import this symbol, with support for different import types and aliasing.

        Args:
            alias (str | None): Optional alias name for the import. If provided and different from symbol name, creates aliased import.
            module (str | None): Optional module name to import from. If not provided, uses the symbol's file's module name.
            import_type (ImportType): Type of import to generate. If WILDCARD, generates star import. Defaults to UNKNOWN.
            is_type_import (bool): Whether this is a type import. Currently unused. Defaults to False.

        Returns:
            str: The formatted import string. Will be one of:
                - "from {module} import * as {file_name}" (for WILDCARD imports)
                - "from {module} import {name} as {alias}" (for aliased imports)
                - "from {module} import {name}" (for standard imports)
        """
        ...
    
    @property
    @reader
    def comment(self) -> PyCommentGroup | None:
        """Retrieves the comment group associated with a Python symbol.

        A read-only property that returns the non-inline comment group (if any) that is associated with this symbol.
        Comments are considered associated with a symbol if they appear immediately before the symbol's definition.

        Returns:
            PyCommentGroup | None: A comment group object containing the symbol's comments, or None if no comments exist.
        """
        ...
    
    @property
    @reader
    def inline_comment(self) -> PyCommentGroup | None:
        """Returns the inline comment group associated with this symbol.

        Retrieves any inline comments attached to this symbol. An inline comment appears on the same line as the code it comments on.

        Args:
            self (PySymbol): The Python symbol to check for inline comments.

        Returns:
            PyCommentGroup | None: A comment group containing the inline comments if they exist, None otherwise.
        """
        ...
    
    @writer
    def set_comment(self, comment: str, auto_format: bool = ..., clean_format: bool = ..., comment_type: PyCommentType = ...) -> None:
        """Sets a comment for the Python symbol.

        Adds or modifies a comment associated with the Python symbol. If a comment already exists,
        it will be edited. If no comment exists, a new comment group will be created.

        Args:
            comment (str): The comment text to be added or set.
            auto_format (bool, optional): If True, automatically formats the text as a comment.
                Defaults to True.
            clean_format (bool, optional): If True, cleans the format of the comment before
                inserting. Defaults to True.
            comment_type (PyCommentType, optional): Type of comment to add (e.g., single line,
                multi line). Defaults to PyCommentType.SINGLE_LINE.

        Returns:
            None: This method modifies the symbol's comment in place.
        """
        ...
    
    @writer
    def add_comment(self, comment: str, auto_format: bool = ..., clean_format: bool = ..., comment_type: PyCommentType = ...) -> None:
        """Adds a new comment to the symbol.

        Appends a comment to the symbol either adding it to an existing comment group or creating a new one.

        Args:
            comment (str): The comment text to be added.
            auto_format (bool): Whether to automatically format the text into a proper comment format.
                Defaults to True.
            clean_format (bool): Whether to clean and normalize the comment text before adding.
                Defaults to True.
            comment_type (PyCommentType): The style of comment to add (e.g., single-line, multi-line).
                Defaults to PyCommentType.SINGLE_LINE.

        Returns:
            None

        Raises:
            None
        """
        ...
    
    @writer
    def set_inline_comment(self, comment: str, auto_format: bool = ..., clean_format: bool = ...) -> None:
        """Sets an inline comment to the symbol.

        Adds or replaces an inline comment for a Python symbol. If an inline comment exists,
        it will be replaced with the new comment. If no inline comment exists, a new one
        will be created at the end of the line.

        Args:
            comment (str): The inline comment text to add.
            auto_format (bool, optional): If True, formats the text into a proper inline
                comment with appropriate prefixes and spacing. Defaults to True.
            clean_format (bool, optional): If True, cleans the comment text before insertion
                by removing extra whitespace and comment markers. Defaults to True.

        Returns:
            None
        """
        ...
    


