Convert type comments to annotations

Author: AA-Turner

sphinxcontrib/websupport/builder.py

@@ -9,9 +9,12 @@
     :license: BSD, see LICENSE for details.
 """
 
+from __future__ import annotations
+
 from os import path
 import posixpath
 import shutil
+from typing import TYPE_CHECKING, Any
 
 from docutils.io import StringOutput
 
@@ -24,11 +27,11 @@
 from sphinxcontrib.websupport.utils import is_commentable
 
 
-if False:
-    # For type annotation
-    from typing import Any, Dict, Iterable, Tuple  # NOQA
-    from docutils import nodes  # NOQA
-    from sphinx.application import Sphinx  # NOQA
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from docutils import nodes
+    from sphinx.application import Sphinx
 
 RESOURCES = [
     'ajax-loader.gif',
@@ -51,8 +54,7 @@ class WebSupportBuilder(PickleHTMLBuilder):
     default_translator_class = WebSupportTranslator
     versioning_compare = True  # for commentable node's uuid stability.
 
-    def init(self):
-        # type: () -> None
+    def init(self) -> None:
         PickleHTMLBuilder.init(self)
         # templates are needed for this builder, but the serializing
         # builder does not initialize them
@@ -67,20 +69,22 @@ def init(self):
     def versioning_method(self):
         return is_commentable
 
-    def set_webinfo(self, staticdir, virtual_staticdir, search, storage):
-        # type: (str, str, Any, str) -> None
+    def set_webinfo(self,
+        staticdir: str,
+        virtual_staticdir: str,
+        search: Any,
+        storage: str,
+    ) -> None:
         self.staticdir = staticdir
         self.virtual_staticdir = virtual_staticdir
         self.search = search
         self.storage = storage
 
-    def prepare_writing(self, docnames):
-        # type: (Iterable[str]) -> None
+    def prepare_writing(self, docnames: Iterable[str]) -> None:
         PickleHTMLBuilder.prepare_writing(self, docnames)
         self.globalcontext['no_search_suffix'] = True
 
-    def write_doc(self, docname, doctree):
-        # type: (str, nodes.document) -> None
+    def write_doc(self, docname: str, doctree: nodes.document) -> None:
         destination = StringOutput(encoding='utf-8')
         doctree.settings = self.docsettings
 
@@ -97,30 +101,31 @@ def write_doc(self, docname, doctree):
         ctx = self.get_doc_context(docname, body, metatags)
         self.handle_page(docname, ctx, event_arg=doctree)
 
-    def write_doc_serialized(self, docname, doctree):
-        # type: (str, nodes.Node) -> None
+    def write_doc_serialized(self, docname: str, doctree: nodes.Node) -> None:
         self.imgpath = '/' + posixpath.join(self.virtual_staticdir, self.imagedir)
         self.post_process_images(doctree)
         title = self.env.longtitles.get(docname)
         title = title and self.render_partial(title)['title'] or ''
         self.index_page(docname, doctree, title)
 
-    def load_indexer(self, docnames):
-        # type: (Iterable[str]) -> None
+    def load_indexer(self, docnames: Iterable[str]) -> None:
         self.indexer = self.search  # type: ignore
         self.indexer.init_indexing(changed=docnames)  # type: ignore
 
-    def _render_page(self, pagename, addctx, templatename, event_arg=None):
-        # type: (str, Dict, str, Any) -> Tuple[Dict, Dict]
+    def _render_page(self,
+        pagename: str,
+        addctx: dict,
+        templatename: str,
+        event_arg: Any = None,
+    ) -> tuple[dict, dict]:
         # This is mostly copied from StandaloneHTMLBuilder. However, instead
         # of rendering the template and saving the html, create a context
         # dict and pickle it.
         ctx = self.globalcontext.copy()
         ctx['pagename'] = pagename
 
-        def pathto(otheruri, resource=False,
-                   baseuri=self.get_target_uri(pagename)):
-            # type: (str, bool, str) -> str
+        def pathto(otheruri: str, resource: bool = False,
+                   baseuri: str = self.get_target_uri(pagename)) -> str:
             if resource and '://' in otheruri:
                 return otheruri
             elif not resource:
@@ -156,9 +161,8 @@ def pathto(otheruri, resource=False,
 
         return ctx, doc_ctx
 
-    def handle_page(self, pagename, addctx, templatename='page.html',
-                    outfilename=None, event_arg=None):
-        # type: (str, Dict, str, str | None, Any) -> None
+    def handle_page(self, pagename: str, addctx: dict, templatename: str = 'page.html',
+                    outfilename: str | None = None, event_arg: Any = None) -> None:
         ctx, doc_ctx = self._render_page(pagename, addctx,
                                          templatename, event_arg)
 
@@ -176,8 +180,7 @@ def handle_page(self, pagename, addctx, templatename='page.html',
             ensuredir(path.dirname(source_name))
             copyfile(self.env.doc2path(pagename), source_name)
 
-    def handle_finish(self):
-        # type: () -> None
+    def handle_finish(self) -> None:
         # get global values for css and script files
         _, doc_ctx = self._render_page('tmp', {}, 'page.html')
         self.globalcontext['css'] = doc_ctx['css']
@@ -196,8 +199,7 @@ def handle_finish(self):
                 shutil.move(src, dst)
         self.copy_resources()
 
-    def copy_resources(self):
-        # type: () -> None
+    def copy_resources(self) -> None:
         # copy resource files to static dir
         dst = path.join(self.staticdir, '_static')
 
@@ -206,13 +208,11 @@ def copy_resources(self):
                 src = path.join(package_dir, 'files', resource)
                 shutil.copy(src, dst)
 
-    def dump_search_index(self):
-        # type: () -> None
+    def dump_search_index(self) -> None:
         self.indexer.finish_indexing()  # type: ignore
 
 
-def setup(app):
-    # type: (Sphinx) -> Dict[str, Any]
+def setup(app: Sphinx) -> dict[str, Any]:
     app.add_builder(WebSupportBuilder)
 
     return {

sphinxcontrib/websupport/core.py

@@ -9,6 +9,8 @@
     :license: BSD, see LICENSE for details.
 """
 
+from __future__ import annotations
+
 import html
 import sys
 import pickle
@@ -31,10 +33,6 @@
 except ImportError:
     from sphinx.util.jsonimpl import dumps as dump_json
 
-if False:
-    # For type annotation
-    from typing import Dict  # NOQA
-
 
 class WebSupport(object):
     """The main API class for the web support package. All interactions
@@ -402,7 +400,7 @@ def _make_base_comment_options(self):
         that remains the same throughout the lifetime of the
         :class:`~sphinxcontrib.websupport.WebSupport` object.
         """
-        self.base_comment_opts = {}  # type: Dict[str, str]
+        self.base_comment_opts: dict[str, str] = {}
 
         if self.docroot != '':
             comment_urls = [

sphinxcontrib/websupport/storage/sqlalchemy_db.py

@@ -10,17 +10,15 @@
     :license: BSD, see LICENSE for details.
 """
 
+from __future__ import annotations
+
 from datetime import datetime
 
 from sqlalchemy import Column, Integer, Text, String, Boolean, \
     ForeignKey, DateTime
 from sqlalchemy.orm import relation, sessionmaker, aliased
 from sqlalchemy.ext.declarative import declarative_base
 
-if False:
-    # For type annotation
-    from typing import List  # NOQA
-
 Base = declarative_base()
 Session = sessionmaker()
 
@@ -78,7 +76,7 @@ def _nest_comments(self, results, username):
         :param results: the flat list of comments
         :param username: the name of the user requesting the comments.
         """
-        comments = []  # type: List
+        comments = []
         list_stack = [comments]
         for r in results:
             if username:

sphinxcontrib/websupport/utils.py

@@ -6,13 +6,14 @@
     :copyright: Copyright 2007-2016 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
+from __future__ import annotations
 
-if False:
-    # For type annotation
-    from docutils import nodes  # NOQA
+from typing import TYPE_CHECKING
 
+if TYPE_CHECKING:
+    from docutils import nodes
 
-def is_commentable(node):
-    # type: (nodes.Node) -> bool
+
+def is_commentable(node: nodes.Node) -> bool:
     # return node.__class__.__name__ in ('paragraph', 'literal_block')
     return node.__class__.__name__ == 'paragraph'