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

1 files changed, 26 insertions, 42 deletions

diff --git a/sphinx/environment/collectors/toctree.py b/sphinx/environment/collectors/toctree.py
index 53009c753..d1e211d2c 100644
--- a/sphinx/environment/collectors/toctree.py
+++ b/sphinx/environment/collectors/toctree.py
@@ -8,31 +8,29 @@
     :license: BSD, see LICENSE for details.
 """
 
+from typing import Any, Dict, List, Set, Tuple, Type, TypeVar
 from typing import cast
 
 from docutils import nodes
+from docutils.nodes import Element, Node
 
 from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.environment import BuildEnvironment
 from sphinx.environment.adapters.toctree import TocTree
 from sphinx.environment.collectors import EnvironmentCollector
 from sphinx.locale import __
 from sphinx.transforms import SphinxContentsFilter
 from sphinx.util import url_re, logging
 
-if False:
-    # For type annotation
-    from typing import Dict, List, Set, Tuple, Type, TypeVar  # NOQA
-    from sphinx.application import Sphinx  # NOQA
-    from sphinx.environment import BuildEnvironment  # NOQA
 
-    N = TypeVar('N')
+N = TypeVar('N')
 
 logger = logging.getLogger(__name__)
 
 
 class TocTreeCollector(EnvironmentCollector):
-    def clear_doc(self, app, env, docname):
-        # type: (Sphinx, BuildEnvironment, str) -> None
+    def clear_doc(self, app: Sphinx, env: BuildEnvironment, docname: str) -> None:
         env.tocs.pop(docname, None)
         env.toc_secnumbers.pop(docname, None)
         env.toc_fignumbers.pop(docname, None)
@@ -46,8 +44,8 @@ class TocTreeCollector(EnvironmentCollector):
             if not fnset:
                 del env.files_to_rebuild[subfn]
 
-    def merge_other(self, app, env, docnames, other):
-        # type: (Sphinx, BuildEnvironment, Set[str], BuildEnvironment) -> None
+    def merge_other(self, app: Sphinx, env: BuildEnvironment, docnames: Set[str],
+                    other: BuildEnvironment) -> None:
         for docname in docnames:
             env.tocs[docname] = other.tocs[docname]
             env.toc_num_entries[docname] = other.toc_num_entries[docname]
@@ -61,14 +59,12 @@ class TocTreeCollector(EnvironmentCollector):
         for subfn, fnset in other.files_to_rebuild.items():
             env.files_to_rebuild.setdefault(subfn, set()).update(fnset & set(docnames))
 
-    def process_doc(self, app, doctree):
-        # type: (Sphinx, nodes.document) -> None
+    def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
         """Build a TOC from the doctree and store it in the inventory."""
         docname = app.env.docname
         numentries = [0]  # nonlocal again...
 
-        def traverse_in_section(node, cls):
-            # type: (nodes.Element, Type[N]) -> List[N]
+        def traverse_in_section(node: Element, cls: Type[N]) -> List[N]:
             """Like traverse(), but stay within the same section."""
             result = []  # type: List[N]
             if isinstance(node, cls):
@@ -80,9 +76,8 @@ class TocTreeCollector(EnvironmentCollector):
                     result.extend(traverse_in_section(child, cls))
             return result
 
-        def build_toc(node, depth=1):
-            # type: (nodes.Element, int) -> nodes.bullet_list
-            entries = []  # type: List[nodes.Element]
+        def build_toc(node: Element, depth: int = 1) -> nodes.bullet_list:
+            entries = []  # type: List[Element]
             for sectionnode in node:
                 # find all toctree nodes in this section and add them
                 # to the toc (just copying the toctree node which is then
@@ -107,7 +102,7 @@ class TocTreeCollector(EnvironmentCollector):
                         '', '', internal=True, refuri=docname,
                         anchorname=anchorname, *nodetext)
                     para = addnodes.compact_paragraph('', '', reference)
-                    item = nodes.list_item('', para)  # type: nodes.Element
+                    item = nodes.list_item('', para)  # type: Element
                     sub_item = build_toc(sectionnode, depth + 1)
                     if sub_item:
                         item += sub_item
@@ -135,12 +130,10 @@ class TocTreeCollector(EnvironmentCollector):
             app.env.tocs[docname] = nodes.bullet_list('')
         app.env.toc_num_entries[docname] = numentries[0]
 
-    def get_updated_docs(self, app, env):
-        # type: (Sphinx, BuildEnvironment) -> List[str]
+    def get_updated_docs(self, app: Sphinx, env: BuildEnvironment) -> List[str]:
         return self.assign_section_numbers(env) + self.assign_figure_numbers(env)
 
-    def assign_section_numbers(self, env):
-        # type: (BuildEnvironment) -> List[str]
+    def assign_section_numbers(self, env: BuildEnvironment) -> List[str]:
         """Assign a section number to each heading under a numbered toctree."""
         # a list of all docnames whose section numbers changed
         rewrite_needed = []
@@ -149,8 +142,7 @@ class TocTreeCollector(EnvironmentCollector):
         old_secnumbers = env.toc_secnumbers
         env.toc_secnumbers = {}
 
-        def _walk_toc(node, secnums, depth, titlenode=None):
-            # type: (nodes.Element, Dict, int, nodes.title) -> None
+        def _walk_toc(node: Element, secnums: Dict, depth: int, titlenode: nodes.title = None) -> None:  # NOQA
             # titlenode is the title of the document, it will get assigned a
             # secnumber too, so that it shows up in next/prev/parent rellinks
             for subnode in node.children:
@@ -184,8 +176,7 @@ class TocTreeCollector(EnvironmentCollector):
                 elif isinstance(subnode, addnodes.toctree):
                     _walk_toctree(subnode, depth)
 
-        def _walk_toctree(toctreenode, depth):
-            # type: (addnodes.toctree, int) -> None
+        def _walk_toctree(toctreenode: addnodes.toctree, depth: int) -> None:
             if depth == 0:
                 return
             for (title, ref) in toctreenode['entries']:
@@ -216,8 +207,7 @@ class TocTreeCollector(EnvironmentCollector):
 
         return rewrite_needed
 
-    def assign_figure_numbers(self, env):
-        # type: (BuildEnvironment) -> List[str]
+    def assign_figure_numbers(self, env: BuildEnvironment) -> List[str]:
         """Assign a figure number to each figure under a numbered toctree."""
 
         rewrite_needed = []
@@ -227,8 +217,7 @@ class TocTreeCollector(EnvironmentCollector):
         env.toc_fignumbers = {}
         fignum_counter = {}  # type: Dict[str, Dict[Tuple[int, ...], int]]
 
-        def get_figtype(node):
-            # type: (nodes.Node) -> str
+        def get_figtype(node: Node) -> str:
             for domain in env.domains.values():
                 figtype = domain.get_enumerable_node_type(node)
                 if figtype:
@@ -236,8 +225,7 @@ class TocTreeCollector(EnvironmentCollector):
 
             return None
 
-        def get_section_number(docname, section):
-            # type: (str, nodes.section) -> Tuple[int, ...]
+        def get_section_number(docname: str, section: nodes.section) -> Tuple[int, ...]:
             anchorname = '#' + section['ids'][0]
             secnumbers = env.toc_secnumbers.get(docname, {})
             if anchorname in secnumbers:
@@ -247,24 +235,22 @@ class TocTreeCollector(EnvironmentCollector):
 
             return secnum or tuple()
 
-        def get_next_fignumber(figtype, secnum):
-            # type: (str, Tuple[int, ...]) -> Tuple[int, ...]
+        def get_next_fignumber(figtype: str, secnum: Tuple[int, ...]) -> Tuple[int, ...]:
             counter = fignum_counter.setdefault(figtype, {})
 
             secnum = secnum[:env.config.numfig_secnum_depth]
             counter[secnum] = counter.get(secnum, 0) + 1
             return secnum + (counter[secnum],)
 
-        def register_fignumber(docname, secnum, figtype, fignode):
-            # type: (str, Tuple[int, ...], str, nodes.Element) -> None
+        def register_fignumber(docname: str, secnum: Tuple[int, ...],
+                               figtype: str, fignode: Element) -> None:
             env.toc_fignumbers.setdefault(docname, {})
             fignumbers = env.toc_fignumbers[docname].setdefault(figtype, {})
             figure_id = fignode['ids'][0]
 
             fignumbers[figure_id] = get_next_fignumber(figtype, secnum)
 
-        def _walk_doctree(docname, doctree, secnum):
-            # type: (str, nodes.Element, Tuple[int, ...]) -> None
+        def _walk_doctree(docname: str, doctree: Element, secnum: Tuple[int, ...]) -> None:
             for subnode in doctree.children:
                 if isinstance(subnode, nodes.section):
                     next_secnum = get_section_number(docname, subnode)
@@ -286,8 +272,7 @@ class TocTreeCollector(EnvironmentCollector):
 
                     _walk_doctree(docname, subnode, secnum)
 
-        def _walk_doc(docname, secnum):
-            # type: (str, Tuple[int, ...]) -> None
+        def _walk_doc(docname: str, secnum: Tuple[int, ...]) -> None:
             if docname not in assigned:
                 assigned.add(docname)
                 doctree = env.get_doctree(docname)
@@ -302,8 +287,7 @@ class TocTreeCollector(EnvironmentCollector):
         return rewrite_needed
 
 
-def setup(app):
-    # type: (Sphinx) -> Dict
+def setup(app: Sphinx) -> Dict[str, Any]:
     app.add_env_collector(TocTreeCollector)
 
     return {