Merge pull request sphinx-doc#9183 from tk0miya/refactor_Optional2

refactor: Add Optional to type annotations

sphinx/application.py

@@ -141,9 +141,9 @@ def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir:
         self.phase = BuildPhase.INITIALIZATION
         self.verbosity = verbosity
         self.extensions: Dict[str, Extension] = {}
-        self.builder: Builder = None
-        self.env: BuildEnvironment = None
-        self.project: Project = None
+        self.builder: Optional[Builder] = None
+        self.env: Optional[BuildEnvironment] = None
+        self.project: Optional[Project] = None
         self.registry = SphinxComponentRegistry()
         self.html_themes: Dict[str, str] = {}
 
@@ -174,7 +174,7 @@ def __init__(self, srcdir: str, confdir: Optional[str], outdir: str, doctreedir:
 
         if status is None:
             self._status: IO = StringIO()
-            self.quiet = True
+            self.quiet: bool = True
         else:
             self._status = status
             self.quiet = False

sphinx/builders/__init__.py

@@ -11,7 +11,8 @@
 import pickle
 import time
 from os import path
-from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Sequence, Set, Tuple, Type, Union
+from typing import (TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Sequence, Set, Tuple,
+                    Type, Union)
 
 from docutils import nodes
 from docutils.nodes import Node
@@ -88,7 +89,7 @@ def __init__(self, app: "Sphinx") -> None:
         ensuredir(self.doctreedir)
 
         self.app: Sphinx = app
-        self.env: BuildEnvironment = None
+        self.env: Optional[BuildEnvironment] = None
         self.events: EventManager = app.events
         self.config: Config = app.config
         self.tags: Tags = app.tags
@@ -225,7 +226,7 @@ def compile_all_catalogs(self) -> None:
         self.compile_catalogs(set(repo.catalogs), message)
 
     def compile_specific_catalogs(self, specified_files: List[str]) -> None:
-        def to_domain(fpath: str) -> str:
+        def to_domain(fpath: str) -> Optional[str]:
             docname = self.env.path2doc(path.abspath(fpath))
             if docname:
                 return docname_to_domain(docname, self.config.gettext_compact)

sphinx/domains/__init__.py

@@ -11,8 +11,8 @@
 
 import copy
 from abc import ABC, abstractmethod
-from typing import (TYPE_CHECKING, Any, Callable, Dict, Iterable, List, NamedTuple, Tuple,
-                    Type, Union, cast)
+from typing import (TYPE_CHECKING, Any, Callable, Dict, Iterable, List, NamedTuple, Optional,
+                    Tuple, Type, Union, cast)
 
 from docutils import nodes
 from docutils.nodes import Element, Node, system_message
@@ -196,7 +196,7 @@ class Domain:
     #: data value for a fresh environment
     initial_data: Dict = {}
     #: data value
-    data: Dict = None
+    data: Dict
     #: data version, bump this when the format of `self.data` changes
     data_version = 0
 
@@ -251,7 +251,7 @@ def add_object_type(self, name: str, objtype: ObjType) -> None:
         for role in objtype.roles:
             self._role2type.setdefault(role, []).append(name)
 
-    def role(self, name: str) -> RoleFunction:
+    def role(self, name: str) -> Optional[RoleFunction]:
         """Return a role adapter function that always gives the registered
         role its full name ('domain:name') as the first argument.
         """
@@ -269,7 +269,7 @@ def role_adapter(typ: str, rawtext: str, text: str, lineno: int,
         self._role_cache[name] = role_adapter
         return role_adapter
 
-    def directive(self, name: str) -> Callable:
+    def directive(self, name: str) -> Optional[Callable]:
         """Return a directive adapter class that always gives the registered
         directive its full name ('domain:name') as ``self.name``.
         """
@@ -318,7 +318,7 @@ def process_field_xref(self, pnode: pending_xref) -> None:
 
     def resolve_xref(self, env: "BuildEnvironment", fromdocname: str, builder: "Builder",
                      typ: str, target: str, node: pending_xref, contnode: Element
-                     ) -> Element:
+                     ) -> Optional[Element]:
         """Resolve the pending_xref *node* with the given *typ* and *target*.
 
         This method should return a new node, to replace the xref node,
@@ -393,11 +393,11 @@ def get_type_name(self, type: ObjType, primary: bool = False) -> str:
             return type.lname
         return _('%s %s') % (self.label, type.lname)
 
-    def get_enumerable_node_type(self, node: Node) -> str:
+    def get_enumerable_node_type(self, node: Node) -> Optional[str]:
         """Get type of enumerable nodes (experimental)."""
         enum_node_type, _ = self.enumerable_nodes.get(node.__class__, (None, None))
         return enum_node_type
 
-    def get_full_qualified_name(self, node: Element) -> str:
+    def get_full_qualified_name(self, node: Element) -> Optional[str]:
         """Return full qualified name for given node."""
         return None

sphinx/domains/c.py

@@ -9,7 +9,8 @@
 """
 
 import re
-from typing import Any, Callable, Dict, Generator, Iterator, List, Tuple, TypeVar, Union, cast
+from typing import (Any, Callable, Dict, Generator, Iterator, List, Optional, Tuple, TypeVar,
+                    Union, cast)
 
 from docutils import nodes
 from docutils.nodes import Element, Node, TextElement, system_message
@@ -3807,7 +3808,7 @@ def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None:
 
     def _resolve_xref_inner(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
                             typ: str, target: str, node: pending_xref,
-                            contnode: Element) -> Tuple[Element, str]:
+                            contnode: Element) -> Tuple[Optional[Element], Optional[str]]:
         parser = DefinitionParser(target, location=node, config=env.config)
         try:
             name = parser.parse_xref_object()
@@ -3844,7 +3845,7 @@ def _resolve_xref_inner(self, env: BuildEnvironment, fromdocname: str, builder:
 
     def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
                      typ: str, target: str, node: pending_xref,
-                     contnode: Element) -> Element:
+                     contnode: Element) -> Optional[Element]:
         return self._resolve_xref_inner(env, fromdocname, builder, typ,
                                         target, node, contnode)[0]
 

sphinx/domains/citation.py

@@ -8,7 +8,7 @@
     :license: BSD, see LICENSE for details.
 """
 
-from typing import TYPE_CHECKING, Any, Dict, List, Set, Tuple, cast
+from typing import TYPE_CHECKING, Any, Dict, List, Optional, Set, Tuple, cast
 
 from docutils import nodes
 from docutils.nodes import Element
@@ -88,7 +88,7 @@ def check_consistency(self) -> None:
 
     def resolve_xref(self, env: "BuildEnvironment", fromdocname: str, builder: "Builder",
                      typ: str, target: str, node: pending_xref, contnode: Element
-                     ) -> Element:
+                     ) -> Optional[Element]:
         docname, labelid, lineno = self.citations.get(target, ('', '', 0))
         if not docname:
             return None

sphinx/domains/cpp.py

@@ -7594,7 +7594,7 @@ def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None:
 
     def _resolve_xref_inner(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
                             typ: str, target: str, node: pending_xref,
-                            contnode: Element) -> Tuple[Element, str]:
+                            contnode: Element) -> Tuple[Optional[Element], Optional[str]]:
         # add parens again for those that could be functions
         if typ == 'any' or typ == 'func':
             target += '()'
@@ -7743,7 +7743,7 @@ def checkType() -> bool:
 
     def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
                      typ: str, target: str, node: pending_xref, contnode: Element
-                     ) -> Element:
+                     ) -> Optional[Element]:
         return self._resolve_xref_inner(env, fromdocname, builder, typ,
                                         target, node, contnode)[0]
 

sphinx/domains/javascript.py

@@ -8,7 +8,7 @@
     :license: BSD, see LICENSE for details.
 """
 
-from typing import Any, Dict, Iterator, List, Tuple, cast
+from typing import Any, Dict, Iterator, List, Optional, Tuple, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -413,7 +413,7 @@ def find_obj(self, env: BuildEnvironment, mod_name: str, prefix: str, name: str,
 
     def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
                      typ: str, target: str, node: pending_xref, contnode: Element
-                     ) -> Element:
+                     ) -> Optional[Element]:
         mod_name = node.get('js:module')
         prefix = node.get('js:object')
         searchorder = 1 if node.hasattr('refspecific') else 0

sphinx/domains/math.py

@@ -8,7 +8,7 @@
     :license: BSD, see LICENSE for details.
 """
 
-from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Tuple
+from typing import TYPE_CHECKING, Any, Dict, Iterable, List, Optional, Tuple
 
 from docutils import nodes
 from docutils.nodes import Element, Node, make_id, system_message
@@ -97,7 +97,7 @@ def merge_domaindata(self, docnames: Iterable[str], otherdata: Dict) -> None:
 
     def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: "Builder",
                      typ: str, target: str, node: pending_xref, contnode: Element
-                     ) -> Element:
+                     ) -> Optional[Element]:
         assert typ in ('eq', 'numref')
         docname, number = self.equations.get(target, (None, None))
         if docname:

sphinx/domains/python.py

@@ -15,7 +15,7 @@
 import typing
 import warnings
 from inspect import Parameter
-from typing import Any, Dict, Iterable, Iterator, List, NamedTuple, Tuple, Type, cast
+from typing import Any, Dict, Iterable, Iterator, List, NamedTuple, Optional, Tuple, Type, cast
 
 from docutils import nodes
 from docutils.nodes import Element, Node
@@ -1246,7 +1246,7 @@ def find_obj(self, env: BuildEnvironment, modname: str, classname: str,
 
     def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
                      type: str, target: str, node: pending_xref, contnode: Element
-                     ) -> Element:
+                     ) -> Optional[Element]:
         modname = node.get('py:module')
         clsname = node.get('py:class')
         searchmode = 1 if node.hasattr('refspecific') else 0
@@ -1340,7 +1340,7 @@ def get_objects(self) -> Iterator[Tuple[str, str, str, str, str, int]]:
                 else:
                     yield (refname, refname, obj.objtype, obj.docname, obj.node_id, 1)
 
-    def get_full_qualified_name(self, node: Element) -> str:
+    def get_full_qualified_name(self, node: Element) -> Optional[str]:
         modname = node.get('py:module')
         clsname = node.get('py:class')
         target = node.get('reftarget')

sphinx/domains/rst.py

@@ -9,7 +9,7 @@
 """
 
 import re
-from typing import Any, Dict, Iterator, List, Tuple, cast
+from typing import Any, Dict, Iterator, List, Optional, Tuple, cast
 
 from docutils.nodes import Element
 from docutils.parsers.rst import directives
@@ -247,7 +247,7 @@ def merge_domaindata(self, docnames: List[str], otherdata: Dict) -> None:
 
     def resolve_xref(self, env: BuildEnvironment, fromdocname: str, builder: Builder,
                      typ: str, target: str, node: pending_xref, contnode: Element
-                     ) -> Element:
+                     ) -> Optional[Element]:
         objtypes = self.objtypes_for_role(typ)
         for objtype in objtypes:
             todocname, node_id = self.objects.get((objtype, target), (None, None))

sphinx/domains/std.py

@@ -285,7 +285,7 @@ def process_link(self, env: "BuildEnvironment", refnode: Element, has_explicit_t
 
 def split_term_classifiers(line: str) -> List[Optional[str]]:
     # split line into a term and classifiers. if no classifier, None is used..
-    parts = re.split(' +: +', line) + [None]
+    parts: List[Optional[str]] = re.split(' +: +', line) + [None]
     return parts
 
 
@@ -621,7 +621,7 @@ class StandardDomain(Domain):
     }
 
     # node_class -> (figtype, title_getter)
-    enumerable_nodes: Dict[Type[Node], Tuple[str, Callable]] = {
+    enumerable_nodes: Dict[Type[Node], Tuple[str, Optional[Callable]]] = {
         nodes.figure: ('figure', None),
         nodes.table: ('table', None),
         nodes.container: ('code-block', None),
@@ -812,7 +812,8 @@ def build_reference_node(self, fromdocname: str, builder: "Builder", docname: st
         return newnode
 
     def resolve_xref(self, env: "BuildEnvironment", fromdocname: str, builder: "Builder",
-                     typ: str, target: str, node: pending_xref, contnode: Element) -> Element:
+                     typ: str, target: str, node: pending_xref, contnode: Element
+                     ) -> Optional[Element]:
         if typ == 'ref':
             resolver = self._resolve_ref_xref
         elif typ == 'numref':
@@ -832,7 +833,7 @@ def resolve_xref(self, env: "BuildEnvironment", fromdocname: str, builder: "Buil
 
     def _resolve_ref_xref(self, env: "BuildEnvironment", fromdocname: str,
                           builder: "Builder", typ: str, target: str, node: pending_xref,
-                          contnode: Element) -> Element:
+                          contnode: Element) -> Optional[Element]:
         if node['refexplicit']:
             # reference to anonymous label; the reference uses
             # the supplied link caption
@@ -850,7 +851,7 @@ def _resolve_ref_xref(self, env: "BuildEnvironment", fromdocname: str,
 
     def _resolve_numref_xref(self, env: "BuildEnvironment", fromdocname: str,
                              builder: "Builder", typ: str, target: str,
-                             node: pending_xref, contnode: Element) -> Element:
+                             node: pending_xref, contnode: Element) -> Optional[Element]:
         if target in self.labels:
             docname, labelid, figname = self.labels.get(target, ('', '', ''))
         else:
@@ -913,7 +914,7 @@ def _resolve_numref_xref(self, env: "BuildEnvironment", fromdocname: str,
 
     def _resolve_keyword_xref(self, env: "BuildEnvironment", fromdocname: str,
                               builder: "Builder", typ: str, target: str,
-                              node: pending_xref, contnode: Element) -> Element:
+                              node: pending_xref, contnode: Element) -> Optional[Element]:
         # keywords are oddballs: they are referenced by named labels
         docname, labelid, _ = self.labels.get(target, ('', '', ''))
         if not docname:
@@ -923,7 +924,7 @@ def _resolve_keyword_xref(self, env: "BuildEnvironment", fromdocname: str,
 
     def _resolve_doc_xref(self, env: "BuildEnvironment", fromdocname: str,
                           builder: "Builder", typ: str, target: str,
-                          node: pending_xref, contnode: Element) -> Element:
+                          node: pending_xref, contnode: Element) -> Optional[Element]:
         # directly reference to document by source name; can be absolute or relative
         refdoc = node.get('refdoc', fromdocname)
         docname = docname_join(refdoc, node['reftarget'])
@@ -940,7 +941,7 @@ def _resolve_doc_xref(self, env: "BuildEnvironment", fromdocname: str,
 
     def _resolve_option_xref(self, env: "BuildEnvironment", fromdocname: str,
                              builder: "Builder", typ: str, target: str,
-                             node: pending_xref, contnode: Element) -> Element:
+                             node: pending_xref, contnode: Element) -> Optional[Element]:
         progname = node.get('std:program')
         target = target.strip()
         docname, labelid = self.progoptions.get((progname, target), ('', ''))
@@ -977,7 +978,7 @@ def _resolve_term_xref(self, env: "BuildEnvironment", fromdocname: str,
 
     def _resolve_obj_xref(self, env: "BuildEnvironment", fromdocname: str,
                           builder: "Builder", typ: str, target: str,
-                          node: pending_xref, contnode: Element) -> Element:
+                          node: pending_xref, contnode: Element) -> Optional[Element]:
         objtypes = self.objtypes_for_role(typ) or []
         for objtype in objtypes:
             if (objtype, target) in self.objects:
@@ -1041,7 +1042,7 @@ def get_type_name(self, type: ObjType, primary: bool = False) -> str:
     def is_enumerable_node(self, node: Node) -> bool:
         return node.__class__ in self.enumerable_nodes
 
-    def get_numfig_title(self, node: Node) -> str:
+    def get_numfig_title(self, node: Node) -> Optional[str]:
         """Get the title of enumerable nodes to refer them using its title"""
         if self.is_enumerable_node(node):
             elem = cast(Element, node)
@@ -1055,7 +1056,7 @@ def get_numfig_title(self, node: Node) -> str:
 
         return None
 
-    def get_enumerable_node_type(self, node: Node) -> str:
+    def get_enumerable_node_type(self, node: Node) -> Optional[str]:
         """Get type of enumerable nodes."""
         def has_child(node: Element, cls: Type) -> bool:
             return any(isinstance(child, cls) for child in node)
@@ -1094,7 +1095,7 @@ def get_fignumber(self, env: "BuildEnvironment", builder: "Builder",
                 # Maybe it is defined in orphaned document.
                 raise ValueError from exc
 
-    def get_full_qualified_name(self, node: Element) -> str:
+    def get_full_qualified_name(self, node: Element) -> Optional[str]:
         if node.get('reftype') == 'option':
             progname = node.get('std:program')
             command = ws_re.split(node.get('reftarget'))
@@ -1109,7 +1110,8 @@ def get_full_qualified_name(self, node: Element) -> str:
             return None
 
 
-def warn_missing_reference(app: "Sphinx", domain: Domain, node: pending_xref) -> bool:
+def warn_missing_reference(app: "Sphinx", domain: Domain, node: pending_xref
+                           ) -> Optional[bool]:
     if (domain and domain.name != 'std') or node['reftype'] != 'ref':
         return None
     else: