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

from typing import TYPE_CHECKING
from docutils import nodes
from docutils.nodes import Element, Node
from sphinx import addnodes
from docutils.parsers.rst.states import Inliner
from sphinx.directives import ObjectDescription
from sphinx.environment import BuildEnvironment
from sphinx.util.typing import TextlikeNode

"""Utility code for "Doc fields".

"Doc fields" are reST field lists in object descriptions that will
be domain-specifically transformed to a more appealing presentation.
"""
if TYPE_CHECKING:
    ...
logger = ...
class Field:
    """A doc field that is never grouped.  It can have an argument or not, the
    argument can be linked using a specified *rolename*.  Field should be used
    for doc fields that usually don't occur more than once.

    The body can be linked using a specified *bodyrolename* if the content is
    just a single inline or text node.

    Example::

       :returns: description of the return value
       :rtype: description of the return type
    """
    is_grouped = ...
    is_typed = ...
    def __init__(self, name: str, names: tuple[str, ...] = ..., label: str = ..., has_arg: bool = ..., rolename: str = ..., bodyrolename: str = ...) -> None:
        ...
    
    def make_xref(self, rolename: str, domain: str, target: str, innernode: type[TextlikeNode] = ..., contnode: Node | None = ..., env: BuildEnvironment | None = ..., inliner: Inliner | None = ..., location: Element | 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: Element | None = ...) -> list[Node]:
        ...
    
    def make_entry(self, fieldarg: str, content: list[Node]) -> tuple[str, list[Node]]:
        ...
    
    def make_field(self, types: dict[str, list[Node]], domain: str, item: tuple, env: BuildEnvironment | None = ..., inliner: Inliner | None = ..., location: Element | None = ...) -> nodes.field:
        ...
    


class GroupedField(Field):
    """
    A doc field that is grouped; i.e., all fields of that type will be
    transformed into one field with its body being a bulleted list.  It always
    has an argument.  The argument can be linked using the given *rolename*.
    GroupedField should be used for doc fields that can occur more than once.
    If *can_collapse* is true, this field will revert to a Field if only used
    once.

    Example::

       :raises ErrorClass: description when it is raised
    """
    is_grouped = ...
    list_type = nodes.bullet_list
    def __init__(self, name: str, names: tuple[str, ...] = ..., label: str = ..., rolename: str = ..., can_collapse: bool = ...) -> None:
        ...
    
    def make_field(self, types: dict[str, list[Node]], domain: str, items: tuple, env: BuildEnvironment | None = ..., inliner: Inliner | None = ..., location: Element | None = ...) -> nodes.field:
        ...
    


class TypedField(GroupedField):
    """
    A doc field that is grouped and has type information for the arguments.  It
    always has an argument.  The argument can be linked using the given
    *rolename*, the type using the given *typerolename*.

    Two uses are possible: either parameter and type description are given
    separately, using a field from *names* and one from *typenames*,
    respectively, or both are given using a field from *names*, see the example.

    Example::

       :param foo: description of parameter foo
       :type foo:  SomeClass

       -- or --

       :param SomeClass foo: description of parameter foo
    """
    is_typed = ...
    def __init__(self, name: str, names: tuple[str, ...] = ..., typenames: tuple[str, ...] = ..., label: str = ..., rolename: str = ..., typerolename: str = ..., can_collapse: bool = ...) -> None:
        ...
    
    def make_field(self, types: dict[str, list[Node]], domain: str, items: tuple, env: BuildEnvironment | None = ..., inliner: Inliner | None = ..., location: Element | None = ...) -> nodes.field:
        ...
    


class DocFieldTransformer:
    """
    Transforms field lists in "doc field" syntax into better-looking
    equivalents, using the field type definitions given on a domain.
    """
    typemap: dict[str, tuple[Field, bool]]
    def __init__(self, directive: ObjectDescription) -> None:
        ...
    
    def transform_all(self, node: addnodes.desc_content) -> None:
        """Transform all field list children of a node."""
        ...
    
    def transform(self, node: nodes.field_list) -> None:
        """Transform a single field list *node*."""
        ...
    


