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

from collections.abc import Generator, Sequence
from contextlib import contextmanager
from typing import Any, TYPE_CHECKING
from docutils import nodes
from docutils.io import FileOutput
from docutils.parsers.rst import Directive
from docutils.parsers.rst.states import Inliner
from docutils.statemachine import State, StringList
from docutils.utils import Reporter
from types import ModuleType
from docutils.frontend import Values
from docutils.nodes import Element, Node, system_message
from sphinx.builders import Builder
from sphinx.config import Config
from sphinx.environment import BuildEnvironment
from sphinx.util.typing import RoleFunction

"""Utility functions for docutils."""
logger = ...
report_re = ...
if TYPE_CHECKING:
    ...
_DEPRECATED_OBJECTS = ...
def __getattr__(name): # -> VersionInfo:
    ...

additional_nodes: set[type[Element]] = ...
@contextmanager
def docutils_namespace() -> Generator[None, None, None]:
    """Create namespace for reST parsers."""
    ...

def is_directive_registered(name: str) -> bool:
    """Check the *name* directive is already registered."""
    ...

def register_directive(name: str, directive: type[Directive]) -> None:
    """Register a directive to docutils.

    This modifies global state of docutils.  So it is better to use this
    inside ``docutils_namespace()`` to prevent side-effects.
    """
    ...

def is_role_registered(name: str) -> bool:
    """Check the *name* role is already registered."""
    ...

def register_role(name: str, role: RoleFunction) -> None:
    """Register a role to docutils.

    This modifies global state of docutils.  So it is better to use this
    inside ``docutils_namespace()`` to prevent side-effects.
    """
    ...

def unregister_role(name: str) -> None:
    """Unregister a role from docutils."""
    ...

def is_node_registered(node: type[Element]) -> bool:
    """Check the *node* is already registered."""
    ...

def register_node(node: type[Element]) -> None:
    """Register a node to docutils.

    This modifies global state of some visitors.  So it is better to use this
    inside ``docutils_namespace()`` to prevent side-effects.
    """
    ...

def unregister_node(node: type[Element]) -> None:
    """Unregister a node from docutils.

    This is inverse of ``nodes._add_nodes_class_names()``.
    """
    ...

@contextmanager
def patched_get_language() -> Generator[None, None, None]:
    """Patch docutils.languages.get_language() temporarily.

    This ignores the second argument ``reporter`` to suppress warnings.
    refs: https://github.com/sphinx-doc/sphinx/issues/3788
    """
    ...

@contextmanager
def patched_rst_get_language() -> Generator[None, None, None]:
    """Patch docutils.parsers.rst.languages.get_language().
    Starting from docutils 0.17, get_language() in ``rst.languages``
    also has a reporter, which needs to be disabled temporarily.

    This should also work for old versions of docutils,
    because reporter is none by default.

    refs: https://github.com/sphinx-doc/sphinx/issues/10179
    """
    ...

@contextmanager
def using_user_docutils_conf(confdir: str | None) -> Generator[None, None, None]:
    """Let docutils know the location of ``docutils.conf`` for Sphinx."""
    ...

@contextmanager
def du19_footnotes() -> Generator[None, None, None]:
    ...

@contextmanager
def patch_docutils(confdir: str | None = ...) -> Generator[None, None, None]:
    """Patch to docutils temporarily."""
    ...

class CustomReSTDispatcher:
    """Custom reST's mark-up dispatcher.

    This replaces docutils's directives and roles dispatch mechanism for reST parser
    by original one temporarily.
    """
    def __init__(self) -> None:
        ...
    
    def __enter__(self) -> None:
        ...
    
    def __exit__(self, exc_type: type[Exception], exc_value: Exception, traceback: Any) -> None:
        ...
    
    def enable(self) -> None:
        ...
    
    def disable(self) -> None:
        ...
    
    def directive(self, directive_name: str, language_module: ModuleType, document: nodes.document) -> tuple[type[Directive] | None, list[system_message]]:
        ...
    
    def role(self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter) -> tuple[RoleFunction, list[system_message]]:
        ...
    


class ElementLookupError(Exception):
    ...


class sphinx_domains(CustomReSTDispatcher):
    """Monkey-patch directive and role dispatch, so that domain-specific
    markup takes precedence.
    """
    def __init__(self, env: BuildEnvironment) -> None:
        ...
    
    def lookup_domain_element(self, type: str, name: str) -> Any:
        """Lookup a markup element (directive or role), given its name which can
        be a full name (with domain).
        """
        ...
    
    def directive(self, directive_name: str, language_module: ModuleType, document: nodes.document) -> tuple[type[Directive] | None, list[system_message]]:
        ...
    
    def role(self, role_name: str, language_module: ModuleType, lineno: int, reporter: Reporter) -> tuple[RoleFunction, list[system_message]]:
        ...
    


class WarningStream:
    def write(self, text: str) -> None:
        ...
    


class LoggingReporter(Reporter):
    @classmethod
    def from_reporter(cls, reporter: Reporter) -> LoggingReporter:
        """Create an instance of LoggingReporter from other reporter object."""
        ...
    
    def __init__(self, source: str, report_level: int = ..., halt_level: int = ..., debug: bool = ..., error_handler: str = ...) -> None:
        ...
    


class NullReporter(Reporter):
    """A dummy reporter; write nothing."""
    def __init__(self) -> None:
        ...
    


@contextmanager
def switch_source_input(state: State, content: StringList) -> Generator[None, None, None]:
    """Switch current source input of state temporarily."""
    ...

class SphinxFileOutput(FileOutput):
    """Better FileOutput class for Sphinx."""
    def __init__(self, **kwargs: Any) -> None:
        ...
    
    def write(self, data: str) -> str:
        ...
    


class SphinxDirective(Directive):
    """A base class for Sphinx directives.

    This class provides helper methods for Sphinx directives.

    .. note:: The subclasses of this class might not work with docutils.
              This class is strongly coupled with Sphinx.
    """
    @property
    def env(self) -> BuildEnvironment:
        """Reference to the :class:`.BuildEnvironment` object."""
        ...
    
    @property
    def config(self) -> Config:
        """Reference to the :class:`.Config` object."""
        ...
    
    def get_source_info(self) -> tuple[str, int]:
        """Get source and line number."""
        ...
    
    def set_source_info(self, node: Node) -> None:
        """Set source and line number to the node."""
        ...
    
    def get_location(self) -> str:
        """Get current location info for logging."""
        ...
    


class SphinxRole:
    """A base class for Sphinx roles.

    This class provides helper methods for Sphinx roles.

    .. note:: The subclasses of this class might not work with docutils.
              This class is strongly coupled with Sphinx.
    """
    name: str
    rawtext: str
    text: str
    lineno: int
    inliner: Inliner
    options: dict[str, Any]
    content: Sequence[str]
    def __call__(self, name: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: dict | None = ..., content: Sequence[str] = ...) -> tuple[list[Node], list[system_message]]:
        ...
    
    def run(self) -> tuple[list[Node], list[system_message]]:
        ...
    
    @property
    def env(self) -> BuildEnvironment:
        """Reference to the :class:`.BuildEnvironment` object."""
        ...
    
    @property
    def config(self) -> Config:
        """Reference to the :class:`.Config` object."""
        ...
    
    def get_source_info(self, lineno: int | None = ...) -> tuple[str, int]:
        ...
    
    def set_source_info(self, node: Node, lineno: int | None = ...) -> None:
        ...
    
    def get_location(self) -> str:
        """Get current location info for logging."""
        ...
    


class ReferenceRole(SphinxRole):
    """A base class for reference roles.

    The reference roles can accept ``link title <target>`` style as a text for
    the role.  The parsed result; link title and target will be stored to
    ``self.title`` and ``self.target``.
    """
    has_explicit_title: bool
    disabled: bool
    title: str
    target: str
    explicit_title_re = ...
    def __call__(self, name: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: dict | None = ..., content: Sequence[str] = ...) -> tuple[list[Node], list[system_message]]:
        ...
    


class SphinxTranslator(nodes.NodeVisitor):
    """A base class for Sphinx translators.

    This class adds a support for visitor/departure method for super node class
    if visitor/departure method for node class is not found.

    It also provides helper methods for Sphinx translators.

    .. note:: The subclasses of this class might not work with docutils.
              This class is strongly coupled with Sphinx.
    """
    def __init__(self, document: nodes.document, builder: Builder) -> None:
        ...
    
    def dispatch_visit(self, node: Node) -> None:
        """
        Dispatch node to appropriate visitor method.
        The priority of visitor method is:

        1. ``self.visit_{node_class}()``
        2. ``self.visit_{super_node_class}()``
        3. ``self.unknown_visit()``
        """
        ...
    
    def dispatch_departure(self, node: Node) -> None:
        """
        Dispatch node to appropriate departure method.
        The priority of departure method is:

        1. ``self.depart_{node_class}()``
        2. ``self.depart_{super_node_class}()``
        3. ``self.unknown_departure()``
        """
        ...
    
    def unknown_visit(self, node: Node) -> None:
        ...
    


__document_cache__: tuple[Values, Reporter]
def new_document(source_path: str, settings: Any = ...) -> nodes.document:
    """Return a new empty document object.  This is an alternative of docutils'.

    This is a simple wrapper for ``docutils.utils.new_document()``.  It
    caches the result of docutils' and use it on second call for instantiation.
    This makes an instantiation of document nodes much faster.
    """
    ...

