Migrate to Node.findall() from Node.traverse()

sphinx/builders/__init__.py

@@ -176,7 +176,7 @@ def get_asset_paths(self) -> List[str]:
     def post_process_images(self, doctree: Node) -> None:
         """Pick the best candidate for all image URIs."""
         images = ImageAdapter(self.env)
-        for node in doctree.traverse(nodes.image):
+        for node in doctree.findall(nodes.image):
             if '?' in node['candidates']:
                 # don't rewrite nonlocal image URIs
                 continue

sphinx/builders/_epub_base.py

@@ -277,22 +277,22 @@ def update_node_id(node: Element) -> None:
                     new_ids.append(new_id)
             node['ids'] = new_ids
 
-        for reference in tree.traverse(nodes.reference):
+        for reference in tree.findall(nodes.reference):
             if 'refuri' in reference:
                 m = self.refuri_re.match(reference['refuri'])
                 if m:
                     reference['refuri'] = self.fix_fragment(m.group(1), m.group(2))
             if 'refid' in reference:
                 reference['refid'] = self.fix_fragment('', reference['refid'])
 
-        for target in tree.traverse(nodes.target):
+        for target in tree.findall(nodes.target):
             update_node_id(target)
 
             next_node: Node = target.next_node(ascend=True)
             if isinstance(next_node, nodes.Element):
                 update_node_id(next_node)
 
-        for desc_signature in tree.traverse(addnodes.desc_signature):
+        for desc_signature in tree.findall(addnodes.desc_signature):
             update_node_id(desc_signature)
 
     def add_visible_links(self, tree: nodes.document, show_urls: str = 'inline') -> None:
@@ -323,14 +323,14 @@ def footnote_spot(tree: nodes.document) -> Tuple[Element, int]:
             # a) place them after the last existing footnote
             # b) place them after an (empty) Footnotes rubric
             # c) create an empty Footnotes rubric at the end of the document
-            fns = list(tree.traverse(nodes.footnote))
+            fns = list(tree.findall(nodes.footnote))
             if fns:
                 fn = fns[-1]
                 return fn.parent, fn.parent.index(fn) + 1
-            for node in tree.traverse(nodes.rubric):
+            for node in tree.findall(nodes.rubric):
                 if len(node) == 1 and node.astext() == FOOTNOTES_RUBRIC_NAME:
                     return node.parent, node.parent.index(node) + 1
-            doc = list(tree.traverse(nodes.document))[0]
+            doc = next(tree.findall(nodes.document))
             rub = nodes.rubric()
             rub.append(nodes.Text(FOOTNOTES_RUBRIC_NAME))
             doc.append(rub)
@@ -339,10 +339,10 @@ def footnote_spot(tree: nodes.document) -> Tuple[Element, int]:
         if show_urls == 'no':
             return
         if show_urls == 'footnote':
-            doc = list(tree.traverse(nodes.document))[0]
+            doc = next(tree.findall(nodes.document))
             fn_spot, fn_idx = footnote_spot(tree)
             nr = 1
-        for node in list(tree.traverse(nodes.reference)):
+        for node in list(tree.findall(nodes.reference)):
             uri = node.get('refuri', '')
             if (uri.startswith('http:') or uri.startswith('https:') or
                     uri.startswith('ftp:')) and uri not in node.astext():

sphinx/builders/gettext.py

@@ -146,7 +146,7 @@ def compile_catalogs(self, catalogs: Set[CatalogInfo], message: str) -> None:
     def write_doc(self, docname: str, doctree: nodes.document) -> None:
         catalog = self.catalogs[docname_to_domain(docname, self.config.gettext_compact)]
 
-        for toctree in self.env.tocs[docname].traverse(addnodes.toctree):
+        for toctree in self.env.tocs[docname].findall(addnodes.toctree):
             for node, msg in extract_messages(toctree):
                 node.uid = ''  # type: ignore  # Hack UUID model
                 catalog.add(msg, node)

sphinx/builders/html/__init__.py

@@ -866,7 +866,7 @@ def post_process_images(self, doctree: Node) -> None:
         Builder.post_process_images(self, doctree)
 
         if self.config.html_scaled_image_link and self.html_scaled_image_link:
-            for node in doctree.traverse(nodes.image):
+            for node in doctree.findall(nodes.image):
                 if not any((key in node) for key in ['scale', 'width', 'height']):
                     # resizing options are not given. scaled image link is available
                     # only for resized images.

sphinx/builders/html/transforms.py

@@ -48,7 +48,7 @@ class KeyboardTransform(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         matcher = NodeMatcher(nodes.literal, classes=["kbd"])
-        for node in self.document.traverse(matcher):  # type: nodes.literal
+        for node in self.document.findall(matcher):  # type: nodes.literal
             parts = self.pattern.split(node[-1].astext())
             if len(parts) == 1 or self.is_multiwords_key(parts):
                 continue

sphinx/builders/latex/__init__.py

@@ -280,7 +280,7 @@ def write(self, *ignored: Any) -> None:
                                            encoding='utf-8', overwrite_if_changed=True)
             with progress_message(__("processing %s") % targetname):
                 doctree = self.env.get_doctree(docname)
-                toctree = next(iter(doctree.traverse(addnodes.toctree)), None)
+                toctree = next(doctree.findall(addnodes.toctree), None)
                 if toctree and toctree.get('maxdepth') > 0:
                     tocdepth = toctree.get('maxdepth')
                 else:
@@ -310,7 +310,7 @@ def write(self, *ignored: Any) -> None:
     def get_contentsname(self, indexfile: str) -> str:
         tree = self.env.get_doctree(indexfile)
         contentsname = None
-        for toctree in tree.traverse(addnodes.toctree):
+        for toctree in tree.findall(addnodes.toctree):
             if 'caption' in toctree:
                 contentsname = toctree['caption']
                 break
@@ -338,7 +338,7 @@ def assemble_doctree(self, indexfile: str, toctree_only: bool, appendices: List[
             new_sect += nodes.title('<Set title in conf.py>',
                                     '<Set title in conf.py>')
             new_tree += new_sect
-            for node in tree.traverse(addnodes.toctree):
+            for node in tree.findall(addnodes.toctree):
                 new_sect += node
             tree = new_tree
         largetree = inline_all_toctrees(self, self.docnames, indexfile, tree,
@@ -353,7 +353,7 @@ def assemble_doctree(self, indexfile: str, toctree_only: bool, appendices: List[
         self.env.resolve_references(largetree, indexfile, self)
         # resolve :ref:s to distant tex files -- we can't add a cross-reference,
         # but append the document name
-        for pendingnode in largetree.traverse(addnodes.pending_xref):
+        for pendingnode in largetree.findall(addnodes.pending_xref):
             docname = pendingnode['refdocname']
             sectname = pendingnode['refsectname']
             newnodes: List[Node] = [nodes.emphasis(sectname, sectname)]

sphinx/builders/latex/transforms.py

@@ -33,7 +33,7 @@ class FootnoteDocnameUpdater(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         matcher = NodeMatcher(*self.TARGET_NODES)
-        for node in self.document.traverse(matcher):  # type: Element
+        for node in self.document.findall(matcher):  # type: Element
             node['docname'] = self.env.docname
 
 
@@ -45,7 +45,7 @@ class SubstitutionDefinitionsRemover(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        for node in list(self.document.traverse(nodes.substitution_definition)):
+        for node in list(self.document.findall(nodes.substitution_definition)):
             node.parent.remove(node)
 
 
@@ -81,7 +81,7 @@ def expand_show_urls(self) -> None:
         if show_urls is False or show_urls == 'no':
             return
 
-        for node in list(self.document.traverse(nodes.reference)):
+        for node in list(self.document.findall(nodes.reference)):
             uri = node.get('refuri', '')
             if uri.startswith(URI_SCHEMES):
                 if uri.startswith('mailto:'):
@@ -348,7 +348,7 @@ class LaTeXFootnoteTransform(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        footnotes = list(self.document.traverse(nodes.footnote))
+        footnotes = list(self.document.findall(nodes.footnote))
         for node in footnotes:
             node.parent.remove(node)
 
@@ -423,7 +423,7 @@ def depart_thead(self, node: nodes.thead) -> None:
         self.unrestrict(node)
 
     def depart_table(self, node: nodes.table) -> None:
-        tbody = list(node.traverse(nodes.tbody))[0]
+        tbody = next(node.findall(nodes.tbody))
         for footnote in reversed(self.table_footnotes):
             fntext = footnotetext('', *footnote.children, ids=footnote['ids'])
             tbody.insert(0, fntext)
@@ -501,7 +501,7 @@ class BibliographyTransform(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         citations = thebibliography()
-        for node in list(self.document.traverse(nodes.citation)):
+        for node in list(self.document.findall(nodes.citation)):
             node.parent.remove(node)
             citations += node
 
@@ -521,7 +521,7 @@ class CitationReferenceTransform(SphinxPostTransform):
     def run(self, **kwargs: Any) -> None:
         domain = cast(CitationDomain, self.env.get_domain('citation'))
         matcher = NodeMatcher(addnodes.pending_xref, refdomain='citation', reftype='ref')
-        for node in self.document.traverse(matcher):  # type: addnodes.pending_xref
+        for node in self.document.findall(matcher):  # type: addnodes.pending_xref
             docname, labelid, _ = domain.citations.get(node['reftarget'], ('', '', 0))
             if docname:
                 citation_ref = nodes.citation_reference('', '', *node.children,
@@ -540,7 +540,7 @@ class MathReferenceTransform(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         equations = self.env.get_domain('math').data['objects']
-        for node in self.document.traverse(addnodes.pending_xref):
+        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))
                 if docname:
@@ -555,7 +555,7 @@ class LiteralBlockTransform(SphinxPostTransform):
 
     def run(self, **kwargs: Any) -> None:
         matcher = NodeMatcher(nodes.container, literal_block=True)
-        for node in self.document.traverse(matcher):  # type: nodes.container
+        for node in self.document.findall(matcher):  # type: nodes.container
             newnode = captioned_literal_block('', *node.children, **node.attributes)
             node.replace_self(newnode)
 
@@ -566,7 +566,7 @@ class DocumentTargetTransform(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        for node in self.document.traverse(addnodes.start_of_file):
+        for node in self.document.findall(addnodes.start_of_file):
             section = node.next_node(nodes.section)
             if section:
                 section['ids'].append(':doc')  # special label for :doc:
@@ -602,9 +602,9 @@ class IndexInSectionTitleTransform(SphinxPostTransform):
     formats = ('latex',)
 
     def run(self, **kwargs: Any) -> None:
-        for node in list(self.document.traverse(nodes.title)):
+        for node in list(self.document.findall(nodes.title)):
             if isinstance(node.parent, nodes.section):
-                for i, index in enumerate(list(node.traverse(addnodes.index))):
+                for i, index in enumerate(node.findall(addnodes.index)):
                     # move the index node next to the section title
                     node.remove(index)
                     node.parent.insert(i + 1, index)

sphinx/builders/linkcheck.py

@@ -650,7 +650,7 @@ def run(self, **kwargs: Any) -> None:
         hyperlinks = builder.hyperlinks
 
         # reference nodes
-        for refnode in self.document.traverse(nodes.reference):
+        for refnode in self.document.findall(nodes.reference):
             if 'refuri' not in refnode:
                 continue
             uri = refnode['refuri']
@@ -664,7 +664,7 @@ def run(self, **kwargs: Any) -> None:
                 hyperlinks[uri] = uri_info
 
         # image nodes
-        for imgnode in self.document.traverse(nodes.image):
+        for imgnode in self.document.findall(nodes.image):
             uri = imgnode['candidates'].get('?')
             if uri and '://' in uri:
                 newuri = self.app.emit_firstresult('linkcheck-process-uri', uri)

sphinx/builders/manpage.py

@@ -98,7 +98,7 @@ def write(self, *ignored: Any) -> None:
             logger.info('} ', nonl=True)
             self.env.resolve_references(largetree, docname, self)
             # remove pending_xref nodes
-            for pendingnode in largetree.traverse(addnodes.pending_xref):
+            for pendingnode in largetree.findall(addnodes.pending_xref):
                 pendingnode.replace_self(pendingnode.children)
 
             docwriter.write(largetree, destination)

sphinx/builders/singlehtml.py

@@ -54,7 +54,7 @@ def get_relative_uri(self, from_: str, to: str, typ: str = None) -> str:
     def fix_refuris(self, tree: Node) -> None:
         # fix refuris with double anchor
         fname = self.config.root_doc + self.out_suffix
-        for refnode in tree.traverse(nodes.reference):
+        for refnode in tree.findall(nodes.reference):
             if 'refuri' not in refnode:
                 continue
             refuri = refnode['refuri']

sphinx/builders/texinfo.py

@@ -138,7 +138,7 @@ def assemble_doctree(self, indexfile: str, toctree_only: bool, appendices: List[
             new_sect += nodes.title('<Set title in conf.py>',
                                     '<Set title in conf.py>')
             new_tree += new_sect
-            for node in tree.traverse(addnodes.toctree):
+            for node in tree.findall(addnodes.toctree):
                 new_sect += node
             tree = new_tree
         largetree = inline_all_toctrees(self, self.docnames, indexfile, tree,
@@ -152,7 +152,7 @@ def assemble_doctree(self, indexfile: str, toctree_only: bool, appendices: List[
         logger.info(__("resolving references..."))
         self.env.resolve_references(largetree, indexfile, self)
         # TODO: add support for external :ref:s
-        for pendingnode in largetree.traverse(addnodes.pending_xref):
+        for pendingnode in largetree.findall(addnodes.pending_xref):
             docname = pendingnode['refdocname']
             sectname = pendingnode['refsectname']
             newnodes: List[Node] = [nodes.emphasis(sectname, sectname)]

sphinx/builders/xml.py

@@ -71,7 +71,7 @@ def write_doc(self, docname: str, doctree: Node) -> None:
         # work around multiple string % tuple issues in docutils;
         # replace tuples in attribute values with lists
         doctree = doctree.deepcopy()
-        for node in doctree.traverse(nodes.Element):
+        for node in doctree.findall(nodes.Element):
             for att, value in node.attributes.items():
                 if isinstance(value, tuple):
                     node.attributes[att] = list(value)

sphinx/directives/patches.py

@@ -83,7 +83,7 @@ def run(self) -> List[Node]:
                 # docutils' meta nodes aren't picklable because the class is nested
                 meta.__class__ = addnodes.meta
 
-        return result
+        return result  # type: ignore
 
 
 class RSTTable(tables.RSTTable):

sphinx/domains/c.py

@@ -3556,7 +3556,7 @@ def _render_symbol(self, s: Symbol, maxdepth: int, skipThis: bool,
         return nodes
 
     def apply(self, **kwargs: Any) -> None:
-        for node in self.document.traverse(AliasNode):
+        for node in self.document.findall(AliasNode):
             node = cast(AliasNode, node)
             sig = node.sig
             parentKey = node.parentKey

sphinx/domains/citation.py

@@ -112,7 +112,7 @@ class CitationDefinitionTransform(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         domain = cast(CitationDomain, self.env.get_domain('citation'))
-        for node in self.document.traverse(nodes.citation):
+        for node in self.document.findall(nodes.citation):
             # register citation node to domain
             node['docname'] = self.env.docname
             domain.note_citation(node)
@@ -131,7 +131,7 @@ class CitationReferenceTransform(SphinxTransform):
 
     def apply(self, **kwargs: Any) -> None:
         domain = cast(CitationDomain, self.env.get_domain('citation'))
-        for node in self.document.traverse(nodes.citation_reference):
+        for node in self.document.findall(nodes.citation_reference):
             target = node.astext()
             ref = pending_xref(target, refdomain='citation', reftype='ref',
                                reftarget=target, refwarn=True,

sphinx/domains/cpp.py

@@ -7459,7 +7459,7 @@ def _render_symbol(self, s: Symbol, maxdepth: int, skipThis: bool,
         return nodes
 
     def apply(self, **kwargs: Any) -> None:
-        for node in self.document.traverse(AliasNode):
+        for node in self.document.findall(AliasNode):
             node = cast(AliasNode, node)
             sig = node.sig
             parentKey = node.parentKey

sphinx/domains/index.py

@@ -48,7 +48,7 @@ def merge_domaindata(self, docnames: Iterable[str], otherdata: Dict) -> None:
     def process_doc(self, env: BuildEnvironment, docname: str, document: Node) -> None:
         """Process a document after it is read by the environment."""
         entries = self.entries.setdefault(env.docname, [])
-        for node in list(document.traverse(addnodes.index)):
+        for node in list(document.findall(addnodes.index)):
             try:
                 for entry in node['entries']:
                     split_index_msg(entry[0], entry[1])

sphinx/domains/math.py

@@ -78,7 +78,7 @@ def process_doc(self, env: BuildEnvironment, docname: str,
         def math_node(node: Node) -> bool:
             return isinstance(node, (nodes.math, nodes.math_block))
 
-        self.data['has_equations'][docname] = any(document.traverse(math_node))
+        self.data['has_equations'][docname] = any(document.findall(math_node))
 
     def clear_doc(self, docname: str) -> None:
         for equation_id, (doc, eqno) in list(self.equations.items()):

sphinx/domains/std.py

@@ -776,7 +776,7 @@ def process_doc(self, env: "BuildEnvironment", docname: str, document: nodes.doc
             elif self.is_enumerable_node(node):
                 sectname = self.get_numfig_title(node)
             else:
-                toctree = next(iter(node.traverse(addnodes.toctree)), None)
+                toctree = next(node.findall(addnodes.toctree), None)
                 if toctree and toctree.get('caption'):
                     sectname = toctree.get('caption')
                 else:

sphinx/environment/__init__.py

@@ -535,7 +535,7 @@ def get_and_resolve_doctree(self, docname: str, builder: "Builder",
         self.apply_post_transforms(doctree, docname)
 
         # now, resolve all toctree nodes
-        for toctreenode in doctree.traverse(addnodes.toctree):
+        for toctreenode in doctree.findall(addnodes.toctree):
             result = TocTree(self).resolve(docname, builder, toctreenode,
                                            prune=prune_toctrees,
                                            includehidden=includehidden)