Added basic type checking

.github/workflows/main.yml

@@ -1,6 +1,8 @@
 name: tests
 
-on: [push, pull_request]
+on:
+  - push
+  - pull_request
 
 jobs:
   test:
@@ -10,28 +12,14 @@ jobs:
         platform: [ubuntu-latest, macos-latest, windows-latest]
     runs-on: ${{ matrix.platform }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v4
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip setuptools wheel
-          python -m pip install tox
+          python -m pip install tox tox-gh-actions
       - name: Run tests
-        run: tox -e py
+        run: tox
-  lint:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v2
-      - name: Set up Python 3.11
-        uses: actions/setup-python@v2
-        with:
-          python-version: 3.11
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip setuptools wheel
-          python -m pip install tox
-      - name: Lint
-        run: tox -e formatting,lint

autoapi/backends.py

@@ -1,3 +1,5 @@
+from typing import Dict, Sequence, Tuple
+
 from .mappers import (
     DotNetSphinxMapper,
     PythonSphinxMapper,
@@ -30,9 +32,9 @@ LANGUAGE_MAPPERS = {
 
 #: describes backend requirements in form
 #: {'backend name': (('1st package name in pypi', '1st package import name'), ...)}
-LANGUAGE_REQUIREMENTS = {
+LANGUAGE_REQUIREMENTS: Dict[str, Sequence[Tuple[str, str]]] = {
     "python": (),
     "javascript": (),
     "go": (("sphinxcontrib-golangdomain", "sphinxcontrib.golangdomain"),),
     "dotnet": (("sphinxcontrib-dotnetdomain", "sphinxcontrib.dotnetdomain"),),
-}  # type: Dict[str, Sequence[Tuple[str, str]]]
+}

autoapi/directives.py

@@ -53,7 +53,6 @@ class NestedParse(Directive):  # pylint: disable=too-few-public-methods
     required_arguments = 0
     optional_arguments = 0
     final_argument_whitespace = False
-    option_spec = {}
 
     def run(self):
         node = nodes.container()

autoapi/extension.py

@@ -1,6 +1,4 @@
-# -*- coding: utf-8 -*-
+"""Sphinx Auto-API Top-level Extension.
-"""
-Sphinx Auto-API Top-level Extension.
 
 This extension allows you to automagically generate API documentation from your project.
 """
@@ -8,10 +6,11 @@ import io
 import os
 import shutil
 import sys
+from typing import Dict, Tuple
 import warnings
 
 import sphinx
-from sphinx.util.console import darkgreen, bold
+from sphinx.util.console import colorize
 from sphinx.addnodes import toctree
 from sphinx.errors import ExtensionError
 import sphinx.util.logging
@@ -40,11 +39,8 @@ _DEFAULT_OPTIONS = [
     "special-members",
     "imported-members",
 ]
-_VIEWCODE_CACHE = {}
+_VIEWCODE_CACHE: Dict[str, Tuple[str, Dict]] = {}
-"""Caches a module's parse results for use in viewcode.
+"""Caches a module's parse results for use in viewcode."""
-
-:type: dict(str, tuple)
-"""
 
 
 class RemovedInAutoAPI2Warning(DeprecationWarning):
@@ -165,7 +161,10 @@ def build_finished(app, exception):
             os.path.join(app.srcdir, app.config.autoapi_root)
         )
         if app.verbosity > 1:
-            LOGGER.info(bold("[AutoAPI] ") + darkgreen("Cleaning generated .rst files"))
+            LOGGER.info(
+                colorize("bold", "[AutoAPI] ")
+                + colorize("darkgreen", "Cleaning generated .rst files")
+            )
         shutil.rmtree(normalized_root)
 
         sphinx_mapper = LANGUAGE_MAPPERS[app.config.autoapi_type]
@@ -211,8 +210,10 @@ def doctree_read(app, doctree):
             # Insert AutoAPI index
             nodes[-1]["entries"].append((None, f"{app.config.autoapi_root}/index"))
             nodes[-1]["includefiles"].append(f"{app.config.autoapi_root}/index")
-            message_prefix = bold("[AutoAPI] ")
+            message_prefix = colorize("bold", "[AutoAPI] ")
-            message = darkgreen(f"Adding AutoAPI TOCTree [{toc_entry}] to index.rst")
+            message = colorize(
+                "darkgreen", f"Adding AutoAPI TOCTree [{toc_entry}] to index.rst"
+            )
             LOGGER.info(message_prefix + message)
 
 

autoapi/mappers/base.py

@@ -6,7 +6,7 @@ import re
 from jinja2 import Environment, FileSystemLoader, TemplateNotFound
 import sphinx
 import sphinx.util
-from sphinx.util.console import darkgreen, bold
+from sphinx.util.console import colorize
 from sphinx.util.osutil import ensuredir
 import sphinx.util.logging
 import unidecode
@@ -211,7 +211,10 @@ class SphinxMapperBase:
         """
         paths = list(self.find_files(patterns=patterns, dirs=dirs, ignore=ignore))
         for path in sphinx.util.status_iterator(
-            paths, bold("[AutoAPI] Reading files... "), "darkgreen", len(paths)
+            paths,
+            colorize("bold", "[AutoAPI] Reading files... "),
+            "darkgreen",
+            len(paths),
         ):
             data = self.read_file(path=path)
             if data:
@@ -248,8 +251,10 @@ class SphinxMapperBase:
                                 os.path.join(root, filename), ignore_pattern
                             ):
                                 LOGGER.info(
-                                    bold("[AutoAPI] ")
+                                    colorize("bold", "[AutoAPI] ")
-                                    + darkgreen(f"Ignoring {root}/{filename}")
+                                    + colorize(
+                                        "darkgreen", f"Ignoring {root}/{filename}"
+                                    )
                                 )
                                 skip = True
 
@@ -290,7 +295,7 @@ class SphinxMapperBase:
         """Trigger find of serialized sources and build objects"""
         for _, data in sphinx.util.status_iterator(
             self.paths.items(),
-            bold("[AutoAPI] ") + "Mapping Data... ",
+            colorize("bold", "[AutoAPI] ") + "Mapping Data... ",
             length=len(self.paths),
             stringify_func=(lambda x: x[0]),
         ):
@@ -308,7 +313,7 @@ class SphinxMapperBase:
     def output_rst(self, root, source_suffix):
         for _, obj in sphinx.util.status_iterator(
             self.objects.items(),
-            bold("[AutoAPI] ") + "Rendering Data... ",
+            colorize("bold", "[AutoAPI] ") + "Rendering Data... ",
             length=len(self.objects),
             verbosity=1,
             stringify_func=(lambda x: x[0]),

autoapi/mappers/dotnet.py

@@ -1,14 +1,15 @@
+from collections import defaultdict
 import re
 import os
 import subprocess
 import traceback
 import shutil
-from collections import defaultdict
+from typing import Dict
 import unidecode
 
 import yaml
 from sphinx.util.osutil import ensuredir
-from sphinx.util.console import darkgreen, bold
+from sphinx.util.console import colorize
 import sphinx.util.logging
 from sphinx.errors import ExtensionError
 
@@ -56,7 +57,7 @@ class DotNetSphinxMapper(SphinxMapperBase):
     :param app: Sphinx application passed in as part of the extension
     """
 
-    top_namespaces = {}
+    top_namespaces: Dict[str, "DotNetNamespace"] = {}
 
     DOCFX_OUTPUT_PATH = "_api"
 
@@ -69,7 +70,9 @@ class DotNetSphinxMapper(SphinxMapperBase):
         the canonical source before the default patterns.  Fallback to default
         pattern matches if no ``docfx.json`` files are found.
         """
-        LOGGER.info(bold("[AutoAPI] ") + darkgreen("Loading Data"))
+        LOGGER.info(
+            colorize("bold", "[AutoAPI] ") + colorize("darkgreen", "Loading Data")
+        )
         all_files = set()
         if not self.app.config.autoapi_file_patterns:
             all_files = set(
@@ -141,7 +144,7 @@ class DotNetSphinxMapper(SphinxMapperBase):
         """Trigger find of serialized sources and build objects"""
         for _, data in sphinx.util.status_iterator(
             self.paths.items(),
-            bold("[AutoAPI] ") + "Mapping Data... ",
+            colorize("bold", "[AutoAPI] ") + "Mapping Data... ",
             length=len(self.paths),
             stringify_func=(lambda x: x[0]),
         ):
@@ -242,7 +245,7 @@ class DotNetSphinxMapper(SphinxMapperBase):
 
         for _, obj in sphinx.util.status_iterator(
             self.objects.items(),
-            bold("[AutoAPI] ") + "Rendering Data... ",
+            colorize("bold", "[AutoAPI] ") + "Rendering Data... ",
             length=len(self.objects),
             stringify_func=(lambda x: x[0]),
         ):
@@ -270,7 +273,10 @@ class DotNetSphinxMapper(SphinxMapperBase):
     @staticmethod
     def build_finished(app, _):
         if app.verbosity > 1:
-            LOGGER.info(bold("[AutoAPI] ") + darkgreen("Cleaning generated .yml files"))
+            LOGGER.info(
+                colorize("bold", "[AutoAPI] ")
+                + colorize("darkgreen", "Cleaning generated .yml files")
+            )
         if os.path.exists(DotNetSphinxMapper.DOCFX_OUTPUT_PATH):
             shutil.rmtree(DotNetSphinxMapper.DOCFX_OUTPUT_PATH)
 

autoapi/mappers/go.py

@@ -1,7 +1,7 @@
 import json
 import subprocess
 
-from sphinx.util.console import bold
+from sphinx.util.console import colorize
 import sphinx.util.logging
 
 from .base import PythonMapperBase, SphinxMapperBase
@@ -24,7 +24,7 @@ class GoSphinxMapper(SphinxMapperBase):
 
         """
         for _dir in sphinx.util.status_iterator(
-            dirs, bold("[AutoAPI] Loading Data "), "darkgreen", len(dirs)
+            dirs, colorize("bold", "[AutoAPI] Loading Data "), "darkgreen", len(dirs)
         ):
             data = self.read_file(_dir, ignore=ignore)
             if data:
@@ -123,7 +123,6 @@ class GoSphinxMapper(SphinxMapperBase):
 
 
 class GoPythonMapper(PythonMapperBase):
-
     language = "go"
     inverted_names = False
 

autoapi/mappers/javascript.py

@@ -2,7 +2,7 @@ import json
 import subprocess
 import os
 
-from sphinx.util.console import bold
+from sphinx.util.console import colorize
 import sphinx.util.logging
 
 from .base import PythonMapperBase, SphinxMapperBase
@@ -52,7 +52,7 @@ class JavaScriptSphinxMapper(SphinxMapperBase):
         """Trigger find of serialized sources and build objects"""
         for _, data in sphinx.util.status_iterator(
             self.paths.items(),
-            bold("[AutoAPI] ") + "Mapping Data... ",
+            colorize("bold", "[AutoAPI] ") + "Mapping Data... ",
             length=len(self.paths),
             stringify_func=(lambda x: x[0]),
         ):
@@ -92,7 +92,6 @@ class JavaScriptSphinxMapper(SphinxMapperBase):
 
 
 class JavaScriptPythonMapper(PythonMapperBase):
-
     language = "javascript"
 
     def __init__(self, obj, **kwargs):

autoapi/mappers/python/mapper.py

@@ -7,7 +7,7 @@ import re
 import sphinx.environment
 from sphinx.errors import ExtensionError
 import sphinx.util
-from sphinx.util.console import bold
+from sphinx.util.console import colorize
 import sphinx.util.docstrings
 import sphinx.util.logging
 
@@ -292,7 +292,7 @@ class PythonSphinxMapper(SphinxMapperBase):
 
         for dir_root, path in sphinx.util.status_iterator(
             dir_root_files,
-            bold("[AutoAPI] Reading files... "),
+            colorize("bold", "[AutoAPI] Reading files... "),
             length=len(dir_root_files),
             stringify_func=(lambda x: x[1]),
         ):

autoapi/mappers/python/objects.py

@@ -1,5 +1,5 @@
 import functools
-from typing import Optional
+from typing import List, Optional
 
 import sphinx.util.logging
 
@@ -41,14 +41,14 @@ class PythonPythonMapper(PythonMapperBase):
     is_callable = False
     member_order = 0
 
-    def __init__(self, obj, class_content="class", **kwargs):
+    def __init__(self, obj, class_content="class", **kwargs) -> None:
         super().__init__(obj, **kwargs)
 
         self.name = obj["name"]
         self.id = obj.get("full_name", self.name)
 
         # Optional
-        self.children = []
+        self.children: List[PythonPythonMapper] = []
         self._docstring = obj["doc"]
         self._docstring_resolved = False
         self.imported = "original_path" in obj
@@ -61,7 +61,7 @@ class PythonPythonMapper(PythonMapperBase):
         # For later
         self._class_content = class_content
 
-        self._display_cache = None  # type: Optional[bool]
+        self._display_cache: Optional[bool] = None
 
     @property
     def docstring(self):

docs/changes/+52f8a406.misc.rst

@@ -0,0 +1 @@
+Added basic type checking.

pyproject.toml

@@ -2,6 +2,14 @@
 requires = ["setuptools>=46.4.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
+[[tool.mypy.overrides]]
+module = "astroid.*"
+ignore_missing_imports = true
+
+[[tool.mypy.overrides]]
+module = "autoapi.documenters"
+ignore_errors = true
+
 [tool.towncrier]
 directory = "docs/changes"
 filename = "CHANGELOG.rst"

tests/python/pypackagecomplex/complex/foo.py

@@ -10,7 +10,6 @@ __all__ = ["PublicClass", "Foo"]
 
 
 class Foo(object):
-
     class_var = 42  #: Class var docstring
 
     another_class_var = 42

tests/python/pypackageexample/example/foo.py

@@ -5,7 +5,6 @@ This is a description
 
 
 class Foo(object):
-
     class_var = 42  #: Class var docstring
 
     another_class_var = 42

tests/python/test_pyintegration.py

@@ -458,7 +458,6 @@ class TestSimplePackage:
         builder("pypackageexample")
 
     def test_integration_with_package(self):
-
         example_path = "_build/text/autoapi/example/index.txt"
         with io.open(example_path, encoding="utf8") as example_handle:
             example_file = example_handle.read()

tox.ini

@@ -4,10 +4,19 @@ envlist =
     # Keep this in sync with .github/workflows/main.yml
     py{37,38,39,310,311}
     formatting
+    typecheck
     lint
     docs
     release_notes
 
+[gh-actions]
+python =
+    3.7: py37
+    3.8: py38
+    3.9: py39
+    3.10: py310
+    3.11: py311, formatting, typecheck, lint, docs, release_notes
+
 [testenv]
 extras =
     dotnet
@@ -32,6 +41,14 @@ deps =
 commands =
     pylint {posargs:autoapi}
 
+[testenv:typecheck]
+deps =
+    mypy
+    types-docutils
+    types-PyYAML
+commands =
+    mypy {posargs:autoapi}
+
 [testenv:docs]
 extras =
     docs