Bump types-docutils to 0.22.3.20251115 (#13634)

Co-authored-by: Adam Dangoor <[email protected]>
Co-authored-by: danieleades <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: daniel.eades <[email protected]>

Author: 5 people

pyproject.toml

@@ -137,7 +137,7 @@ type-stubs = [
     # align with versions used elsewhere
     "types-colorama==0.4.15.20250801",
     "types-defusedxml==0.7.0.20250822",
-    "types-docutils==0.21.0.20250525",
+    "types-docutils==0.22.3.20251115",
     "types-Pillow==10.2.0.20240822",
     "types-Pygments==2.19.0.20251121",
     "types-requests==2.32.4.20250913",

sphinx/builders/__init__.py

@@ -10,6 +10,7 @@
 from typing import TYPE_CHECKING, final
 
 from docutils import nodes
+from docutils.utils import DependencyList
 
 from sphinx._cli.util.colour import bold
 from sphinx.deprecation import _deprecation_warning
@@ -687,7 +688,7 @@ def write_doctree(
         doctree.settings = doctree.settings.copy()
         doctree.settings.warning_stream = None
         doctree.settings.env = None
-        doctree.settings.record_dependencies = None
+        doctree.settings.record_dependencies = DependencyList()
 
         doctree_filename = self.doctreedir / f'{docname}.doctree'
         doctree_filename.parent.mkdir(parents=True, exist_ok=True)

sphinx/builders/_epub_base.py

@@ -294,7 +294,7 @@ def fix_ids(self, tree: nodes.document) -> None:
         for target in tree.findall(nodes.target):
             self._update_node_id(target)
 
-            next_node: Node = target.next_node(ascend=True)
+            next_node: Node | None = target.next_node(ascend=True)
             if isinstance(next_node, nodes.Element):
                 self._update_node_id(next_node)
 

sphinx/builders/latex/transforms.py

@@ -528,7 +528,7 @@ def run(self, **kwargs: Any) -> None:
             citations += node
 
         if len(citations) > 0:
-            self.document += citations  # type: ignore[attr-defined]
+            self.document += citations
 
 
 class CitationReferenceTransform(SphinxPostTransform):

sphinx/builders/linkcheck.py

@@ -31,7 +31,7 @@
 from sphinx.util import logging, requests
 from sphinx.util._uri import encode_uri
 from sphinx.util.http_date import rfc1123_to_epoch
-from sphinx.util.nodes import get_node_line
+from sphinx.util.nodes import NodeMatcher, get_node_line
 
 if TYPE_CHECKING:
     from collections.abc import Callable, Iterator, Sequence
@@ -221,7 +221,8 @@ class HyperlinkCollector(SphinxPostTransform):
     default_priority = 800
 
     def run(self, **kwargs: Any) -> None:
-        for node in self.document.findall():
+        matcher = NodeMatcher(nodes.image, nodes.raw, nodes.reference)
+        for node in matcher.findall(self.document):
             if uri := self.find_uri(node):
                 self._add_uri(uri, node)
 

sphinx/builders/xml.py

@@ -87,7 +87,7 @@ def _translate(self, doctree: nodes.document) -> str:
 
         # copied from docutils.writers.docutils_xml.Writer.translate()
         # so that we can override the translator class
-        visitor: XMLTranslator = self.create_translator(doctree)
+        visitor: XMLTranslator = self.create_translator(doctree)  # type: ignore[assignment]
         doctree.walkabout(visitor)
         return ''.join(visitor.output)
 

sphinx/directives/__init__.py

@@ -325,8 +325,14 @@ def run(self) -> list[Node]:
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
+        # TODO: TYPING: Upstream docutils should widen roles.role() to accept
+        #       the RST language module shape (has a `roles` mapping);
+        #       current stub requires _LanguageModule from docutils.languages.
         role, messages = roles.role(
-            role_name, self.state_machine.language, self.lineno, self.state.reporter
+            role_name,
+            self.state_machine.language,  # type: ignore[arg-type]
+            self.lineno,
+            self.state.reporter,
         )
         if role:
             docutils.register_role('', role)  # type: ignore[arg-type]

sphinx/directives/code.py

@@ -119,7 +119,10 @@ class CodeBlock(SphinxDirective):
     def run(self) -> list[Node]:
         document = self.state.document
         code = '\n'.join(self.content)
-        location = self.state_machine.get_source_and_line(self.lineno)
+        source, line = self.state_machine.get_source_and_line(self.lineno)
+        location: tuple[str, int] | None = (
+            (source, line) if source is not None and line is not None else None
+        )
 
         linespec = self.options.get('emphasize-lines')
         if linespec:
@@ -141,7 +144,6 @@ def run(self) -> list[Node]:
             hl_lines = None
 
         if 'dedent' in self.options:
-            location = self.state_machine.get_source_and_line(self.lineno)
             lines = code.splitlines(True)
             lines = dedent_lines(lines, self.options['dedent'], location=location)
             code = ''.join(lines)
@@ -454,7 +456,10 @@ def run(self) -> list[Node]:
             self.options['diff'] = path
 
         try:
-            location = self.state_machine.get_source_and_line(self.lineno)
+            source, line = self.state_machine.get_source_and_line(self.lineno)
+            location: tuple[str, int] | None = (
+                (source, line) if source is not None and line is not None else None
+            )
             rel_filename, filename = self.env.relfn2path(self.arguments[0])
             self.env.note_dependency(rel_filename)
 

sphinx/directives/other.py

@@ -405,8 +405,7 @@ def _insert_input(include_lines: list[str], source: str) -> None:
 
         # Only enable this patch if there are listeners for 'include-read'.
         if self.env.events.listeners.get('include-read'):
-            # See https://github.com/python/mypy/issues/2427 for details on the mypy issue
-            self.state_machine.insert_input = _insert_input
+            self.state_machine.insert_input = _insert_input  # type: ignore[assignment,method-assign]
 
         if self.arguments[0].startswith('<') and self.arguments[0].endswith('>'):
             # docutils "standard" includes, do not do path processing

sphinx/directives/patches.py

@@ -18,6 +18,7 @@
 from sphinx.util.osutil import SEP, relpath
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
     from typing import ClassVar
 
     from docutils.nodes import Node
@@ -29,12 +30,12 @@
 logger = logging.getLogger(__name__)
 
 
-class Figure(images.Figure):  # type: ignore[misc]
+class Figure(images.Figure):
     """The figure directive which applies `:name:` option to the figure node
     instead of the image node.
     """
 
-    def run(self) -> list[Node]:
+    def run(self) -> Sequence[Node]:
         name = self.options.pop('name', None)
         result = super().run()
         if len(result) == 2 or isinstance(result[0], nodes.system_message):
@@ -55,12 +56,12 @@ def run(self) -> list[Node]:
         return [figure_node]
 
 
-class CSVTable(tables.CSVTable):  # type: ignore[misc]
+class CSVTable(tables.CSVTable):
     """The csv-table directive which searches a CSV file from Sphinx project's source
     directory when an absolute path is given via :file: option.
     """
 
-    def run(self) -> list[Node]:
+    def run(self) -> Sequence[nodes.table | nodes.system_message]:
         if 'file' in self.options and self.options['file'].startswith((SEP, os.sep)):
             env = self.state.document.settings.env
             filename = Path(self.options['file'])