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

import docutils.parsers.rst.states
from typing import Any, TYPE_CHECKING
from docutils import nodes
from sphinx.util.docutils import ReferenceRole, SphinxRole
from collections.abc import Sequence
from docutils.nodes import Element, Node, TextElement, system_message
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx.util.typing import RoleFunction

"""Handlers for additional ReST roles."""
if TYPE_CHECKING:
    ...
generic_docroles = ...
class XRefRole(ReferenceRole):
    """
    A generic cross-referencing role.  To create a callable that can be used as
    a role function, create an instance of this class.

    The general features of this role are:

    * Automatic creation of a reference and a content node.
    * Optional separation of title and target with `title <target>`.
    * The implementation is a class rather than a function to make
      customization easier.

    Customization can be done in two ways:

    * Supplying constructor parameters:
      * `fix_parens` to normalize parentheses (strip from target, and add to
        title if configured)
      * `lowercase` to lowercase the target
      * `nodeclass` and `innernodeclass` select the node classes for
        the reference and the content node

    * Subclassing and overwriting `process_link()` and/or `result_nodes()`.
    """
    nodeclass: type[Element] = ...
    innernodeclass: type[TextElement] = ...
    def __init__(self, fix_parens: bool = ..., lowercase: bool = ..., nodeclass: type[Element] | None = ..., innernodeclass: type[TextElement] | None = ..., warn_dangling: bool = ...) -> None:
        ...
    
    def update_title_and_target(self, title: str, target: str) -> tuple[str, str]:
        ...
    
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    
    def create_non_xref_node(self) -> tuple[list[Node], list[system_message]]:
        ...
    
    def create_xref_node(self) -> tuple[list[Node], list[system_message]]:
        ...
    
    def process_link(self, env: BuildEnvironment, refnode: Element, has_explicit_title: bool, title: str, target: str) -> tuple[str, str]:
        """Called after parsing title and target text, and creating the
        reference node (given in *refnode*).  This method can alter the
        reference node and must return a new (or the same) ``(title, target)``
        tuple.
        """
        ...
    
    def result_nodes(self, document: nodes.document, env: BuildEnvironment, node: Element, is_ref: bool) -> tuple[list[Node], list[system_message]]:
        """Called before returning the finished nodes.  *node* is the reference
        node if one was created (*is_ref* is then true), else the content node.
        This method can add other nodes and must return a ``(nodes, messages)``
        tuple (the usual return value of a role function).
        """
        ...
    


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


class PEP(ReferenceRole):
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    
    def build_uri(self) -> str:
        ...
    


class RFC(ReferenceRole):
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    
    def build_uri(self) -> str:
        ...
    


_amp_re = ...
class GUILabel(SphinxRole):
    amp_re = ...
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    


class MenuSelection(GUILabel):
    BULLET_CHARACTER = ...
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    


_litvar_re = ...
parens_re = ...
class EmphasizedLiteral(SphinxRole):
    parens_re = ...
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    
    def parse(self, text: str) -> list[Node]:
        ...
    


_abbr_re = ...
class Abbreviation(SphinxRole):
    abbr_re = ...
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    


def code_role(name: str, rawtext: str, text: str, lineno: int, inliner: docutils.parsers.rst.states.Inliner, options: dict | None = ..., content: Sequence[str] = ...) -> tuple[list[Node], list[system_message]]:
    ...

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

