Migrate to py3 style type annotation: sphinx.environment.adapters.toctree

sphinx/environment/adapters/toctree.py

@@ -8,9 +8,11 @@
     :license: BSD, see LICENSE for details.
 """
 
-from typing import Iterable, cast
+from typing import cast
+from typing import Iterable, List
 
 from docutils import nodes
+from docutils.nodes import Element, Node
 
 from sphinx import addnodes
 from sphinx.locale import __
@@ -20,20 +22,18 @@ from sphinx.util.nodes import clean_astext, process_only_nodes
 
 if False:
     # For type annotation
-    from typing import Any, Dict, List  # NOQA
-    from sphinx.builders import Builder  # NOQA
-    from sphinx.environment import BuildEnvironment  # NOQA
+    from sphinx.builders import Builder
+    from sphinx.environment import BuildEnvironment
+
 
 logger = logging.getLogger(__name__)
 
 
 class TocTree:
-    def __init__(self, env):
-        # type: (BuildEnvironment) -> None
+    def __init__(self, env: "BuildEnvironment") -> None:
         self.env = env
 
-    def note(self, docname, toctreenode):
-        # type: (str, addnodes.toctree) -> None
+    def note(self, docname: str, toctreenode: addnodes.toctree) -> None:
         """Note a TOC tree directive in a document and gather information about
         file relations from it.
         """
@@ -48,9 +48,9 @@ class TocTree:
             self.env.files_to_rebuild.setdefault(includefile, set()).add(docname)
         self.env.toctree_includes.setdefault(docname, []).extend(includefiles)
 
-    def resolve(self, docname, builder, toctree, prune=True, maxdepth=0,
-                titles_only=False, collapse=False, includehidden=False):
-        # type: (str, Builder, addnodes.toctree, bool, int, bool, bool, bool) -> nodes.Element
+    def resolve(self, docname: str, builder: "Builder", toctree: addnodes.toctree,
+                prune: bool = True, maxdepth: int = 0, titles_only: bool = False,
+                collapse: bool = False, includehidden: bool = False) -> Element:
         """Resolve a *toctree* node into individual bullet lists with titles
         as items, returning None (if no containing titles are found) or
         a new node.
@@ -86,8 +86,7 @@ class TocTree:
         toctree_ancestors = self.get_toctree_ancestors(docname)
         excluded = Matcher(self.env.config.exclude_patterns)
 
-        def _toctree_add_classes(node, depth):
-            # type: (nodes.Element, int) -> None
+        def _toctree_add_classes(node: Element, depth: int) -> None:
             """Add 'toctree-l%d' and 'current' classes to the toctree."""
             for subnode in node.children:
                 if isinstance(subnode, (addnodes.compact_paragraph,
@@ -105,7 +104,7 @@ class TocTree:
                         if not subnode['anchorname']:
                             # give the whole branch a 'current' class
                             # (useful for styling it differently)
-                            branchnode = subnode  # type: nodes.Element
+                            branchnode = subnode  # type: Element
                             while branchnode:
                                 branchnode['classes'].append('current')
                                 branchnode = branchnode.parent
@@ -117,11 +116,12 @@ class TocTree:
                             subnode['iscurrent'] = True
                             subnode = subnode.parent
 
-        def _entries_from_toctree(toctreenode, parents, separate=False, subtree=False):
-            # type: (addnodes.toctree, List[str], bool, bool) -> List[nodes.Element]
+        def _entries_from_toctree(toctreenode: addnodes.toctree, parents: List[str],
+                                  separate: bool = False, subtree: bool = False
+                                  ) -> List[Element]:
             """Return TOC entries for a toctree node."""
             refs = [(e[0], e[1]) for e in toctreenode['entries']]
-            entries = []  # type: List[nodes.Element]
+            entries = []  # type: List[Element]
             for (title, ref) in refs:
                 try:
                     refdoc = None
@@ -265,8 +265,7 @@ class TocTree:
                     docname, refnode['refuri']) + refnode['anchorname']
         return newnode
 
-    def get_toctree_ancestors(self, docname):
-        # type: (str) -> List[str]
+    def get_toctree_ancestors(self, docname: str) -> List[str]:
         parent = {}
         for p, children in self.env.toctree_includes.items():
             for child in children:
@@ -278,8 +277,8 @@ class TocTree:
             d = parent[d]
         return ancestors
 
-    def _toctree_prune(self, node, depth, maxdepth, collapse=False):
-        # type: (nodes.Element, int, int, bool) -> None
+    def _toctree_prune(self, node: Element, depth: int, maxdepth: int, collapse: bool = False
+                       ) -> None:
         """Utility: Cut a TOC at a specified depth."""
         for subnode in node.children[:]:
             if isinstance(subnode, (addnodes.compact_paragraph,
@@ -300,8 +299,7 @@ class TocTree:
                         # recurse on visible children
                         self._toctree_prune(subnode, depth + 1, maxdepth,  collapse)
 
-    def get_toc_for(self, docname, builder):
-        # type: (str, Builder) -> nodes.Node
+    def get_toc_for(self, docname: str, builder: "Builder") -> Node:
         """Return a TOC nodetree -- for use on the same page only!"""
         tocdepth = self.env.metadata[docname].get('tocdepth', 0)
         try:
@@ -316,11 +314,11 @@ class TocTree:
             node['refuri'] = node['anchorname'] or '#'
         return toc
 
-    def get_toctree_for(self, docname, builder, collapse, **kwds):
-        # type: (str, Builder, bool, Any) -> nodes.Element
+    def get_toctree_for(self, docname: str, builder: "Builder", collapse: bool, **kwds
+                        ) -> Element:
         """Return the global TOC nodetree."""
         doctree = self.env.get_doctree(self.env.config.master_doc)
-        toctrees = []  # type: List[nodes.Element]
+        toctrees = []  # type: List[Element]
         if 'includehidden' not in kwds:
             kwds['includehidden'] = True
         if 'maxdepth' not in kwds: