refactor: Add Optional to type annotations

9 files changed, 40 insertions, 37 deletions

diff --git a/sphinx/domains/__init__.py b/sphinx/domains/__init__.py
index 8f3e6a955..dbfad258c 100644
--- a/sphinx/domains/__init__.py
+++ b/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 @@ class Domain:
         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 @@ class Domain:
         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 @@ class Domain:
 
     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 @@ class Domain:
             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
diff --git a/sphinx/domains/c.py b/sphinx/domains/c.py
index b0711f68e..ed908c875 100644
--- a/sphinx/domains/c.py
+++ b/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 @@ class CDomain(Domain):
 
     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 @@ class CDomain(Domain):
 
     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]
 
diff --git a/sphinx/domains/citation.py b/sphinx/domains/citation.py
index 772d486af..0e859acb4 100644
--- a/sphinx/domains/citation.py
+++ b/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 @@ class CitationDomain(Domain):
 
     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
diff --git a/sphinx/domains/cpp.py b/sphinx/domains/cpp.py
index 7bb1e49aa..6c551b4a7 100644
--- a/sphinx/domains/cpp.py
+++ b/sphinx/domains/cpp.py
@@ -7594,7 +7594,7 @@ class CPPDomain(Domain):
 
     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 @@ class CPPDomain(Domain):
 
     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]
 
diff --git a/sphinx/domains/javascript.py b/sphinx/domains/javascript.py
index 92d0e1d61..8511a1d6a 100644
--- a/sphinx/domains/javascript.py
+++ b/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 @@ class JavaScriptDomain(Domain):
 
     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
diff --git a/sphinx/domains/math.py b/sphinx/domains/math.py
index 88db1ad0e..aa6f9422d 100644
--- a/sphinx/domains/math.py
+++ b/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 @@ class MathDomain(Domain):
 
     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:
diff --git a/sphinx/domains/python.py b/sphinx/domains/python.py
index 4464895ef..dbe2c87ca 100644
--- a/sphinx/domains/python.py
+++ b/sphinx/domains/python.py
@@ -15,7 +15,7 @@ import sys
 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 @@ class PythonDomain(Domain):
 
     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 @@ class PythonDomain(Domain):
                 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')
diff --git a/sphinx/domains/rst.py b/sphinx/domains/rst.py
index d048c2dfb..539a610bb 100644
--- a/sphinx/domains/rst.py
+++ b/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 @@ class ReSTDomain(Domain):
 
     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))
diff --git a/sphinx/domains/std.py b/sphinx/domains/std.py
index 5e10646f0..7660f84c9 100644
--- a/sphinx/domains/std.py
+++ b/sphinx/domains/std.py
@@ -285,7 +285,7 @@ class OptionXRefRole(XRefRole):
 
 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 @@ class StandardDomain(Domain):
         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 @@ class StandardDomain(Domain):
 
     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 @@ class StandardDomain(Domain):
 
     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 @@ class StandardDomain(Domain):
 
     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 @@ class StandardDomain(Domain):
 
     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 @@ class StandardDomain(Domain):
 
     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 @@ class StandardDomain(Domain):
 
     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 @@ class StandardDomain(Domain):
     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 @@ class StandardDomain(Domain):
 
         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 @@ class StandardDomain(Domain):
                 # 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 @@ class StandardDomain(Domain):
             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: