Merge pull request #6957 from tk0miya/refactor_type_annotation4

Migrate to py3 style type annotation: util, transforms and versioning

sphinx/transforms/__init__.py

@@ -273,8 +273,7 @@ class DoctestTransform(SphinxTransform):
     """Set "doctest" style to each doctest_block node"""
     default_priority = 500
 
-    def apply(self, **kwargs):
+    def apply(self, **kwargs) -> None:
-        # type: (Any) -> None
         for node in self.document.traverse(nodes.doctest_block):
             node['classes'].append('doctest')
 

sphinx/util/__init__.py

@@ -122,8 +122,7 @@ def get_matching_docs(dirname: str, suffixes: List[str],
                 break
 
 
-def get_filetype(source_suffix, filename):
+def get_filetype(source_suffix: Dict[str, str], filename: str) -> str:
-    # type: (Dict[str, str], str) -> str
     for suffix, filetype in source_suffix.items():
         if filename.endswith(suffix):
             # If default filetype (None), considered as restructuredtext.

sphinx/versioning.py

@@ -13,16 +13,18 @@ import warnings
 from itertools import product, zip_longest
 from operator import itemgetter
 from os import path
+from typing import Any, Dict, Iterator
 from uuid import uuid4
 
+from docutils import nodes
+from docutils.nodes import Node
+
 from sphinx.deprecation import RemovedInSphinx30Warning
 from sphinx.transforms import SphinxTransform
 
 if False:
     # For type annotation
-    from typing import Any, Dict, Iterator  # NOQA
+    from sphinx.application import Sphinx
-    from docutils import nodes  # NOQA
-    from sphinx.application import Sphinx  # NOQA
 
 try:
     import Levenshtein
@@ -34,8 +36,7 @@ except ImportError:
 VERSIONING_RATIO = 65
 
 
-def add_uids(doctree, condition):
+def add_uids(doctree: Node, condition: Any) -> Iterator[Node]:
-    # type: (nodes.Node, Any) -> Iterator[nodes.Node]
     """Add a unique id to every node in the `doctree` which matches the
     condition and yield the nodes.
 
@@ -50,8 +51,7 @@ def add_uids(doctree, condition):
         yield node
 
 
-def merge_doctrees(old, new, condition):
+def merge_doctrees(old: Node, new: Node, condition: Any) -> Iterator[Node]:
-    # type: (nodes.Node, nodes.Node, Any) -> Iterator[nodes.Node]
     """Merge the `old` doctree with the `new` one while looking at nodes
     matching the `condition`.
 
@@ -118,8 +118,7 @@ def merge_doctrees(old, new, condition):
         yield new_node
 
 
-def get_ratio(old, new):
+def get_ratio(old: str, new: str) -> float:
-    # type: (str, str) -> float
     """Return a "similiarity ratio" (in percent) representing the similarity
     between the two strings where 0 is equal and anything above less than equal.
     """
@@ -132,8 +131,7 @@ def get_ratio(old, new):
         return levenshtein_distance(old, new) / (len(old) / 100.0)
 
 
-def levenshtein_distance(a, b):
+def levenshtein_distance(a: str, b: str) -> int:
-    # type: (str, str) -> int
     """Return the Levenshtein edit distance between two strings *a* and *b*."""
     if a == b:
         return 0
@@ -157,8 +155,7 @@ class UIDTransform(SphinxTransform):
     """Add UIDs to doctree for versioning."""
     default_priority = 880
 
-    def apply(self, **kwargs):
+    def apply(self, **kwargs) -> None:
-        # type: (Any) -> None
         env = self.env
         old_doctree = None
         if not env.versioning_condition:
@@ -180,8 +177,7 @@ class UIDTransform(SphinxTransform):
             list(merge_doctrees(old_doctree, self.document, env.versioning_condition))
 
 
-def prepare(document):
+def prepare(document: nodes.document) -> None:
-    # type: (nodes.document) -> None
     """Simple wrapper for UIDTransform."""
     warnings.warn('versioning.prepare() is deprecated. Use UIDTransform instead.',
                   RemovedInSphinx30Warning, stacklevel=2)
@@ -189,8 +185,7 @@ def prepare(document):
     transform.apply()
 
 
-def setup(app):
+def setup(app: "Sphinx") -> Dict[str, Any]:
-    # type: (Sphinx) -> Dict[str, Any]
     app.add_transform(UIDTransform)
 
     return {