Sphinx 8.0.2__py3-none-any.whl → 8.1.1__py3-none-any.whl

sphinx/environment/__init__.py

@@ -8,14 +8,22 @@ import pickle
 from collections import defaultdict
 from copy import copy
 from os import path
-from typing import TYPE_CHECKING, Any, NoReturn
+from typing import TYPE_CHECKING
 
 from sphinx import addnodes
+from sphinx.domains._domains_container import _DomainsContainer
 from sphinx.environment.adapters import toctree as toctree_adapters
-from sphinx.errors import BuildEnvironmentError, DocumentError, ExtensionError, SphinxError
+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 import logging
+from sphinx.util._files import DownloadFiles, FilenameUniqDict
+from sphinx.util._serialise import stable_str
 from sphinx.util._timestamps import _format_rfc3339_microseconds
 from sphinx.util.docutils import LoggingReporter
 from sphinx.util.i18n import CatalogRepository, docname_to_domain
@@ -23,8 +31,9 @@ from sphinx.util.nodes import is_translatable
 from sphinx.util.osutil import _last_modified_time, canon_path, os_path
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterator
+    from collections.abc import Callable, Iterable, Iterator
     from pathlib import Path
+    from typing import Any, Literal
 
     from docutils import nodes
     from docutils.nodes import Node
@@ -60,7 +69,7 @@ default_settings: dict[str, Any] = {
 
 # This is increased every time an environment attribute is added
 # or changed to properly invalidate pickle files.
-ENV_VERSION = 63
+ENV_VERSION = 64
 
 # config status
 CONFIG_UNSET = -1
@@ -81,61 +90,6 @@ versioning_conditions: dict[str, Literal[False] | Callable[[Node], bool]] = {
     'text': is_translatable,
 }
 
-if TYPE_CHECKING:
-    from collections.abc import MutableMapping
-    from typing import Literal, 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
-
-    class _DomainsType(MutableMapping[str, Domain]):
-        @overload
-        def __getitem__(self, key: Literal["c"]) -> CDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["cpp"]) -> CPPDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["changeset"]) -> ChangeSetDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["citation"]) -> CitationDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["index"]) -> IndexDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["js"]) -> JavaScriptDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["math"]) -> MathDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["py"]) -> PythonDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["rst"]) -> ReSTDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["std"]) -> StandardDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["duration"]) -> DurationDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: Literal["todo"]) -> TodoDomain: ...  # NoQA: E704
-        @overload
-        def __getitem__(self, key: str) -> Domain: ...  # NoQA: E704
-        def __getitem__(self, _key: str) -> Domain: raise NotImplementedError  # NoQA: E704
-        def __setitem__(  # NoQA: E301,E704
-            self, key: str, value: Domain,
-        ) -> NoReturn: raise NotImplementedError
-        def __delitem__(self, key: str) -> NoReturn: raise NotImplementedError  # NoQA: E704
-        def __iter__(self) -> NoReturn: raise NotImplementedError  # NoQA: E704
-        def __len__(self) -> NoReturn: raise NotImplementedError  # NoQA: E704
-
-else:
-    _DomainsType = dict
-
 
 class BuildEnvironment:
     """
@@ -144,8 +98,6 @@ class BuildEnvironment:
     transformations to resolve links to them.
     """
 
-    domains: _DomainsType
-
     # --------- ENVIRONMENT INITIALIZATION -------------------------------------
 
     def __init__(self, app: Sphinx) -> None:
@@ -163,9 +115,6 @@ class BuildEnvironment:
         self.versioning_condition: Literal[False] | Callable[[Node], bool] | None = None
         self.versioning_compare: bool | None = None
 
-        # all the registered domains, set by the application
-        self.domains = _DomainsType()
-
         # the docutils settings for building
         self.settings: dict[str, Any] = default_settings.copy()
         self.settings['env'] = self
@@ -242,7 +191,7 @@ class BuildEnvironment:
         self.dlfiles: DownloadFiles = DownloadFiles()
 
         # the original URI for images
-        self.original_image_uri: dict[str, str] = {}
+        self.original_image_uri: dict[_StrPath, str] = {}
 
         # temporary data storage while reading a document
         self.temp_data: dict[str, Any] = {}
@@ -270,6 +219,9 @@ class BuildEnvironment:
         # objtype index -> (domain, type, objname (localized))
         self._search_index_objnames: dict[int, tuple[str, str, str]] = {}
 
+        # all the registered domains, set by the application
+        self.domains: _DomainsContainer = _DomainsContainer._from_environment(self)
+
         # set up environment
         self.setup(app)
 
@@ -277,7 +229,7 @@ class BuildEnvironment:
         """Obtains serializable data for pickling."""
         __dict__ = self.__dict__.copy()
         # clear unpickable attributes
-        __dict__.update(app=None, domains={}, events=None)
+        __dict__.update(app=None, domains=None, events=None)
         # clear in-memory doctree caches, to reduce memory consumption and
         # ensure that, upon restoring the state, the most recent pickled files
         # on the disk are used instead of those from a possibly outdated state
@@ -304,51 +256,83 @@ class BuildEnvironment:
         self.project = app.project
         self.version = app.registry.get_envversion(app)
 
-        # initialize domains
-        self.domains = _DomainsType()
-        for domain in app.registry.create_domains(self):
-            self.domains[domain.name] = domain
-
+        # initialise domains
+        if self.domains is None:
+            # if we are unpickling an environment, we need to recreate the domains
+            self.domains = _DomainsContainer._from_environment(self)
         # setup domains (must do after all initialization)
-        for domain in self.domains.values():
-            domain.setup()
+        self.domains._setup()
 
-        # initialize config
-        self._update_config(app.config)
+        # Initialise config.
+        # The old config is self.config, restored from the pickled environment.
+        # The new config is app.config, always recreated from ``conf.py``
+        self.config_status, self.config_status_extra = self._config_status(
+            old_config=self.config, new_config=app.config, verbosity=app.verbosity
+        )
+        self.config = app.config
 
         # initialize settings
         self._update_settings(app.config)
 
-    def _update_config(self, config: Config) -> None:
-        """Update configurations by new one."""
-        self.config_status = CONFIG_OK
-        self.config_status_extra = ''
-        if self.config is None:
-            self.config_status = CONFIG_NEW
-        elif self.config.extensions != config.extensions:
-            self.config_status = CONFIG_EXTENSIONS_CHANGED
-            extensions = sorted(
-                set(self.config.extensions) ^ set(config.extensions))
+    @staticmethod
+    def _config_status(
+        *, old_config: Config | None, new_config: Config, verbosity: int
+    ) -> tuple[int, str]:
+        """Report the differences between two Config objects.
+
+        Returns a triple of:
+
+        1. The new configuration
+        2. A status code indicating how the configuration has changed.
+        3. A status message indicating what has changed.
+        """
+        if old_config is None:
+            return CONFIG_NEW, ''
+
+        if old_config.extensions != new_config.extensions:
+            old_extensions = set(old_config.extensions)
+            new_extensions = set(new_config.extensions)
+            extensions = old_extensions ^ new_extensions
             if len(extensions) == 1:
-                extension = extensions[0]
+                extension = extensions.pop()
             else:
-                extension = '%d' % (len(extensions),)
-            self.config_status_extra = f' ({extension!r})'
-        else:
-            # check if a config value was changed that affects how
-            # doctrees are read
-            for item in config.filter(frozenset({'env'})):
-                if self.config[item.name] != item.value:
-                    self.config_status = CONFIG_CHANGED
-                    self.config_status_extra = f' ({item.name!r})'
-                    break
+                extension = f'{len(extensions)}'
+            return CONFIG_EXTENSIONS_CHANGED, f' ({extension!r})'
+
+        # Log any changes in configuration keys
+        if changed_keys := _differing_config_keys(old_config, new_config):
+            changed_num = len(changed_keys)
+            if changed_num == 1:
+                logger.info(
+                    __('The configuration has changed (1 option: %r)'),
+                    next(iter(changed_keys)),
+                )
+            elif changed_num <= 5 or verbosity >= 1:
+                logger.info(
+                    __('The configuration has changed (%d options: %s)'),
+                    changed_num,
+                    ', '.join(map(repr, sorted(changed_keys))),
+                )
+            else:
+                logger.info(
+                    __('The configuration has changed (%d options: %s, ...)'),
+                    changed_num,
+                    ', '.join(map(repr, sorted(changed_keys)[:5])),
+                )
+
+        # check if a config value was changed that affects how doctrees are read
+        for item in new_config.filter(frozenset({'env'})):
+            if old_config[item.name] != item.value:
+                return CONFIG_CHANGED, f' ({item.name!r})'
 
-        self.config = config
+        return CONFIG_OK, ''
 
     def _update_settings(self, config: Config) -> None:
         """Update settings by new config."""
         self.settings['input_encoding'] = config.source_encoding
-        self.settings['trim_footnote_reference_space'] = config.trim_footnote_reference_space
+        self.settings['trim_footnote_reference_space'] = (
+            config.trim_footnote_reference_space
+        )
         self.settings['language_code'] = config.language
 
         # Allow to disable by 3rd party extension (workaround)
@@ -373,9 +357,12 @@ class BuildEnvironment:
             condition = versioning_conditions[method]
 
         if self.versioning_condition not in {None, condition}:
-            raise SphinxError(__('This environment is incompatible with the '
-                                 'selected builder, please choose another '
-                                 'doctree directory.'))
+            msg = __(
+                'This environment is incompatible with the '
+                'selected builder, please choose another '
+                'doctree directory.'
+            )
+            raise SphinxError(msg)
         self.versioning_condition = condition
         self.versioning_compare = compare
 
@@ -386,25 +373,24 @@ class BuildEnvironment:
             self.included.pop(docname, None)
             self.reread_always.discard(docname)
 
-        for domain in self.domains.values():
-            domain.clear_doc(docname)
+        self.domains._clear_doc(docname)
 
-    def merge_info_from(self, docnames: list[str], other: BuildEnvironment,
-                        app: Sphinx) -> None:
+    def merge_info_from(
+        self, docnames: Iterable[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.
         """
-        docnames = set(docnames)  # type: ignore[assignment]
+        docnames = frozenset(docnames)
         for docname in docnames:
             self.all_docs[docname] = other.all_docs[docname]
             self.included[docname] = other.included[docname]
             if docname in other.reread_always:
                 self.reread_always.add(docname)
 
-        for domainname, domain in self.domains.items():
-            domain.merge_domaindata(docnames, other.domaindata[domainname])
+        self.domains._merge_domain_data(docnames, other.domaindata)
         self.events.emit('env-merge-info', self, docnames, other)
 
     def path2doc(self, filename: str | os.PathLike[str]) -> str | None:
@@ -434,12 +420,13 @@ class BuildEnvironment:
         if filename.startswith(('/', os.sep)):
             rel_fn = filename[1:]
         else:
-            docdir = path.dirname(self.doc2path(docname or self.docname,
-                                                base=False))
+            docdir = path.dirname(self.doc2path(docname or self.docname, base=False))
             rel_fn = path.join(docdir, filename)
 
-        return (canon_path(path.normpath(rel_fn)),
-                path.normpath(path.join(self.srcdir, rel_fn)))
+        return (
+            canon_path(path.normpath(rel_fn)),
+            path.normpath(path.join(self.srcdir, rel_fn)),
+        )
 
     @property
     def found_docs(self) -> set[str]:
@@ -451,9 +438,11 @@ class BuildEnvironment:
         self.found_docs.
         """
         try:
-            exclude_paths = (self.config.exclude_patterns +
-                             self.config.templates_path +
-                             builder.get_asset_paths())
+            exclude_paths = (
+                self.config.exclude_patterns
+                + self.config.templates_path
+                + builder.get_asset_paths()
+            )
             self.project.discover(exclude_paths, self.config.include_patterns)
 
             # Current implementation is applying translated messages in the reading
@@ -464,18 +453,25 @@ class BuildEnvironment:
             # move i18n process into the writing phase, and remove these lines.
             if builder.use_message_catalog:
                 # add catalog mo file dependency
-                repo = CatalogRepository(self.srcdir, self.config.locale_dirs,
-                                         self.config.language, self.config.source_encoding)
+                repo = CatalogRepository(
+                    self.srcdir,
+                    self.config.locale_dirs,
+                    self.config.language,
+                    self.config.source_encoding,
+                )
                 mo_paths = {c.domain: c.mo_path for c in repo.catalogs}
                 for docname in self.found_docs:
                     domain = docname_to_domain(docname, self.config.gettext_compact)
                     if domain in mo_paths:
                         self.dependencies[docname].add(mo_paths[domain])
         except OSError as exc:
-            raise DocumentError(__('Failed to scan documents in %s: %r') %
-                                (self.srcdir, exc)) from exc
+            raise DocumentError(
+                __('Failed to scan documents in %s: %r') % (self.srcdir, exc)
+            ) from exc
 
-    def get_outdated_files(self, config_changed: bool) -> tuple[set[str], set[str], set[str]]:
+    def get_outdated_files(
+        self, config_changed: bool
+    ) -> tuple[set[str], set[str], set[str]]:
         """Return (added, changed, removed) sets."""
         # clear all files no longer present
         removed = set(self.all_docs) - self.found_docs
@@ -507,10 +503,12 @@ class BuildEnvironment:
                 mtime = self.all_docs[docname]
                 newmtime = _last_modified_time(self.doc2path(docname))
                 if newmtime > mtime:
-                    logger.debug('[build target] outdated %r: %s -> %s',
-                                 docname,
-                                 _format_rfc3339_microseconds(mtime),
-                                 _format_rfc3339_microseconds(newmtime))
+                    logger.debug(
+                        '[build target] outdated %r: %s -> %s',
+                        docname,
+                        _format_rfc3339_microseconds(mtime),
+                        _format_rfc3339_microseconds(newmtime),
+                    )
                     changed.add(docname)
                     continue
                 # finally, check the mtime of dependencies
@@ -521,7 +519,8 @@ class BuildEnvironment:
                         if not path.isfile(deppath):
                             logger.debug(
                                 '[build target] changed %r missing dependency %r',
-                                docname, deppath,
+                                docname,
+                                deppath,
                             )
                             changed.add(docname)
                             break
@@ -529,7 +528,8 @@ class BuildEnvironment:
                         if depmtime > mtime:
                             logger.debug(
                                 '[build target] outdated %r from dependency %r: %s -> %s',
-                                docname, deppath,
+                                docname,
+                                deppath,
                                 _format_rfc3339_microseconds(mtime),
                                 _format_rfc3339_microseconds(depmtime),
                             )
@@ -557,8 +557,7 @@ class BuildEnvironment:
         self.temp_data['docname'] = docname
         # defaults to the global default, but can be re-set in a document
         self.temp_data['default_role'] = self.config.default_role
-        self.temp_data['default_domain'] = \
-            self.domains.get(self.config.primary_domain)
+        self.temp_data['default_domain'] = self.domains.get(self.config.primary_domain)
 
     # utilities to use while reading a document
 
@@ -616,7 +615,8 @@ class BuildEnvironment:
         try:
             return self.domains[domainname]
         except KeyError as exc:
-            raise ExtensionError(__('Domain %r is not registered') % domainname) from exc
+            msg = __('Domain %r is not registered') % domainname
+            raise ExtensionError(msg) from exc
 
     # --------- RESOLVING REFERENCES AND TOCTREES ------------------------------
 
@@ -663,7 +663,10 @@ class BuildEnvironment:
         # now, resolve all toctree nodes
         for toctreenode in doctree.findall(addnodes.toctree):
             result = toctree_adapters._resolve_toctree(
-                self, docname, builder, toctreenode,
+                self,
+                docname,
+                builder,
+                toctreenode,
                 prune=prune_toctrees,
                 includehidden=includehidden,
             )
@@ -674,9 +677,17 @@ class BuildEnvironment:
 
         return doctree
 
-    def resolve_toctree(self, docname: str, builder: Builder, toctree: addnodes.toctree,
-                        prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
-                        collapse: bool = False, includehidden: bool = False) -> Node | None:
+    def resolve_toctree(
+        self,
+        docname: str,
+        builder: Builder,
+        toctree: addnodes.toctree,
+        prune: bool = True,
+        maxdepth: int = 0,
+        titles_only: bool = False,
+        collapse: bool = False,
+        includehidden: bool = False,
+    ) -> 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.
@@ -689,7 +700,10 @@ class BuildEnvironment:
         be collapsed.
         """
         return toctree_adapters._resolve_toctree(
-            self, docname, builder, toctree,
+            self,
+            docname,
+            builder,
+            toctree,
             prune=prune,
             maxdepth=maxdepth,
             titles_only=titles_only,
@@ -697,8 +711,9 @@ class BuildEnvironment:
             includehidden=includehidden,
         )
 
-    def resolve_references(self, doctree: nodes.document, fromdocname: str,
-                           builder: Builder) -> None:
+    def resolve_references(
+        self, doctree: nodes.document, fromdocname: str, builder: Builder
+    ) -> None:
         self.apply_post_transforms(doctree, fromdocname)
 
     def apply_post_transforms(self, doctree: nodes.document, docname: str) -> None:
@@ -723,7 +738,7 @@ class BuildEnvironment:
 
         relations = {}
         docnames = _traverse_toctree(
-            traversed, None, self.config.root_doc, self.toctree_includes,
+            traversed, None, self.config.root_doc, self.toctree_includes
         )
         prev_doc = None
         parent, docname = next(docnames)
@@ -750,15 +765,32 @@ class BuildEnvironment:
                     continue
                 if 'orphan' in self.metadata[docname]:
                     continue
-                logger.warning(__("document isn't included in any toctree"),
-                               location=docname)
+                logger.warning(
+                    __("document isn't included in any toctree"), location=docname
+                )
+        # Call _check_toc_parents here rather than in  _get_toctree_ancestors()
+        # because that method is called multiple times per document and would
+        # lead to duplicate warnings.
+        _check_toc_parents(self.toctree_includes)
 
         # call check-consistency for all extensions
-        for domain in self.domains.values():
-            domain.check_consistency()
+        self.domains._check_consistency()
         self.events.emit('env-check-consistency', self)
 
 
+def _differing_config_keys(old: Config, new: Config) -> frozenset[str]:
+    """Return a set of keys that differ between two config objects."""
+    old_vals = {c.name: c.value for c in old}
+    new_vals = {c.name: c.value for c in new}
+    not_in_both = old_vals.keys() ^ new_vals.keys()
+    different_values = {
+        key
+        for key in old_vals.keys() & new_vals.keys()
+        if stable_str(old_vals[key]) != stable_str(new_vals[key])
+    }
+    return frozenset(not_in_both | different_values)
+
+
 def _traverse_toctree(
     traversed: set[str],
     parent: str | None,
@@ -766,9 +798,12 @@ def _traverse_toctree(
     toctree_includes: dict[str, list[str]],
 ) -> Iterator[tuple[str | None, str]]:
     if parent == docname:
-        logger.warning(__('self referenced toctree found. Ignored.'),
-                       location=docname, type='toc',
-                       subtype='circular')
+        logger.warning(
+            __('self referenced toctree found. Ignored.'),
+            location=docname,
+            type='toc',
+            subtype='circular',
+        )
         return
 
     # traverse toctree by pre-order
@@ -777,8 +812,29 @@ def _traverse_toctree(
 
     for child in toctree_includes.get(docname, ()):
         for sub_parent, sub_docname in _traverse_toctree(
-            traversed, docname, child, toctree_includes,
+            traversed, docname, child, toctree_includes
         ):
             if sub_docname not in traversed:
                 yield sub_parent, sub_docname
                 traversed.add(sub_docname)
+
+
+def _check_toc_parents(toctree_includes: dict[str, list[str]]) -> None:
+    toc_parents: dict[str, list[str]] = {}
+    for parent, children in toctree_includes.items():
+        for child in children:
+            toc_parents.setdefault(child, []).append(parent)
+
+    for doc, parents in sorted(toc_parents.items()):
+        if len(parents) > 1:
+            logger.info(
+                __(
+                    'document is referenced in multiple toctrees: %s, selecting: %s <- %s'
+                ),
+                parents,
+                max(parents),
+                doc,
+                location=doc,
+                type='toc',
+                subtype='multiple_toc_parents',
+            )

sphinx/environment/adapters/asset.py

@@ -1,6 +1,7 @@
 """Assets adapter for sphinx.environment."""
 
 from sphinx.environment import BuildEnvironment
+from sphinx.util._pathlib import _StrPath
 
 
 class ImageAdapter:
@@ -9,7 +10,7 @@ class ImageAdapter:
 
     def get_original_image_uri(self, name: str) -> str:
         """Get the original image URI."""
-        while name in self.env.original_image_uri:
-            name = self.env.original_image_uri[name]
+        while _StrPath(name) in self.env.original_image_uri:
+            name = self.env.original_image_uri[_StrPath(name)]
 
         return name