Add _DomainsContainer for better static typing (#12783)

Co-authored-by: Daniel Eades <[email protected]>

sphinx/builders/changes.py

@@ -4,11 +4,10 @@
 
 import html
 from os import path
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING, Any
 
 from sphinx import package_dir
 from sphinx.builders import Builder
-from sphinx.domains.changeset import ChangeSetDomain
 from sphinx.locale import _, __
 from sphinx.theming import HTMLThemeFactory
 from sphinx.util import logging
@@ -49,7 +48,7 @@ def get_outdated_docs(self) -> str:
 
     def write(self, *ignored: Any) -> None:
         version = self.config.version
-        domain = cast(ChangeSetDomain, self.env.get_domain('changeset'))
+        domain = self.env.domains.changeset_domain
         libchanges: dict[str, list[tuple[str, str, int]]] = {}
         apichanges: list[tuple[str, str, int]] = []
         otherchanges: dict[tuple[str, str], list[tuple[str, str, int]]] = {}

sphinx/builders/html/__init__.py

@@ -33,7 +33,7 @@
 from sphinx.builders.html._build_info import BuildInfo
 from sphinx.config import ENUM, Config
 from sphinx.deprecation import _deprecation_warning
-from sphinx.domains import Domain, Index, IndexEntry
+from sphinx.domains import Index, IndexEntry
 from sphinx.environment.adapters.asset import ImageAdapter
 from sphinx.environment.adapters.indexentries import IndexEntries
 from sphinx.environment.adapters.toctree import document_toc, global_toctree_for_doc
@@ -439,8 +439,7 @@ def prepare_writing(self, docnames: set[str]) -> None:
                 indices_config = frozenset(indices_config)
             else:
                 check_names = False
-            for domain_name in sorted(self.env.domains):
-                domain: Domain = self.env.domains[domain_name]
+            for domain in self.env.domains.sorted():
                 for index_cls in domain.indices:
                     index_name = f'{domain.name}-{index_cls.name}'
                     if check_names and index_name not in indices_config:

sphinx/builders/latex/transforms.py

@@ -15,7 +15,6 @@
     math_reference,
     thebibliography,
 )
-from sphinx.domains.citation import CitationDomain
 from sphinx.locale import __
 from sphinx.transforms import SphinxTransform
 from sphinx.transforms.post_transforms import SphinxPostTransform
@@ -536,7 +535,7 @@ class CitationReferenceTransform(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        domain = cast(CitationDomain, self.env.get_domain('citation'))
+        domain = self.env.domains.citation_domain
         matcher = NodeMatcher(addnodes.pending_xref, refdomain='citation', reftype='ref')
         for node in matcher.findall(self.document):
             docname, labelid, _ = domain.citations.get(node['reftarget'], ('', '', 0))
@@ -557,7 +556,7 @@ class MathReferenceTransform(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        equations = self.env.get_domain('math').data['objects']
+        equations = self.env.domains.math_domain.data['objects']
         for node in self.document.findall(addnodes.pending_xref):
             if node['refdomain'] == 'math' and node['reftype'] in ('eq', 'numref'):
                 docname, _ = equations.get(node['reftarget'], (None, None))

sphinx/builders/xml.py

@@ -75,9 +75,8 @@ def write_doc(self, docname: str, doctree: nodes.document) -> None:
         # work around multiple string % tuple issues in docutils;
         # replace tuples in attribute values with lists
         doctree = doctree.deepcopy()
-        for domain in self.env.domains.values():
-            xmlns = "xmlns:" + domain.name
-            doctree[xmlns] = "https://www.sphinx-doc.org/"
+        for domain in self.env.domains.sorted():
+            doctree[f'xmlns:{domain.name}'] = 'https://www.sphinx-doc.org/'
         for node in doctree.findall(nodes.Element):
             for att, value in node.attributes.items():
                 if isinstance(value, tuple):

sphinx/directives/__init__.py

@@ -351,7 +351,7 @@ def run(self) -> list[Node]:
         domain_name = self.arguments[0].lower()
         # if domain_name not in env.domains:
         #     # try searching by label
-        #     for domain in env.domains.values():
+        #     for domain in env.domains.sorted():
         #         if domain.label.lower() == domain_name:
         #             domain_name = domain.name
         #             break

sphinx/directives/patches.py

@@ -12,7 +12,6 @@
 from docutils.parsers.rst.roles import set_classes
 
 from sphinx.directives import optional_int
-from sphinx.domains.math import MathDomain
 from sphinx.locale import __
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
@@ -165,7 +164,7 @@ def add_target(self, ret: list[Node]) -> None:
             return
 
         # register label to domain
-        domain = cast(MathDomain, self.env.get_domain('math'))
+        domain = self.env.domains.math_domain
         domain.note_equation(self.env.docname, node['label'], location=node)
         node['number'] = domain.get_equation_number_for(node['label'])
 

sphinx/domains/__init__.py

@@ -7,13 +7,14 @@
 from __future__ import annotations
 
 import copy
-from typing import TYPE_CHECKING, Any, cast
+from typing import TYPE_CHECKING
 
 from sphinx.domains._index import Index, IndexEntry
 from sphinx.locale import _
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Iterable, Sequence
+    from collections.abc import Callable, Iterable, Sequence, Set
+    from typing import Any
 
     from docutils import nodes
     from docutils.nodes import Element, Node
@@ -136,10 +137,8 @@ def __init__(self, env: BuildEnvironment) -> None:
 
     def setup(self) -> None:
         """Set up domain object."""
-        from sphinx.domains.std import StandardDomain
-
         # Add special hyperlink target for index pages (ex. py-modindex)
-        std = cast(StandardDomain, self.env.get_domain('std'))
+        std = self.env.domains.standard_domain
         for index in self.indices:
             if index.name and index.localname:
                 docname = f"{self.name}-{index.name}"
@@ -199,7 +198,7 @@ def clear_doc(self, docname: str) -> None:
         """Remove traces of a document in the domain-specific inventories."""
         pass
 
-    def merge_domaindata(self, docnames: list[str], otherdata: dict[str, Any]) -> None:
+    def merge_domaindata(self, docnames: Set[str], otherdata: dict[str, Any]) -> None:
         """Merge in data regarding *docnames* from a different domaindata
         inventory (coming from a subprocess in parallel builds).
         """