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

import functools
import os
import pickle
import time
from __future__ import annotations
from collections import defaultdict
from copy import copy
from os import path
from typing import Any, Callable, Literal, TYPE_CHECKING
from sphinx import addnodes
from sphinx.environment.adapters import toctree as toctree_adapters
from sphinx.errors import BuildEnvironmentError, DocumentError, ExtensionError, SphinxError
from sphinx.locale import __
from sphinx.transforms import SphinxTransformer
from sphinx.util import DownloadFiles, FilenameUniqDict, logging
from sphinx.util.docutils import LoggingReporter
from sphinx.util.i18n import CatalogRepository, docname_to_domain
from sphinx.util.nodes import is_translatable
from sphinx.util.osutil import canon_path, os_path
from collections.abc import Generator, Iterator, MutableMapping
from pathlib import Path
from docutils import nodes
from docutils.nodes import Node
from sphinx.application import Sphinx
from sphinx.builders import Builder
from sphinx.config import Config
from sphinx.domains import Domain
from sphinx.events import EventManager
from sphinx.project import Project
from typing_extensions import overload
from sphinx.domains.c import CDomain
from sphinx.domains.changeset import ChangeSetDomain
from sphinx.domains.citation import CitationDomain
from sphinx.domains.cpp import CPPDomain
from sphinx.domains.index import IndexDomain
from sphinx.domains.javascript import JavaScriptDomain
from sphinx.domains.math import MathDomain
from sphinx.domains.python import PythonDomain
from sphinx.domains.rst import ReSTDomain
from sphinx.domains.std import StandardDomain
from sphinx.ext.duration import DurationDomain
from sphinx.ext.todo import TodoDomain

"""Global creation environment."""
if TYPE_CHECKING:
    ...
logger = ...
default_settings: dict[str, Any] = ...
ENV_VERSION = ...
CONFIG_UNSET = ...
CONFIG_OK = ...
CONFIG_NEW = ...
CONFIG_CHANGED = ...
CONFIG_EXTENSIONS_CHANGED = ...
CONFIG_CHANGED_REASON = ...
versioning_conditions: dict[str, bool | Callable] = ...
if TYPE_CHECKING:
    class _DomainsType(MutableMapping[str, Domain]):
        @overload
        def __getitem__(self, key: Literal["c"]) -> CDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["cpp"]) -> CPPDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["changeset"]) -> ChangeSetDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["citation"]) -> CitationDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["index"]) -> IndexDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["js"]) -> JavaScriptDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["math"]) -> MathDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["py"]) -> PythonDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["rst"]) -> ReSTDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["std"]) -> StandardDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["duration"]) -> DurationDomain:
            ...
        
        @overload
        def __getitem__(self, key: Literal["todo"]) -> TodoDomain:
            ...
        
        @overload
        def __getitem__(self, key: str) -> Domain:
            ...
        
        def __getitem__(self, key):
            ...
        
        def __setitem__(self, key, value):
            ...
        
        def __delitem__(self, key):
            ...
        
        def __iter__(self):
            ...
        
        def __len__(self):
            ...
        
    
    
else:
    ...
class BuildEnvironment:
    """
    The environment in which the ReST files are translated.
    Stores an inventory of cross-file targets and provides doctree
    transformations to resolve links to them.
    """
    domains: _DomainsType
    def __init__(self, app: Sphinx) -> None:
        ...
    
    def __getstate__(self) -> dict:
        """Obtains serializable data for pickling."""
        ...
    
    def __setstate__(self, state: dict) -> None:
        ...
    
    def setup(self, app: Sphinx) -> None:
        """Set up BuildEnvironment object."""
        ...
    
    def set_versioning_method(self, method: str | Callable, compare: bool) -> None:
        """This sets the doctree versioning method for this environment.

        Versioning methods are a builder property; only builders with the same
        versioning method can share the same doctree directory.  Therefore, we
        raise an exception if the user tries to use an environment with an
        incompatible versioning method.
        """
        ...
    
    def clear_doc(self, docname: str) -> None:
        """Remove all traces of a source file in the inventory."""
        ...
    
    def merge_info_from(self, docnames: list[str], other: BuildEnvironment, app: Sphinx) -> None:
        """Merge global information gathered about *docnames* while reading them
        from the *other* environment.

        This possibly comes from a parallel build process.
        """
        ...
    
    def path2doc(self, filename: str | os.PathLike[str]) -> str | None:
        """Return the docname for the filename if the file is document.

        *filename* should be absolute or relative to the source directory.
        """
        ...
    
    def doc2path(self, docname: str, base: bool = ...) -> str:
        """Return the filename for the document name.

        If *base* is True, return absolute path under self.srcdir.
        If *base* is False, return relative path to self.srcdir.
        """
        ...
    
    def relfn2path(self, filename: str, docname: str | None = ...) -> tuple[str, str]:
        """Return paths to a file referenced from a document, relative to
        documentation root and absolute.

        In the input "filename", absolute filenames are taken as relative to the
        source dir, while relative filenames are relative to the dir of the
        containing document.
        """
        ...
    
    @property
    def found_docs(self) -> set[str]:
        """contains all existing docnames."""
        ...
    
    def find_files(self, config: Config, builder: Builder) -> None:
        """Find all source files in the source dir and put them in
        self.found_docs.
        """
        ...
    
    def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str], set[str]]:
        """Return (added, changed, removed) sets."""
        ...
    
    def check_dependents(self, app: Sphinx, already: set[str]) -> Generator[str, None, None]:
        ...
    
    def prepare_settings(self, docname: str) -> None:
        """Prepare to set up environment for reading."""
        ...
    
    @property
    def docname(self) -> str:
        """Returns the docname of the document currently being parsed."""
        ...
    
    def new_serialno(self, category: str = ...) -> int:
        """Return a serial number, e.g. for index entry targets.

        The number is guaranteed to be unique in the current document.
        """
        ...
    
    def note_dependency(self, filename: str) -> None:
        """Add *filename* as a dependency of the current document.

        This means that the document will be rebuilt if this file changes.

        *filename* should be absolute or relative to the source directory.
        """
        ...
    
    def note_included(self, filename: str) -> None:
        """Add *filename* as a included from other document.

        This means the document is not orphaned.

        *filename* should be absolute or relative to the source directory.
        """
        ...
    
    def note_reread(self) -> None:
        """Add the current document to the list of documents that will
        automatically be re-read at the next build.
        """
        ...
    
    def get_domain(self, domainname: str) -> Domain:
        """Return the domain instance with the specified name.

        Raises an ExtensionError if the domain is not registered.
        """
        ...
    
    def get_doctree(self, docname: str) -> nodes.document:
        """Read the doctree for a file from the pickle and return it."""
        ...
    
    @functools.cached_property
    def master_doctree(self) -> nodes.document:
        ...
    
    def get_and_resolve_doctree(self, docname: str, builder: Builder, doctree: nodes.document | None = ..., prune_toctrees: bool = ..., includehidden: bool = ...) -> nodes.document:
        """Read the doctree from the pickle, resolve cross-references and
        toctrees and return it.
        """
        ...
    
    def resolve_toctree(self, docname: str, builder: Builder, toctree: addnodes.toctree, prune: bool = ..., maxdepth: int = ..., titles_only: bool = ..., collapse: bool = ..., includehidden: bool = ...) -> Node | None:
        """Resolve a *toctree* node into individual bullet lists with titles
        as items, returning None (if no containing titles are found) or
        a new node.

        If *prune* is True, the tree is pruned to *maxdepth*, or if that is 0,
        to the value of the *maxdepth* option on the *toctree* node.
        If *titles_only* is True, only toplevel document titles will be in the
        resulting tree.
        If *collapse* is True, all branches not containing docname will
        be collapsed.
        """
        ...
    
    def resolve_references(self, doctree: nodes.document, fromdocname: str, builder: Builder) -> None:
        ...
    
    def apply_post_transforms(self, doctree: nodes.document, docname: str) -> None:
        """Apply all post-transforms."""
        ...
    
    def collect_relations(self) -> dict[str, list[str | None]]:
        ...
    
    def check_consistency(self) -> None:
        """Do consistency checks."""
        ...
    


