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

import re
import sys
import warnings
import sphinx
from __future__ import annotations
from inspect import Parameter, Signature
from typing import Any, Callable, TYPE_CHECKING, TypeVar
from docutils.statemachine import StringList
from sphinx.config import Config, ENUM
from sphinx.deprecation import RemovedInSphinx80Warning
from sphinx.ext.autodoc.importer import get_class_members, import_module, import_object
from sphinx.ext.autodoc.mock import ismock, mock, undecorate
from sphinx.locale import _, __
from sphinx.pycode import ModuleAnalyzer, PycodeError
from sphinx.util import inspect, logging
from sphinx.util.docstrings import prepare_docstring, separate_metadata
from sphinx.util.inspect import evaluate_signature, getdoc, object_description, safe_getattr, stringify_signature
from sphinx.util.typing import OptionSpec, get_type_hints, restify, stringify_annotation
from collections.abc import Iterator, Sequence
from types import ModuleType
from sphinx.application import Sphinx
from sphinx.environment import BuildEnvironment
from sphinx.ext.autodoc.directive import DocumenterBridge

"""Extension to create automatic documentation from code docstrings.

Automatically insert docstrings for functions, classes or whole modules into
the doctree, thus avoiding duplication between docstrings and documentation
for those who like elaborate docstrings.
"""
if TYPE_CHECKING:
    ...
logger = ...
MethodDescriptorType = ...
py_ext_sig_re = ...
special_member_re = ...
def identity(x: Any) -> Any:
    ...

class _All:
    """A special value for :*-members: that matches to any member."""
    def __contains__(self, item: Any) -> bool:
        ...
    
    def append(self, item: Any) -> None:
        ...
    


class _Empty:
    """A special value for :exclude-members: that never matches to any member."""
    def __contains__(self, item: Any) -> bool:
        ...
    


ALL = ...
EMPTY = ...
UNINITIALIZED_ATTR = ...
INSTANCEATTR = ...
SLOTSATTR = ...
def members_option(arg: Any) -> object | list[str]:
    """Used to convert the :members: option to auto directives."""
    ...

def exclude_members_option(arg: Any) -> object | set[str]:
    """Used to convert the :exclude-members: option."""
    ...

def inherited_members_option(arg: Any) -> set[str]:
    """Used to convert the :inherited-members: option to auto directives."""
    ...

def member_order_option(arg: Any) -> str | None:
    """Used to convert the :member-order: option to auto directives."""
    ...

def class_doc_from_option(arg: Any) -> str | None:
    """Used to convert the :class-doc-from: option to autoclass directives."""
    ...

SUPPRESS = ...
def annotation_option(arg: Any) -> Any:
    ...

def bool_option(arg: Any) -> bool:
    """Used to convert flag options to auto directives.  (Instead of
    directives.flag(), which returns None).
    """
    ...

def merge_members_option(options: dict) -> None:
    """Merge :private-members: and :special-members: options to the
    :members: option.
    """
    ...

def cut_lines(pre: int, post: int = ..., what: str | None = ...) -> Callable:
    """Return a listener that removes the first *pre* and last *post*
    lines of every docstring.  If *what* is a sequence of strings,
    only docstrings of a type in *what* will be processed.

    Use like this (e.g. in the ``setup()`` function of :file:`conf.py`)::

       from sphinx.ext.autodoc import cut_lines
       app.connect('autodoc-process-docstring', cut_lines(4, what=['module']))

    This can (and should) be used in place of :confval:`automodule_skip_lines`.
    """
    ...

def between(marker: str, what: Sequence[str] | None = ..., keepempty: bool = ..., exclude: bool = ...) -> Callable:
    """Return a listener that either keeps, or if *exclude* is True excludes,
    lines between lines that match the *marker* regular expression.  If no line
    matches, the resulting docstring would be empty, so no change will be made
    unless *keepempty* is true.

    If *what* is a sequence of strings, only docstrings of a type in *what* will
    be processed.
    """
    ...

class Options(dict):
    """A dict/attribute hybrid that returns None on nonexisting keys."""
    def copy(self) -> Options:
        ...
    
    def __getattr__(self, name: str) -> Any:
        ...
    


class ObjectMember:
    """A member of object.

    This is used for the result of `Documenter.get_module_members()` to
    represent each member of the object.

    .. Note::

       An instance of this class behaves as a tuple of (name, object)
       for compatibility to old Sphinx.  The behavior will be dropped
       in the future.  Therefore extensions should not use the tuple
       interface.
    """
    def __init__(self, name: str, obj: Any, *, docstring: str | None = ..., class_: Any = ..., skipped: bool = ...) -> None:
        ...
    
    def __getitem__(self, index): # -> Any:
        ...
    


class Documenter:
    """
    A Documenter knows how to autodocument a single object type.  When
    registered with the AutoDirective, it will be used to document objects
    of that type when needed by autodoc.

    Its *objtype* attribute selects what auto directive it is assigned to
    (the directive name is 'auto' + objtype), and what directive it generates
    by default, though that can be overridden by an attribute called
    *directivetype*.

    A Documenter has an *option_spec* that works like a docutils directive's;
    in fact, it will be used to parse an auto directive's options that matches
    the Documenter.
    """
    objtype = ...
    content_indent = ...
    priority = ...
    member_order = ...
    titles_allowed = ...
    option_spec: OptionSpec = ...
    def get_attr(self, obj: Any, name: str, *defargs: Any) -> Any:
        """getattr() override for types such as Zope interfaces."""
        ...
    
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        """Called to see if a member can be documented by this Documenter."""
        ...
    
    def __init__(self, directive: DocumenterBridge, name: str, indent: str = ...) -> None:
        ...
    
    @property
    def documenters(self) -> dict[str, type[Documenter]]:
        """Returns registered Documenter classes"""
        ...
    
    def add_line(self, line: str, source: str, *lineno: int) -> None:
        """Append one line of generated reST to the output."""
        ...
    
    def resolve_name(self, modname: str | None, parents: Any, path: str, base: str) -> tuple[str | None, list[str]]:
        """Resolve the module and name of the object to document given by the
        arguments and the current module/class.

        Must return a pair of the module name and a chain of attributes; for
        example, it would return ``('zipfile', ['ZipFile', 'open'])`` for the
        ``zipfile.ZipFile.open`` method.
        """
        ...
    
    def parse_name(self) -> bool:
        """Determine what module to import and what attribute to document.

        Returns True and sets *self.modname*, *self.objpath*, *self.fullname*,
        *self.args* and *self.retann* if parsing and resolving was successful.
        """
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        """Import the object given by *self.modname* and *self.objpath* and set
        it as *self.object*.

        Returns True if successful, False if an error occurred.
        """
        ...
    
    def get_real_modname(self) -> str:
        """Get the real module name of an object to document.

        It can differ from the name of the module through which the object was
        imported.
        """
        ...
    
    def check_module(self) -> bool:
        """Check if *self.object* is really defined in the module given by
        *self.modname*.
        """
        ...
    
    def format_args(self, **kwargs: Any) -> str:
        """Format the argument signature of *self.object*.

        Should return None if the object does not have a signature.
        """
        ...
    
    def format_name(self) -> str:
        """Format the name of *self.object*.

        This normally should be something that can be parsed by the generated
        directive, but doesn't need to be (Sphinx will display it unparsed
        then).
        """
        ...
    
    def format_signature(self, **kwargs: Any) -> str:
        """Format the signature (arguments and return annotation) of the object.

        Let the user process it via the ``autodoc-process-signature`` event.
        """
        ...
    
    def add_directive_header(self, sig: str) -> None:
        """Add the directive header and options to the generated content."""
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        """Decode and return lines of the docstring(s) for the object.

        When it returns None, autodoc-process-docstring will not be called for this
        object.
        """
        ...
    
    def process_doc(self, docstrings: list[list[str]]) -> Iterator[str]:
        """Let the user process the docstrings before adding them."""
        ...
    
    def get_sourcename(self) -> str:
        ...
    
    def add_content(self, more_content: StringList | None) -> None:
        """Add content from docstrings, attribute documentation and user."""
        ...
    
    def get_object_members(self, want_all: bool) -> tuple[bool, list[ObjectMember]]:
        """Return `(members_check_module, members)` where `members` is a
        list of `(membername, member)` pairs of the members of *self.object*.

        If *want_all* is True, return all members.  Else, only return those
        members given by *self.options.members* (which may also be None).
        """
        ...
    
    def filter_members(self, members: list[ObjectMember], want_all: bool) -> list[tuple[str, Any, bool]]:
        """Filter the given member list.

        Members are skipped if

        - they are private (except if given explicitly or the private-members
          option is set)
        - they are special methods (except if given explicitly or the
          special-members option is set)
        - they are undocumented (except if the undoc-members option is set)

        The user can override the skipping decision by connecting to the
        ``autodoc-skip-member`` event.
        """
        ...
    
    def document_members(self, all_members: bool = ...) -> None:
        """Generate reST for member documentation.

        If *all_members* is True, document all members, else those given by
        *self.options.members*.
        """
        ...
    
    def sort_members(self, documenters: list[tuple[Documenter, bool]], order: str) -> list[tuple[Documenter, bool]]:
        """Sort the given member list."""
        ...
    
    def generate(self, more_content: StringList | None = ..., real_modname: str | None = ..., check_module: bool = ..., all_members: bool = ...) -> None:
        """Generate reST for the object given by *self.name*, and possibly for
        its members.

        If *more_content* is given, include that content. If *real_modname* is
        given, use that module name to find attribute docs. If *check_module* is
        True, only generate if the object is defined in the module name it is
        imported from. If *all_members* is True, document all members.
        """
        ...
    


class ModuleDocumenter(Documenter):
    """
    Specialized Documenter subclass for modules.
    """
    objtype = ...
    content_indent = ...
    _extra_indent = ...
    option_spec: OptionSpec = ...
    def __init__(self, *args: Any) -> None:
        ...
    
    def add_content(self, more_content: StringList | None) -> None:
        ...
    
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    
    def resolve_name(self, modname: str | None, parents: Any, path: str, base: str) -> tuple[str | None, list[str]]:
        ...
    
    def parse_name(self) -> bool:
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def add_directive_header(self, sig: str) -> None:
        ...
    
    def get_module_members(self) -> dict[str, ObjectMember]:
        """Get members of target module."""
        ...
    
    def get_object_members(self, want_all: bool) -> tuple[bool, list[ObjectMember]]:
        ...
    
    def sort_members(self, documenters: list[tuple[Documenter, bool]], order: str) -> list[tuple[Documenter, bool]]:
        ...
    


class ModuleLevelDocumenter(Documenter):
    """
    Specialized Documenter subclass for objects on module level (functions,
    classes, data/constants).
    """
    def resolve_name(self, modname: str | None, parents: Any, path: str, base: str) -> tuple[str | None, list[str]]:
        ...
    


class ClassLevelDocumenter(Documenter):
    """
    Specialized Documenter subclass for objects on class level (methods,
    attributes).
    """
    def resolve_name(self, modname: str | None, parents: Any, path: str, base: str) -> tuple[str | None, list[str]]:
        ...
    


class DocstringSignatureMixin:
    """
    Mixin for FunctionDocumenter and MethodDocumenter to provide the
    feature of reading the signature from the docstring.
    """
    _new_docstrings: list[list[str]] | None = ...
    _signatures: list[str] = ...
    def get_doc(self) -> list[list[str]] | None:
        ...
    
    def format_signature(self, **kwargs: Any) -> str:
        ...
    


class DocstringStripSignatureMixin(DocstringSignatureMixin):
    """
    Mixin for AttributeDocumenter to provide the
    feature of stripping any function signature from the docstring.
    """
    def format_signature(self, **kwargs: Any) -> str:
        ...
    


class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
    """
    Specialized Documenter subclass for functions.
    """
    objtype = ...
    member_order = ...
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    
    def format_args(self, **kwargs: Any) -> str:
        ...
    
    def document_members(self, all_members: bool = ...) -> None:
        ...
    
    def add_directive_header(self, sig: str) -> None:
        ...
    
    def format_signature(self, **kwargs: Any) -> str:
        ...
    
    def merge_default_value(self, actual: Signature, overload: Signature) -> Signature:
        """Merge default values of actual implementation to the overload variants."""
        ...
    
    def annotate_to_first_argument(self, func: Callable, typ: type) -> Callable | None:
        """Annotate type hint to the first argument of function if needed."""
        ...
    


class DecoratorDocumenter(FunctionDocumenter):
    """
    Specialized Documenter subclass for decorator functions.
    """
    objtype = ...
    priority = ...
    def format_args(self, **kwargs: Any) -> str:
        ...
    


_METACLASS_CALL_BLACKLIST = ...
_CLASS_NEW_BLACKLIST = ...
class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
    """
    Specialized Documenter subclass for classes.
    """
    objtype = ...
    member_order = ...
    option_spec: OptionSpec = ...
    priority = ...
    _signature_class: Any = ...
    _signature_method_name: str = ...
    def __init__(self, *args: Any) -> None:
        ...
    
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def format_args(self, **kwargs: Any) -> str:
        ...
    
    def format_signature(self, **kwargs: Any) -> str:
        ...
    
    def get_overloaded_signatures(self) -> list[Signature]:
        ...
    
    def get_canonical_fullname(self) -> str | None:
        ...
    
    def add_directive_header(self, sig: str) -> None:
        ...
    
    def get_object_members(self, want_all: bool) -> tuple[bool, list[ObjectMember]]:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    
    def get_variable_comment(self) -> list[str] | None:
        ...
    
    def add_content(self, more_content: StringList | None) -> None:
        ...
    
    def document_members(self, all_members: bool = ...) -> None:
        ...
    
    def generate(self, more_content: StringList | None = ..., real_modname: str | None = ..., check_module: bool = ..., all_members: bool = ...) -> None:
        ...
    


class ExceptionDocumenter(ClassDocumenter):
    """
    Specialized ClassDocumenter subclass for exceptions.
    """
    objtype = ...
    member_order = ...
    priority = ...
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    


class DataDocumenterMixinBase:
    config: Config
    env: BuildEnvironment
    modname: str
    parent: Any
    object: Any
    objpath: list[str]
    def should_suppress_directive_header(self) -> bool:
        """Check directive header should be suppressed."""
        ...
    
    def should_suppress_value_header(self) -> bool:
        """Check :value: header should be suppressed."""
        ...
    
    def update_content(self, more_content: StringList) -> None:
        """Update docstring, for example with TypeVar variance."""
        ...
    


class GenericAliasMixin(DataDocumenterMixinBase):
    """
    Mixin for DataDocumenter and AttributeDocumenter to provide the feature for
    supporting GenericAliases.
    """
    def should_suppress_directive_header(self) -> bool:
        ...
    
    def update_content(self, more_content: StringList) -> None:
        ...
    


class UninitializedGlobalVariableMixin(DataDocumenterMixinBase):
    """
    Mixin for DataDocumenter to provide the feature for supporting uninitialized
    (type annotation only) global variables.
    """
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def should_suppress_value_header(self) -> bool:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    


class DataDocumenter(GenericAliasMixin, UninitializedGlobalVariableMixin, ModuleLevelDocumenter):
    """
    Specialized Documenter subclass for data items.
    """
    objtype = ...
    member_order = ...
    priority = ...
    option_spec: OptionSpec = ...
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    
    def update_annotations(self, parent: Any) -> None:
        """Update __annotations__ to support type_comment and so on."""
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def should_suppress_value_header(self) -> bool:
        ...
    
    def add_directive_header(self, sig: str) -> None:
        ...
    
    def document_members(self, all_members: bool = ...) -> None:
        ...
    
    def get_real_modname(self) -> str:
        ...
    
    def get_module_comment(self, attrname: str) -> list[str] | None:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    
    def add_content(self, more_content: StringList | None) -> None:
        ...
    


class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
    """
    Specialized Documenter subclass for methods (normal, static and class).
    """
    objtype = ...
    directivetype = ...
    member_order = ...
    priority = ...
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def format_args(self, **kwargs: Any) -> str:
        ...
    
    def add_directive_header(self, sig: str) -> None:
        ...
    
    def document_members(self, all_members: bool = ...) -> None:
        ...
    
    def format_signature(self, **kwargs: Any) -> str:
        ...
    
    def merge_default_value(self, actual: Signature, overload: Signature) -> Signature:
        """Merge default values of actual implementation to the overload variants."""
        ...
    
    def annotate_to_first_argument(self, func: Callable, typ: type) -> Callable | None:
        """Annotate type hint to the first argument of function if needed."""
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    


class NonDataDescriptorMixin(DataDocumenterMixinBase):
    """
    Mixin for AttributeDocumenter to provide the feature for supporting non
    data-descriptors.

    .. note:: This mix-in must be inherited after other mix-ins.  Otherwise, docstring
              and :value: header will be suppressed unexpectedly.
    """
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def should_suppress_value_header(self) -> bool:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    


class SlotsMixin(DataDocumenterMixinBase):
    """
    Mixin for AttributeDocumenter to provide the feature for supporting __slots__.
    """
    def isslotsattribute(self) -> bool:
        """Check the subject is an attribute in __slots__."""
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def should_suppress_value_header(self) -> bool:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    


class RuntimeInstanceAttributeMixin(DataDocumenterMixinBase):
    """
    Mixin for AttributeDocumenter to provide the feature for supporting runtime
    instance attributes (that are defined in __init__() methods with doc-comments).

    Example:

        class Foo:
            def __init__(self):
                self.attr = None  #: This is a target of this mix-in.
    """
    RUNTIME_INSTANCE_ATTRIBUTE = ...
    def is_runtime_instance_attribute(self, parent: Any) -> bool:
        """Check the subject is an attribute defined in __init__()."""
        ...
    
    def is_runtime_instance_attribute_not_commented(self, parent: Any) -> bool:
        """Check the subject is an attribute defined in __init__() without comment."""
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        """Check the existence of runtime instance attribute after failing to import the
        attribute."""
        ...
    
    def should_suppress_value_header(self) -> bool:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    


class UninitializedInstanceAttributeMixin(DataDocumenterMixinBase):
    """
    Mixin for AttributeDocumenter to provide the feature for supporting uninitialized
    instance attributes (PEP-526 styled, annotation only attributes).

    Example:

        class Foo:
            attr: int  #: This is a target of this mix-in.
    """
    def is_uninitialized_instance_attribute(self, parent: Any) -> bool:
        """Check the subject is an annotation only attribute."""
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        """Check the exisitence of uninitialized instance attribute when failed to import
        the attribute."""
        ...
    
    def should_suppress_value_header(self) -> bool:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    


class AttributeDocumenter(GenericAliasMixin, SlotsMixin, RuntimeInstanceAttributeMixin, UninitializedInstanceAttributeMixin, NonDataDescriptorMixin, DocstringStripSignatureMixin, ClassLevelDocumenter):
    """
    Specialized Documenter subclass for attributes.
    """
    objtype = ...
    member_order = ...
    option_spec: OptionSpec = ...
    priority = ...
    @staticmethod
    def is_function_or_method(obj: Any) -> bool:
        ...
    
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    
    def document_members(self, all_members: bool = ...) -> None:
        ...
    
    def update_annotations(self, parent: Any) -> None:
        """Update __annotations__ to support type_comment and so on."""
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        ...
    
    def get_real_modname(self) -> str:
        ...
    
    def should_suppress_value_header(self) -> bool:
        ...
    
    def add_directive_header(self, sig: str) -> None:
        ...
    
    def get_attribute_comment(self, parent: Any, attrname: str) -> list[str] | None:
        ...
    
    def get_doc(self) -> list[list[str]] | None:
        ...
    
    def add_content(self, more_content: StringList | None) -> None:
        ...
    


class PropertyDocumenter(DocstringStripSignatureMixin, ClassLevelDocumenter):
    """
    Specialized Documenter subclass for properties.
    """
    objtype = ...
    member_order = ...
    priority = ...
    @classmethod
    def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any) -> bool:
        ...
    
    def import_object(self, raiseerror: bool = ...) -> bool:
        """Check the exisitence of uninitialized instance attribute when failed to import
        the attribute."""
        ...
    
    def format_args(self, **kwargs: Any) -> str:
        ...
    
    def document_members(self, all_members: bool = ...) -> None:
        ...
    
    def get_real_modname(self) -> str:
        ...
    
    def add_directive_header(self, sig: str) -> None:
        ...
    


def autodoc_attrgetter(app: Sphinx, obj: Any, name: str, *defargs: Any) -> Any:
    """Alternative getattr() for types"""
    ...

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

