Merge pull request #9031 from tk0miya/refactor_vartypes_env

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

Author: tk0miya

sphinx/environment/__init__.py

@@ -42,7 +42,7 @@
 
 logger = logging.getLogger(__name__)
 
-default_settings = {
+default_settings: Dict[str, Any] = {
     'embed_stylesheet': False,
     'cloak_email_addresses': True,
     'pep_base_url': 'https://www.python.org/dev/peps/',
@@ -55,7 +55,7 @@
     'halt_level': 5,
     'file_insertion_enabled': True,
     'smartquotes_locales': [],
-}  # type: Dict[str, Any]
+}
 
 # This is increased every time an environment attribute is added
 # or changed to properly invalidate pickle files.
@@ -74,10 +74,10 @@
 }
 
 
-versioning_conditions = {
+versioning_conditions: Dict[str, Union[bool, Callable]] = {
     'none': False,
     'text': is_translatable,
-}  # type: Dict[str, Union[bool, Callable]]
+}
 
 
 class BuildEnvironment:
@@ -87,24 +87,24 @@ class BuildEnvironment:
     transformations to resolve links to them.
     """
 
-    domains = None  # type: Dict[str, Domain]
+    domains: Dict[str, Domain] = None
 
     # --------- ENVIRONMENT INITIALIZATION -------------------------------------
 
     def __init__(self, app: "Sphinx" = None):
-        self.app = None                  # type: Sphinx
-        self.doctreedir = None           # type: str
-        self.srcdir = None               # type: str
-        self.config = None               # type: Config
-        self.config_status = None        # type: int
-        self.config_status_extra = None  # type: str
-        self.events = None               # type: EventManager
-        self.project = None              # type: Project
-        self.version = None              # type: Dict[str, str]
+        self.app: Sphinx = None
+        self.doctreedir: str = None
+        self.srcdir: str = None
+        self.config: Config = None
+        self.config_status: int = None
+        self.config_status_extra: str = None
+        self.events: EventManager = None
+        self.project: Project = None
+        self.version: Dict[str, str] = None
 
         # the method of doctree versioning; see set_versioning_method
-        self.versioning_condition = None  # type: Union[bool, Callable]
-        self.versioning_compare = None  # type: bool
+        self.versioning_condition: Union[bool, Callable] = None
+        self.versioning_compare: bool = None
 
         # all the registered domains, set by the application
         self.domains = {}
@@ -116,70 +116,67 @@ def __init__(self, app: "Sphinx" = None):
         # All "docnames" here are /-separated and relative and exclude
         # the source suffix.
 
-        self.all_docs = {}          # type: Dict[str, float]
-                                    # docname -> mtime at the time of reading
-                                    # contains all read docnames
-        self.dependencies = defaultdict(set)    # type: Dict[str, Set[str]]
-                                    # docname -> set of dependent file
-                                    # names, relative to documentation root
-        self.included = defaultdict(set)        # type: Dict[str, Set[str]]
-                                    # docname -> set of included file
-                                    # docnames included from other documents
-        self.reread_always = set()  # type: Set[str]
-                                    # docnames to re-read unconditionally on
-                                    # next build
+        # docname -> mtime at the time of reading
+        # contains all read docnames
+        self.all_docs: Dict[str, float] = {}
+        # docname -> set of dependent file
+        # names, relative to documentation root
+        self.dependencies: Dict[str, Set[str]] = defaultdict(set)
+        # docname -> set of included file
+        # docnames included from other documents
+        self.included: Dict[str, Set[str]] = defaultdict(set)
+        # docnames to re-read unconditionally on next build
+        self.reread_always: Set[str] = set()
 
         # File metadata
-        self.metadata = defaultdict(dict)       # type: Dict[str, Dict[str, Any]]
-                                                # docname -> dict of metadata items
+        # docname -> dict of metadata items
+        self.metadata: Dict[str, Dict[str, Any]] = defaultdict(dict)
 
         # TOC inventory
-        self.titles = {}            # type: Dict[str, nodes.title]
-                                    # docname -> title node
-        self.longtitles = {}        # type: Dict[str, nodes.title]
-                                    # docname -> title node; only different if
-                                    # set differently with title directive
-        self.tocs = {}              # type: Dict[str, nodes.bullet_list]
-                                    # docname -> table of contents nodetree
-        self.toc_num_entries = {}   # type: Dict[str, int]
-                                    # docname -> number of real entries
+        # docname -> title node
+        self.titles: Dict[str, nodes.title] = {}
+        # docname -> title node; only different if
+        # set differently with title directive
+        self.longtitles: Dict[str, nodes.title] = {}
+        # docname -> table of contents nodetree
+        self.tocs: Dict[str, nodes.bullet_list] = {}
+        # docname -> number of real entries
+        self.toc_num_entries: Dict[str, int] = {}
 
         # used to determine when to show the TOC
         # in a sidebar (don't show if it's only one item)
-        self.toc_secnumbers = {}    # type: Dict[str, Dict[str, Tuple[int, ...]]]
-                                    # docname -> dict of sectionid -> number
-        self.toc_fignumbers = {}    # type: Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]]
-                                    # docname -> dict of figtype ->
-                                    # dict of figureid -> number
-
-        self.toctree_includes = {}  # type: Dict[str, List[str]]
-                                    # docname -> list of toctree includefiles
-        self.files_to_rebuild = {}  # type: Dict[str, Set[str]]
-                                    # docname -> set of files
-                                    # (containing its TOCs) to rebuild too
-        self.glob_toctrees = set()  # type: Set[str]
-                                    # docnames that have :glob: toctrees
-        self.numbered_toctrees = set()  # type: Set[str]
-                                        # docnames that have :numbered: toctrees
+        # docname -> dict of sectionid -> number
+        self.toc_secnumbers: Dict[str, Dict[str, Tuple[int, ...]]] = {}
+        # docname -> dict of figtype -> dict of figureid -> number
+        self.toc_fignumbers: Dict[str, Dict[str, Dict[str, Tuple[int, ...]]]] = {}
+
+        # docname -> list of toctree includefiles
+        self.toctree_includes: Dict[str, List[str]] = {}
+        # docname -> set of files (containing its TOCs) to rebuild too
+        self.files_to_rebuild: Dict[str, Set[str]] = {}
+        # docnames that have :glob: toctrees
+        self.glob_toctrees: Set[str] = set()
+        # docnames that have :numbered: toctrees
+        self.numbered_toctrees: Set[str] = set()
 
         # domain-specific inventories, here to be pickled
-        self.domaindata = {}        # type: Dict[str, Dict]
-                                    # domainname -> domain-specific dict
+        # domainname -> domain-specific dict
+        self.domaindata: Dict[str, Dict] = {}
 
         # these map absolute path -> (docnames, unique filename)
-        self.images = FilenameUniqDict()    # type: FilenameUniqDict
-        self.dlfiles = DownloadFiles()      # type: DownloadFiles
-                                            # filename -> (set of docnames, destination)
+        self.images: FilenameUniqDict = FilenameUniqDict()
+        # filename -> (set of docnames, destination)
+        self.dlfiles: DownloadFiles = DownloadFiles()
 
         # the original URI for images
-        self.original_image_uri = {}  # type: Dict[str, str]
+        self.original_image_uri: Dict[str, str] = {}
 
         # temporary data storage while reading a document
-        self.temp_data = {}         # type: Dict[str, Any]
+        self.temp_data: Dict[str, Any] = {}
         # context for cross-references (e.g. current module or class)
         # this is similar to temp_data, but will for example be copied to
         # attributes of "any" cross references
-        self.ref_context = {}       # type: Dict[str, Any]
+        self.ref_context: Dict[str, Any] = {}
 
         # set up environment
         if app:
@@ -269,7 +266,7 @@ def set_versioning_method(self, method: Union[str, Callable], compare: bool) ->
         raise an exception if the user tries to use an environment with an
         incompatible versioning method.
         """
-        condition = None  # type: Union[bool, Callable]
+        condition: Union[bool, Callable] = None
         if callable(method):
             condition = method
         else:
@@ -385,8 +382,8 @@ def get_outdated_files(self, config_changed: bool) -> Tuple[Set[str], Set[str],
         # clear all files no longer present
         removed = set(self.all_docs) - self.found_docs
 
-        added = set()  # type: Set[str]
-        changed = set()  # type: Set[str]
+        added: Set[str] = set()
+        changed: Set[str] = set()
 
         if config_changed:
             # config values affect e.g. substitutions
@@ -438,7 +435,7 @@ def get_outdated_files(self, config_changed: bool) -> Tuple[Set[str], Set[str],
         return added, changed, removed
 
     def check_dependents(self, app: "Sphinx", already: Set[str]) -> Generator[str, None, None]:
-        to_rewrite = []  # type: List[str]
+        to_rewrite: List[str] = []
         for docnames in self.events.emit('env-get-updated', self):
             to_rewrite.extend(docnames)
         for docname in set(to_rewrite):

sphinx/environment/adapters/indexentries.py

@@ -31,7 +31,7 @@ def create_index(self, builder: Builder, group_entries: bool = True,
                      _fixre: Pattern = re.compile(r'(.*) ([(][^()]*[)])')
                      ) -> List[Tuple[str, List[Tuple[str, Any]]]]:
         """Create the real index from the collected index entries."""
-        new = {}  # type: Dict[str, List]
+        new: Dict[str, List] = {}
 
         def add_entry(word: str, subword: str, main: str, link: bool = True,
                       dic: Dict = new, key: str = None) -> None:
@@ -126,7 +126,7 @@ def keyfunc(entry: Tuple[str, List]) -> Tuple[Tuple[int, str], str]:
             #     (in module foo)
             #     (in module bar)
             oldkey = ''
-            oldsubitems = None  # type: Dict[str, List]
+            oldsubitems: Dict[str, List] = None
             i = 0
             while i < len(newlist):
                 key, (targets, subitems, _key) = newlist[i]

sphinx/environment/adapters/toctree.py

@@ -102,7 +102,7 @@ def _toctree_add_classes(node: Element, depth: int) -> None:
                         if not subnode['anchorname']:
                             # give the whole branch a 'current' class
                             # (useful for styling it differently)
-                            branchnode = subnode  # type: Element
+                            branchnode: Element = subnode
                             while branchnode:
                                 branchnode['classes'].append('current')
                                 branchnode = branchnode.parent
@@ -119,7 +119,7 @@ def _entries_from_toctree(toctreenode: addnodes.toctree, parents: List[str],
                                   ) -> List[Element]:
             """Return TOC entries for a toctree node."""
             refs = [(e[0], e[1]) for e in toctreenode['entries']]
-            entries = []  # type: List[Element]
+            entries: List[Element] = []
             for (title, ref) in refs:
                 try:
                     refdoc = None
@@ -268,7 +268,7 @@ def get_toctree_ancestors(self, docname: str) -> List[str]:
         for p, children in self.env.toctree_includes.items():
             for child in children:
                 parent[child] = p
-        ancestors = []  # type: List[str]
+        ancestors: List[str] = []
         d = docname
         while d in parent and d not in ancestors:
             ancestors.append(d)
@@ -316,7 +316,7 @@ def get_toctree_for(self, docname: str, builder: "Builder", collapse: bool,
                         **kwargs: Any) -> Element:
         """Return the global TOC nodetree."""
         doctree = self.env.get_doctree(self.env.config.root_doc)
-        toctrees = []  # type: List[Element]
+        toctrees: List[Element] = []
         if 'includehidden' not in kwargs:
             kwargs['includehidden'] = True
         if 'maxdepth' not in kwargs or not kwargs['maxdepth']:

sphinx/environment/collectors/__init__.py

@@ -27,7 +27,7 @@ class EnvironmentCollector:
     entries and toctrees, etc.
     """
 
-    listener_ids = None  # type: Dict[str, int]
+    listener_ids: Dict[str, int] = None
 
     def enable(self, app: "Sphinx") -> None:
         assert self.listener_ids is None

sphinx/environment/collectors/asset.py

@@ -48,7 +48,7 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
             # choose the best image from these candidates.  The special key * is
             # set if there is only single candidate to be used by a writer.
             # The special key ? is set for nonlocal URIs.
-            candidates = {}  # type: Dict[str, str]
+            candidates: Dict[str, str] = {}
             node['candidates'] = candidates
             imguri = node['uri']
             if imguri.startswith('data:'):
@@ -94,7 +94,7 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
 
     def collect_candidates(self, env: BuildEnvironment, imgpath: str,
                            candidates: Dict[str, str], node: Node) -> None:
-        globbed = {}  # type: Dict[str, List[str]]
+        globbed: Dict[str, List[str]] = {}
         for filename in glob(imgpath):
             new_imgpath = relative_path(path.join(env.srcdir, 'dummy'),
                                         filename)

sphinx/environment/collectors/toctree.py

@@ -64,7 +64,7 @@ def process_doc(self, app: Sphinx, doctree: nodes.document) -> None:
 
         def traverse_in_section(node: Element, cls: "Type[N]") -> List[N]:
             """Like traverse(), but stay within the same section."""
-            result = []  # type: List[N]
+            result: List[N] = []
             if isinstance(node, cls):
                 result.append(node)
             for child in node.children:
@@ -75,7 +75,7 @@ def traverse_in_section(node: Element, cls: "Type[N]") -> List[N]:
             return result
 
         def build_toc(node: Element, depth: int = 1) -> nodes.bullet_list:
-            entries = []  # type: List[Element]
+            entries: 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
@@ -100,7 +100,7 @@ def build_toc(node: Element, depth: int = 1) -> nodes.bullet_list:
                         '', '', internal=True, refuri=docname,
                         anchorname=anchorname, *nodetext)
                     para = addnodes.compact_paragraph('', '', reference)
-                    item = nodes.list_item('', para)  # type: Element
+                    item: Element = nodes.list_item('', para)
                     sub_item = build_toc(sectionnode, depth + 1)
                     if sub_item:
                         item += sub_item
@@ -136,7 +136,7 @@ def assign_section_numbers(self, env: BuildEnvironment) -> List[str]:
         # a list of all docnames whose section numbers changed
         rewrite_needed = []
 
-        assigned = set()  # type: Set[str]
+        assigned: Set[str] = set()
         old_secnumbers = env.toc_secnumbers
         env.toc_secnumbers = {}
 
@@ -186,7 +186,7 @@ def _walk_toctree(toctreenode: addnodes.toctree, depth: int) -> None:
                                       '(nested numbered toctree?)'), ref,
                                    location=toctreenode, type='toc', subtype='secnum')
                 elif ref in env.tocs:
-                    secnums = {}  # type: Dict[str, Tuple[int, ...]]
+                    secnums: Dict[str, Tuple[int, ...]] = {}
                     env.toc_secnumbers[ref] = secnums
                     assigned.add(ref)
                     _walk_toc(env.tocs[ref], secnums, depth, env.titles.get(ref))
@@ -210,10 +210,10 @@ def assign_figure_numbers(self, env: BuildEnvironment) -> List[str]:
 
         rewrite_needed = []
 
-        assigned = set()  # type: Set[str]
+        assigned: Set[str] = set()
         old_fignumbers = env.toc_fignumbers
         env.toc_fignumbers = {}
-        fignum_counter = {}  # type: Dict[str, Dict[Tuple[int, ...], int]]
+        fignum_counter: Dict[str, Dict[Tuple[int, ...], int]] = {}
 
         def get_figtype(node: Node) -> str:
             for domain in env.domains.values():