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

from graph_sitter.codebase.codebase_graph import CodebaseGraph
from graph_sitter.core.autocommit import reader, writer
from graph_sitter.core.file import SourceFile
from graph_sitter.core.interface import Interface
from graph_sitter.enums import ImportType
from graph_sitter.python import PyAssignment
from graph_sitter.python.class_definition import PyClass
from graph_sitter.python.detached_symbols.code_block import PyCodeBlock
from graph_sitter.python.expressions.type import PyType
from graph_sitter.python.function import PyFunction
from graph_sitter.python.import_resolution import PyImport
from graph_sitter.python.interfaces.has_block import PyHasBlock
from graph_sitter.python.statements.attribute import PyAttribute
from graph_sitter.python.symbol import PySymbol
from graph_sitter.writer_decorators import noapidoc, py_apidoc

@py_apidoc
class PyFile(SourceFile[PyImport, PyFunction, PyClass, PyAssignment, Interface[PyCodeBlock, PyAttribute, PyFunction, PyType], PyCodeBlock], PyHasBlock):
    """SourceFile representation for Python codebase"""
    programming_language = ...
    @staticmethod
    def get_extensions() -> list[str]:
        """Returns the file extensions associated with Python files.

        Gets the list of file extensions that are considered Python files.

        Returns:
            list[str]: A list containing '.py' as the only Python file extension.
        """
        ...
    
    def symbol_can_be_added(self, symbol: PySymbol) -> bool:
        """Checks if a Python symbol can be added to this Python source file.

        Verifies whether a given Python symbol is compatible with and can be added to this Python source file. Currently always returns True as Python files can contain any Python symbol type.

        Args:
            symbol (PySymbol): The Python symbol to check for compatibility with this file.

        Returns:
            bool: Always returns True as Python files can contain any Python symbol type.
        """
        ...
    
    @noapidoc
    def get_import_module_name_for_file(self, filepath: str, G: CodebaseGraph) -> str:
        """Returns the module name that this file gets imported as

        For example, `my/package/name.py` => `my.package.name`
        """
        ...
    
    @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 symbol.

        Constructs a Python import statement based on the provided parameters, handling different import types and module paths.

        Args:
            alias (str | None, optional): Alias to use for the imported symbol. Defaults to None.
            module (str | None, optional): Module path to import from. If None, uses module name from source. Defaults to None.
            import_type (ImportType, optional): Type of import statement to generate. Defaults to ImportType.UNKNOWN.
            is_type_import (bool, optional): Whether this is a type import. Currently unused. Defaults to False.

        Returns:
            str: A formatted import string in the form of 'from {module} import {symbol}' with optional alias or wildcard syntax.
        """
        ...
    
    @reader
    def get_import_insert_index(self, import_string) -> int | None:
        """Determines the index position where a new import statement should be inserted in a Python file.

        The function determines the optimal position for inserting a new import statement, following Python's import ordering conventions.
        Future imports are placed at the top of the file, followed by all other imports.

        Args:
            import_string (str): The import statement to be inserted.

        Returns:
            int | None: The index where the import should be inserted. Returns 0 for future imports or if there are no existing imports after future imports.
            Returns None if there are no imports in the file.
        """
        ...
    
    @writer
    def add_import_from_import_string(self, import_string: str) -> None:
        """Adds an import statement to the file from a string representation.

        This method adds a new import statement to the file, handling placement based on existing imports.
        Future imports are placed at the top of the file, followed by regular imports.

        Args:
            import_string (str): The string representation of the import statement to add (e.g., 'from module import symbol').

        Returns:
            None: This function modifies the file in place.
        """
        ...
    
    @noapidoc
    def remove_unused_exports(self) -> None:
        """Removes unused exports from the file. NO-OP for python"""
        ...
    


