Merge pull request #9004 from tk0miya/refactor_vartypes_ext

refactor: Use PEP-526 based variable annotation (sphinx.ext)

sphinx/ext/apidoc.py

@@ -215,7 +215,7 @@ def walk(rootpath: str, excludes: List[str], opts: Any
         # remove hidden ('.') and private ('_') directories, as well as
         # excluded dirs
         if includeprivate:
-            exclude_prefixes = ('.',)  # type: Tuple[str, ...]
+            exclude_prefixes: Tuple[str, ...] = ('.',)
         else:
             exclude_prefixes = ('.', '_')
 

sphinx/ext/autodoc/__init__.py

@@ -325,28 +325,28 @@ class Documenter:
 
     def __init__(self, directive: "DocumenterBridge", name: str, indent: str = '') -> None:
         self.directive = directive
-        self.config = directive.env.config  # type: Config
+        self.config: Config = directive.env.config
-        self.env = directive.env    # type: BuildEnvironment
+        self.env: BuildEnvironment = directive.env
         self.options = directive.genopt
         self.name = name
         self.indent = indent
         # the module and object path within the module, and the fully
         # qualified name (all set after resolve_name succeeds)
-        self.modname = None         # type: str
+        self.modname: str = None
-        self.module = None          # type: ModuleType
+        self.module: ModuleType = None
-        self.objpath = None         # type: List[str]
+        self.objpath: List[str] = None
-        self.fullname = None        # type: str
+        self.fullname: str = None
         # extra signature items (arguments and return annotation,
         # also set after resolve_name succeeds)
-        self.args = None            # type: str
+        self.args: str = None
-        self.retann = None          # type: str
+        self.retann: str = None
         # the object to document (set after import_object succeeds)
-        self.object = None          # type: Any
+        self.object: Any = None
-        self.object_name = None     # type: str
+        self.object_name: str = None
         # the parent/owner of the object to document
-        self.parent = None          # type: Any
+        self.parent: Any = None
         # the module analyzer to get at attribute docs, or None
-        self.analyzer = None        # type: ModuleAnalyzer
+        self.analyzer: ModuleAnalyzer = None
 
     @property
     def documenters(self) -> Dict[str, Type["Documenter"]]:
@@ -822,7 +822,7 @@ class Documenter:
         members_check_module, members = self.get_object_members(want_all)
 
         # document non-skipped members
-        memberdocumenters = []  # type: List[Tuple[Documenter, bool]]
+        memberdocumenters: List[Tuple[Documenter, bool]] = []
         for (mname, member, isattr) in self.filter_members(members, want_all):
             classes = [cls for cls in self.documenters.values()
                        if cls.can_document_member(member, mname, isattr, self)]
@@ -904,7 +904,7 @@ class Documenter:
         # This is used for situations where you have a module that collects the
         # functions and classes of internal submodules.
         guess_modname = self.get_real_modname()
-        self.real_modname = real_modname or guess_modname  # type: str
+        self.real_modname: str = real_modname or guess_modname
 
         # try to also get a source code analyzer for attribute docs
         try:
@@ -985,7 +985,7 @@ class ModuleDocumenter(Documenter):
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
         merge_members_option(self.options)
-        self.__all__ = None  # type: Optional[Sequence[str]]
+        self.__all__: Optional[Sequence[str]] = None
 
     @classmethod
     def can_document_member(cls, member: Any, membername: str, isattr: bool, parent: Any
@@ -1042,7 +1042,7 @@ class ModuleDocumenter(Documenter):
         else:
             attr_docs = {}
 
-        members = {}  # type: Dict[str, ObjectMember]
+        members: Dict[str, ObjectMember] = {}
         for name in dir(self.object):
             try:
                 value = safe_getattr(self.object, name, None)
@@ -1167,8 +1167,8 @@ class DocstringSignatureMixin:
     Mixin for FunctionDocumenter and MethodDocumenter to provide the
     feature of reading the signature from the docstring.
     """
-    _new_docstrings = None  # type: List[List[str]]
+    _new_docstrings: List[List[str]] = None
-    _signatures = None      # type: List[str]
+    _signatures: List[str] = None
 
     def _find_signature(self) -> Tuple[str, str]:
         # candidates of the object name
@@ -1429,8 +1429,8 @@ class ClassDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):  # type:
         'private-members': members_option, 'special-members': members_option,
     }
 
-    _signature_class = None  # type: Any
+    _signature_class: Any = None
-    _signature_method_name = None  # type: str
+    _signature_method_name: str = None
 
     def __init__(self, *args: Any) -> None:
         super().__init__(*args)
@@ -1727,12 +1727,12 @@ class ExceptionDocumenter(ClassDocumenter):
 
 class DataDocumenterMixinBase:
     # define types of instance variables
-    config = None  # type: Config
+    config: Config = None
-    env = None  # type: BuildEnvironment
+    env: BuildEnvironment = None
-    modname = None  # type: str
+    modname: str = None
-    parent = None  # type: Any
+    parent: Any = None
-    object = None  # type: Any
+    object: Any = None
-    objpath = None  # type: List[str]
+    objpath: List[str] = None
 
     def should_suppress_directive_header(self) -> bool:
         """Check directive header should be suppressed."""

sphinx/ext/autodoc/directive.py

@@ -56,7 +56,7 @@ class DocumenterBridge:
         self._reporter = reporter
         self.genopt = options
         self.lineno = lineno
-        self.filename_set = set()  # type: Set[str]
+        self.filename_set: Set[str] = set()
         self.result = StringList()
         self.state = state
 
@@ -101,7 +101,7 @@ def parse_generated_content(state: RSTState, content: StringList, documenter: Do
     """Parse a generated content by Documenter."""
     with switch_source_input(state, content):
         if documenter.titles_allowed:
-            node = nodes.section()  # type: Element
+            node: Element = nodes.section()
             # necessary so that the child nodes get the right source/line set
             node.document = state.document
             nested_parse_with_titles(state, content, node)

sphinx/ext/autodoc/importer.py

@@ -147,7 +147,7 @@ def get_module_members(module: Any) -> List[Tuple[str, Any]]:
     warnings.warn('sphinx.ext.autodoc.importer.get_module_members() is deprecated.',
                   RemovedInSphinx50Warning)
 
-    members = {}  # type: Dict[str, Tuple[str, Any]]
+    members: Dict[str, Tuple[str, Any]] = {}
     for name in dir(module):
         try:
             value = safe_getattr(module, name, None)
@@ -177,7 +177,7 @@ def get_object_members(subject: Any, objpath: List[str], attrgetter: Callable,
     # the members directly defined in the class
     obj_dict = attrgetter(subject, '__dict__', {})
 
-    members = {}  # type: Dict[str, Attribute]
+    members: Dict[str, Attribute] = {}
 
     # enum members
     if isenumclass(subject):
@@ -238,7 +238,7 @@ def get_class_members(subject: Any, objpath: List[str], attrgetter: Callable
     # the members directly defined in the class
     obj_dict = attrgetter(subject, '__dict__', {})
 
-    members = {}  # type: Dict[str, ObjectMember]
+    members: Dict[str, ObjectMember] = {}
 
     # enum members
     if isenumclass(subject):

sphinx/ext/autodoc/mock.py

@@ -27,7 +27,7 @@ class _MockObject:
 
     __display_name__ = '_MockObject'
     __sphinx_mock__ = True
-    __sphinx_decorator_args__ = ()  # type: Tuple[Any, ...]
+    __sphinx_decorator_args__: Tuple[Any, ...] = ()
 
     def __new__(cls, *args: Any, **kwargs: Any) -> Any:
         if len(args) == 3 and isinstance(args[1], tuple):
@@ -86,8 +86,8 @@ class _MockModule(ModuleType):
 
     def __init__(self, name: str) -> None:
         super().__init__(name)
-        self.__all__ = []  # type: List[str]
+        self.__all__: List[str] = []
-        self.__path__ = []  # type: List[str]
+        self.__path__: List[str] = []
 
     def __getattr__(self, name: str) -> _MockObject:
         return _make_subclass(name, self.__name__)()
@@ -118,7 +118,7 @@ class MockFinder(MetaPathFinder):
         super().__init__()
         self.modnames = modnames
         self.loader = MockLoader(self)
-        self.mocked_modules = []  # type: List[str]
+        self.mocked_modules: List[str] = []
 
     def find_spec(self, fullname: str, path: Optional[Sequence[Union[bytes, str]]],
                   target: ModuleType = None) -> Optional[ModuleSpec]:

sphinx/ext/autodoc/typehints.py

@@ -80,7 +80,7 @@ def insert_field_list(node: Element) -> nodes.field_list:
 
 
 def modify_field_list(node: nodes.field_list, annotations: Dict[str, str]) -> None:
-    arguments = {}  # type: Dict[str, Dict[str, bool]]
+    arguments: Dict[str, Dict[str, bool]] = {}
     fields = cast(Iterable[nodes.field], node)
     for field in fields:
         field_name = field[0].astext()

sphinx/ext/autosummary/generate.py

@@ -59,7 +59,7 @@ class DummyApplication:
     def __init__(self, translator: NullTranslations) -> None:
         self.config = Config()
         self.registry = SphinxComponentRegistry()
-        self.messagelog = []  # type: List[str]
+        self.messagelog: List[str] = []
         self.srcdir = "/"
         self.translator = translator
         self.verbosity = 0

sphinx/ext/coverage.py

@@ -53,19 +53,19 @@ class CoverageBuilder(Builder):
                 'results in %(outdir)s' + path.sep + 'python.txt.')
 
     def init(self) -> None:
-        self.c_sourcefiles = []  # type: List[str]
+        self.c_sourcefiles: List[str] = []
         for pattern in self.config.coverage_c_path:
             pattern = path.join(self.srcdir, pattern)
             self.c_sourcefiles.extend(glob.glob(pattern))
 
-        self.c_regexes = []  # type: List[Tuple[str, Pattern]]
+        self.c_regexes: List[Tuple[str, Pattern]] = []
         for (name, exp) in self.config.coverage_c_regexes.items():
             try:
                 self.c_regexes.append((name, re.compile(exp)))
             except Exception:
                 logger.warning(__('invalid regex %r in coverage_c_regexes'), exp)
 
-        self.c_ignorexps = {}  # type: Dict[str, List[Pattern]]
+        self.c_ignorexps: Dict[str, List[Pattern]] = {}
         for (name, exps) in self.config.coverage_ignore_c_items.items():
             self.c_ignorexps[name] = compile_regex_list('coverage_ignore_c_items',
                                                         exps)
@@ -82,11 +82,11 @@ class CoverageBuilder(Builder):
         return 'coverage overview'
 
     def write(self, *ignored: Any) -> None:
-        self.py_undoc = {}  # type: Dict[str, Dict[str, Any]]
+        self.py_undoc: Dict[str, Dict[str, Any]] = {}
         self.build_py_coverage()
         self.write_py_coverage()
 
-        self.c_undoc = {}  # type: Dict[str, Set[Tuple[str, str]]]
+        self.c_undoc: Dict[str, Set[Tuple[str, str]]] = {}
         self.build_c_coverage()
         self.write_c_coverage()
 
@@ -94,7 +94,7 @@ class CoverageBuilder(Builder):
         # Fetch all the info from the header files
         c_objects = self.env.domaindata['c']['objects']
         for filename in self.c_sourcefiles:
-            undoc = set()  # type: Set[Tuple[str, str]]
+            undoc: Set[Tuple[str, str]] = set()
             with open(filename) as f:
                 for line in f:
                     for key, regex in self.c_regexes:
@@ -161,7 +161,7 @@ class CoverageBuilder(Builder):
                 continue
 
             funcs = []
-            classes = {}  # type: Dict[str, List[str]]
+            classes: Dict[str, List[str]] = {}
 
             for name, obj in inspect.getmembers(mod):
                 # diverse module attributes are ignored:
@@ -200,7 +200,7 @@ class CoverageBuilder(Builder):
                             classes[name] = []
                             continue
 
-                        attrs = []  # type: List[str]
+                        attrs: List[str] = []
 
                         for attr_name in dir(obj):
                             if attr_name not in obj.__dict__:

sphinx/ext/graphviz.py

@@ -50,10 +50,10 @@ class ClickableMapDefinition:
     href_re = re.compile('href=".*?"')
 
     def __init__(self, filename: str, content: str, dot: str = '') -> None:
-        self.id = None  # type: str
+        self.id: str = None
         self.filename = filename
         self.content = content.splitlines()
-        self.clickable = []  # type: List[str]
+        self.clickable: List[str] = []
 
         self.parse(dot=dot)
 

sphinx/ext/inheritance_diagram.py

@@ -155,7 +155,7 @@ class InheritanceGraph:
 
     def _import_classes(self, class_names: List[str], currmodule: str) -> List[Any]:
         """Import a list of classes."""
-        classes = []  # type: List[Any]
+        classes: List[Any] = []
         for name in class_names:
             classes.extend(import_classes(name, currmodule))
         return classes
@@ -199,7 +199,7 @@ class InheritanceGraph:
             except Exception:  # might raise AttributeError for strange classes
                 pass
 
-            baselist = []  # type: List[str]
+            baselist: List[str] = []
             all_classes[cls] = (nodename, fullname, baselist, tooltip)
 
             if fullname in top_classes:
@@ -293,7 +293,7 @@ class InheritanceGraph:
             n_attrs.update(env.config.inheritance_node_attrs)
             e_attrs.update(env.config.inheritance_edge_attrs)
 
-        res = []  # type: List[str]
+        res: List[str] = []
         res.append('digraph %s {\n' % name)
         res.append(self._format_graph_attrs(g_attrs))
 

sphinx/ext/intersphinx.py

@@ -264,7 +264,7 @@ def missing_reference(app: Sphinx, env: BuildEnvironment, node: pending_xref,
     """Attempt to resolve a missing reference via intersphinx references."""
     target = node['reftarget']
     inventories = InventoryAdapter(env)
-    objtypes = None  # type: List[str]
+    objtypes: List[str] = None
     if node['reftype'] == 'any':
         # we search anything!
         objtypes = ['%s:%s' % (domain.name, objtype)
@@ -398,7 +398,7 @@ def inspect_main(argv: List[str]) -> None:
         sys.exit(1)
 
     class MockConfig:
-        intersphinx_timeout = None  # type: int
+        intersphinx_timeout: int = None
         tls_verify = False
         user_agent = None
 

sphinx/ext/linkcode.py

@@ -41,7 +41,7 @@ def doctree_read(app: Sphinx, doctree: Node) -> None:
 
     for objnode in doctree.traverse(addnodes.desc):
         domain = objnode.get('domain')
-        uris = set()  # type: Set[str]
+        uris: Set[str] = set()
         for signode in objnode:
             if not isinstance(signode, addnodes.desc_signature):
                 continue

sphinx/ext/napoleon/__init__.py

@@ -388,7 +388,7 @@ def _process_docstring(app: Sphinx, what: str, name: str, obj: Any,
 
     """
     result_lines = lines
-    docstring = None  # type: GoogleDocstring
+    docstring: GoogleDocstring = None
     if app.config.napoleon_numpy_docstring:
         docstring = NumpyDocstring(result_lines, app.config, app, what, name,
                                    obj, options)

sphinx/ext/napoleon/docstring.py

@@ -162,13 +162,13 @@ class GoogleDocstring:
         else:
             lines = docstring
         self._line_iter = modify_iter(lines, modifier=lambda s: s.rstrip())
-        self._parsed_lines = []  # type: List[str]
+        self._parsed_lines: List[str] = []
         self._is_in_section = False
         self._section_indent = 0
         if not hasattr(self, '_directive_sections'):
-            self._directive_sections = []  # type: List[str]
+            self._directive_sections: List[str] = []
         if not hasattr(self, '_sections'):
-            self._sections = {
+            self._sections: Dict[str, Callable] = {
                 'args': self._parse_parameters_section,
                 'arguments': self._parse_parameters_section,
                 'attention': partial(self._parse_admonition, 'attention'),
@@ -203,7 +203,7 @@ class GoogleDocstring:
                 'warns': self._parse_warns_section,
                 'yield': self._parse_yields_section,
                 'yields': self._parse_yields_section,
-            }  # type: Dict[str, Callable]
+            }
 
         self._load_custom_sections()
 
@@ -461,7 +461,7 @@ class GoogleDocstring:
         field_type = ':%s:' % field_type.strip()
         padding = ' ' * len(field_type)
         multi = len(fields) > 1
-        lines = []  # type: List[str]
+        lines: List[str] = []
         for _name, _type, _desc in fields:
             field = self._format_field(_name, _type, _desc)
             if multi:
@@ -585,7 +585,7 @@ class GoogleDocstring:
         if self._name and self._what in ('attribute', 'data', 'property'):
             # Implicit stop using StopIteration no longer allowed in
             # Python 3.7; see PEP 479
-            res = []  # type: List[str]
+            res: List[str] = []
             try:
                 res = self._parse_attribute_docstring()
             except StopIteration:
@@ -703,7 +703,7 @@ class GoogleDocstring:
             return self._format_fields(_('Keyword Arguments'), fields)
 
     def _parse_methods_section(self, section: str) -> List[str]:
-        lines = []  # type: List[str]
+        lines: List[str] = []
         for _name, _type, _desc in self._consume_fields(parse_type=False):
             lines.append('.. method:: %s' % _name)
             if self._opt and 'noindex' in self._opt:
@@ -737,7 +737,7 @@ class GoogleDocstring:
 
     def _parse_raises_section(self, section: str) -> List[str]:
         fields = self._consume_fields(parse_type=False, prefer_type=True)
-        lines = []  # type: List[str]
+        lines: List[str] = []
         for _name, _type, _desc in fields:
             m = self._name_rgx.match(_type)
             if m and m.group('name'):
@@ -774,7 +774,7 @@ class GoogleDocstring:
         else:
             use_rtype = self._config.napoleon_use_rtype
 
-        lines = []  # type: List[str]
+        lines: List[str] = []
         for _name, _type, _desc in fields:
             if use_rtype:
                 field = self._format_field(_name, '', _desc)
@@ -1281,7 +1281,7 @@ class NumpyDocstring(GoogleDocstring):
             return new_func, description, role
 
         current_func = None
-        rest = []  # type: List[str]
+        rest: List[str] = []
 
         for line in content:
             if not line.strip():
@@ -1316,7 +1316,7 @@ class NumpyDocstring(GoogleDocstring):
             for func, description, role in items
         ]
 
-        lines = []  # type: List[str]
+        lines: List[str] = []
         last_had_desc = True
         for name, desc, role in items:
             if role:

sphinx/ext/napoleon/iterators.py

@@ -49,8 +49,8 @@ class peek_iter:
     """
     def __init__(self, *args: Any) -> None:
         """__init__(o, sentinel=None)"""
-        self._iterable = iter(*args)        # type: Iterable
+        self._iterable: Iterable = iter(*args)
-        self._cache = collections.deque()   # type: collections.deque
+        self._cache: collections.deque = collections.deque()
         if len(args) == 2:
             self.sentinel = args[1]
         else: