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

import re
from __future__ import annotations
from typing import Any, Generic, TYPE_CHECKING, TypeVar, cast
from docutils import nodes
from docutils.parsers.rst import directives, roles
from sphinx import addnodes
from sphinx.addnodes import desc_signature
from sphinx.util import docutils
from sphinx.util.docfields import DocFieldTransformer, Field, TypedField
from sphinx.util.docutils import SphinxDirective
from sphinx.util.nodes import nested_parse_with_titles
from sphinx.util.typing import OptionSpec
from docutils.nodes import Node
from sphinx.application import Sphinx

"""Handlers for additional ReST directives."""
if TYPE_CHECKING:
    ...
nl_escape_re = ...
strip_backslash_re = ...
def optional_int(argument: str) -> int | None:
    """
    Check for an integer argument or None value; raise ``ValueError`` if not.
    """
    ...

ObjDescT = TypeVar('ObjDescT')
class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
    """
    Directive to describe a class, function or similar object.  Not used
    directly, but subclassed (in domain-specific directives) to add custom
    behavior.
    """
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    doc_field_types: list[Field] = ...
    domain: str | None = ...
    objtype: str
    indexnode: addnodes.index
    _doc_field_type_map: dict[str, tuple[Field, bool]] = ...
    def get_field_type_map(self) -> dict[str, tuple[Field, bool]]:
        ...
    
    def get_signatures(self) -> list[str]:
        """
        Retrieve the signatures to document from the directive arguments.  By
        default, signatures are given as arguments, one per line.
        """
        ...
    
    def handle_signature(self, sig: str, signode: desc_signature) -> ObjDescT:
        """
        Parse the signature *sig* into individual nodes and append them to
        *signode*. If ValueError is raised, parsing is aborted and the whole
        *sig* is put into a single desc_name node.

        The return value should be a value that identifies the object.  It is
        passed to :meth:`add_target_and_index()` unchanged, and otherwise only
        used to skip duplicates.
        """
        ...
    
    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
        """
        Add cross-reference IDs and entries to self.indexnode, if applicable.

        *name* is whatever :meth:`handle_signature()` returned.
        """
        ...
    
    def before_content(self) -> None:
        """
        Called before parsing content. Used to set information about the current
        directive context on the build environment.
        """
        ...
    
    def transform_content(self, contentnode: addnodes.desc_content) -> None:
        """
        Called after creating the content through nested parsing,
        but before the ``object-description-transform`` event is emitted,
        and before the info-fields are transformed.
        Can be used to manipulate the content.
        """
        ...
    
    def after_content(self) -> None:
        """
        Called after parsing content. Used to reset information about the
        current directive context on the build environment.
        """
        ...
    
    def run(self) -> list[Node]:
        """
        Main directive entry function, called by docutils upon encountering the
        directive.

        This directive is meant to be quite easily subclassable, so it delegates
        to several additional methods.  What it does:

        * find out if called as a domain-specific directive, set self.domain
        * create a `desc` node to fit all description inside
        * parse standard options, currently `no-index`
        * create an index node if needed as self.indexnode
        * parse all given signatures (as returned by self.get_signatures())
          using self.handle_signature(), which should either return a name
          or raise ValueError
        * add index entries using self.add_target_and_index()
        * parse the content and handle doc fields in it
        """
        ...
    


class DefaultRole(SphinxDirective):
    """
    Set the default interpreted text role.  Overridden from docutils.
    """
    optional_arguments = ...
    final_argument_whitespace = ...
    def run(self) -> list[Node]:
        ...
    


class DefaultDomain(SphinxDirective):
    """
    Directive to (re-)set the default domain for this source file.
    """
    has_content = ...
    required_arguments = ...
    optional_arguments = ...
    final_argument_whitespace = ...
    option_spec: OptionSpec = ...
    def run(self) -> list[Node]:
        ...
    


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

