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

from typing import Any, NamedTuple, TYPE_CHECKING
from docutils import nodes
from docutils.parsers.rst import directives
from sphinx import addnodes
from sphinx.addnodes import desc_signature, pending_xref
from sphinx.directives import ObjectDescription
from sphinx.domains import Domain, Index, IndexEntry, ObjType
from sphinx.pycode.parser import Token, TokenProcessor
from sphinx.roles import XRefRole
from sphinx.util.docfields import Field, GroupedField, TypedField
from sphinx.util.docutils import SphinxDirective
from collections.abc import Iterable, Iterator
from docutils.nodes import Element, Node
from docutils.parsers.rst.states import Inliner
from sphinx.application import Sphinx
from sphinx.builders import Builder
from sphinx.environment import BuildEnvironment
from sphinx.util.typing import OptionSpec, TextlikeNode

"""The Python domain."""
if TYPE_CHECKING:
    ...
logger = ...
py_sig_re = ...
pairindextypes = ...
class ObjectEntry(NamedTuple):
    docname: str
    node_id: str
    objtype: str
    aliased: bool
    ...


class ModuleEntry(NamedTuple):
    docname: str
    node_id: str
    synopsis: str
    platform: str
    deprecated: bool
    ...


def parse_reftarget(reftarget: str, suppress_prefix: bool = ...) -> tuple[str, str, str, bool]:
    """Parse a type string and return (reftype, reftarget, title, refspecific flag)"""
    ...

def type_to_xref(target: str, env: BuildEnvironment, *, suppress_prefix: bool = ...) -> addnodes.pending_xref:
    """Convert a type string to a cross reference node."""
    ...

class _TypeParameterListParser(TokenProcessor):
    def __init__(self, sig: str) -> None:
        ...
    
    def fetch_type_param_spec(self) -> list[Token]:
        ...
    
    def parse(self) -> None:
        ...
    


class PyXrefMixin:
    def make_xref(self, rolename: str, domain: str, target: str, innernode: type[TextlikeNode] = ..., contnode: Node | None = ..., env: BuildEnvironment | None = ..., inliner: Inliner | None = ..., location: Node | None = ...) -> Node:
        ...
    
    def make_xrefs(self, rolename: str, domain: str, target: str, innernode: type[TextlikeNode] = ..., contnode: Node | None = ..., env: BuildEnvironment | None = ..., inliner: Inliner | None = ..., location: Node | None = ...) -> list[Node]:
        ...
    


class PyField(PyXrefMixin, Field):
    ...


class PyGroupedField(PyXrefMixin, GroupedField):
    ...


class PyTypedField(PyXrefMixin, TypedField):
    ...


class PyObject(ObjectDescription[tuple[str, str]]):
    """
    Description of a general Python object.

    :cvar allow_nesting: Class is an object that allows for nested namespaces
    :vartype allow_nesting: bool
    """
    option_spec: OptionSpec = ...
    doc_field_types = ...
    allow_nesting = ...
    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
        """May return a prefix to put before the object name in the
        signature.
        """
        ...
    
    def needs_arglist(self) -> bool:
        """May return true if an empty argument list is to be generated even if
        the document contains none.
        """
        ...
    
    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
        """Transform a Python signature into RST nodes.

        Return (fully qualified name of the thing, classname if any).

        If inside a class, the current class name is handled intelligently:
        * it is stripped from the displayed name if present
        * it is added to the full name (return value) if not present
        """
        ...
    
    def get_index_text(self, modname: str, name: tuple[str, str]) -> str:
        """Return the text for the index entry of the object."""
        ...
    
    def add_target_and_index(self, name_cls: tuple[str, str], sig: str, signode: desc_signature) -> None:
        ...
    
    def before_content(self) -> None:
        """Handle object nesting before content

        :py:class:`PyObject` represents Python language constructs. For
        constructs that are nestable, such as a Python classes, this method will
        build up a stack of the nesting hierarchy so that it can be later
        de-nested correctly, in :py:meth:`after_content`.

        For constructs that aren't nestable, the stack is bypassed, and instead
        only the most recent object is tracked. This object prefix name will be
        removed with :py:meth:`after_content`.
        """
        ...
    
    def after_content(self) -> None:
        """Handle object de-nesting after content

        If this class is a nestable object, removing the last nested class prefix
        ends further nesting in the object.

        If this class is not a nestable object, the list of classes should not
        be altered as we didn't affect the nesting levels in
        :py:meth:`before_content`.
        """
        ...
    


class PyFunction(PyObject):
    """Description of a function."""
    option_spec: OptionSpec = ...
    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
        ...
    
    def needs_arglist(self) -> bool:
        ...
    
    def add_target_and_index(self, name_cls: tuple[str, str], sig: str, signode: desc_signature) -> None:
        ...
    
    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
        ...
    


class PyDecoratorFunction(PyFunction):
    """Description of a decorator."""
    def run(self) -> list[Node]:
        ...
    
    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
        ...
    
    def needs_arglist(self) -> bool:
        ...
    


class PyVariable(PyObject):
    """Description of a variable."""
    option_spec: OptionSpec = ...
    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
        ...
    
    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
        ...
    


class PyClasslike(PyObject):
    """
    Description of a class-like object (classes, interfaces, exceptions).
    """
    option_spec: OptionSpec = ...
    allow_nesting = ...
    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
        ...
    
    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
        ...
    


class PyMethod(PyObject):
    """Description of a method."""
    option_spec: OptionSpec = ...
    def needs_arglist(self) -> bool:
        ...
    
    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
        ...
    
    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
        ...
    


class PyClassMethod(PyMethod):
    """Description of a classmethod."""
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


class PyStaticMethod(PyMethod):
    """Description of a staticmethod."""
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


class PyDecoratorMethod(PyMethod):
    """Description of a decoratormethod."""
    def run(self) -> list[Node]:
        ...
    
    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
        ...
    
    def needs_arglist(self) -> bool:
        ...
    


class PyAttribute(PyObject):
    """Description of an attribute."""
    option_spec: OptionSpec = ...
    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
        ...
    
    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
        ...
    


class PyProperty(PyObject):
    """Description of an attribute."""
    option_spec = ...
    def handle_signature(self, sig: str, signode: desc_signature) -> tuple[str, str]:
        ...
    
    def get_signature_prefix(self, sig: str) -> list[nodes.Node]:
        ...
    
    def get_index_text(self, modname: str, name_cls: tuple[str, str]) -> str:
        ...
    


class PyModule(SphinxDirective):
    """
    Directive to mark description of a new module.
    """
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


class PyCurrentModule(SphinxDirective):
    """
    This directive is just to tell Sphinx that we're documenting
    stuff in module foo, but links to module foo won't lead here.
    """
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


class PyXRefRole(XRefRole):
    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str) -> tuple[str, str]:
        ...
    


def filter_meta_fields(app: Sphinx, domain: str, objtype: str, content: Element) -> None:
    """Filter ``:meta:`` field from its docstring."""
    ...

class PythonModuleIndex(Index):
    """
    Index subclass to provide the Python module index.
    """
    name = ...
    localname = ...
    shortname = ...
    def generate(self, docnames: Iterable[str] | None = ...) -> tuple[list[tuple[str, list[IndexEntry]]], bool]:
        ...
    


class PythonDomain(Domain):
    """Python language domain."""
    name = ...
    label = ...
    object_types: dict[str, ObjType] = ...
    directives = ...
    roles = ...
    initial_data: dict[str, dict[str, tuple[Any]]] = ...
    indices = ...
    @property
    def objects(self) -> dict[str, ObjectEntry]:
        ...
    
    def note_object(self, name: str, objtype: str, node_id: str, aliased: bool = ..., location: Any = ...) -> None:
        """Note a python object for cross reference.

        .. versionadded:: 2.1
        """
        ...
    
    @property
    def modules(self) -> dict[str, ModuleEntry]:
        ...
    
    def note_module(self, name: str, node_id: str, synopsis: str, platform: str, deprecated: bool) -> None:
        """Note a python module for cross reference.

        .. versionadded:: 2.1
        """
        ...
    
    def clear_doc(self, docname: str) -> None:
        ...
    
    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
        ...
    
    def find_obj(self, env: BuildEnvironment, modname: str, classname: str, name: str, type: str | None, searchmode: int = ...) -> list[tuple[str, ObjectEntry]]:
        """Find a Python object for "name", perhaps using the given module
        and/or classname.  Returns a list of (name, object entry) tuples.
        """
        ...
    
    def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, type: str, target: str, node: pending_xref, contnode: Element) -> Element | None:
        ...
    
    def resolve_any_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder, target: str, node: pending_xref, contnode: Element) -> list[tuple[str, Element]]:
        ...
    
    def get_objects(self) -> Iterator[tuple[str, str, str, str, str, int]]:
        ...
    
    def get_full_qualified_name(self, node: Element) -> str | None:
        ...
    


def builtin_resolver(app: Sphinx, env: BuildEnvironment, node: pending_xref, contnode: Element) -> Element | None:
    """Do not emit nitpicky warnings for built-in types."""
    ...

def setup(app: Sphinx) -> dict[str, Any]:
    ...

