Use mypy

Author: rudolfbyker

.github/workflows/mypy.yml

@@ -0,0 +1,23 @@
+name: Lint with MyPy
+
+on: [push, pull_request]
+
+jobs:
+  mypy:
+    timeout-minutes: 10
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: 3.11
+
+      - name: Install dependencies
+        run: |
+          python -m pip install -c ci-constraints.txt . -r mypy-requirements.txt
+
+      - name: Run MyPy
+        run: |
+          mypy .

README.md

@@ -35,3 +35,17 @@ This will run all tests. This includes
 - Unit tests from `tests/`.
 - Doctests from `mkdocstrings_vba/`.
 - Full builds from `examples/`.
+
+## Linting
+
+Fix code style using `black`:
+
+```shell
+black .
+```
+
+Check types using `mypy`:
+
+```shell
+mypy .
+```

mkdocstrings_handlers/vba/__init__.py

@@ -1,5 +1,5 @@
 """This package implements a handler for the VBA language."""
 
-from mkdocstrings_handlers.vba._handler import get_handler
+from ._handler import get_handler
 
 __all__ = ["get_handler"]

mkdocstrings_handlers/vba/_crossref.py

@@ -34,8 +34,8 @@ def do_multi_crossref(text: str, code: bool = True) -> Markup:
     group_number = 0
     variables = {}
 
-    def repl(match):  # noqa: WPS430
-        nonlocal group_number  # noqa: WPS420
+    def repl(match: re.Match[str]) -> str:
+        nonlocal group_number
         group_number += 1
         path = match.group()
         path_var = f"path{group_number}"

mkdocstrings_handlers/vba/_handler.py

@@ -4,10 +4,21 @@
 
 from __future__ import annotations
 
+import copy
 import posixpath
 from collections import ChainMap
 from pathlib import Path
-from typing import Any, BinaryIO, Iterator, Optional, Tuple
+from typing import (
+    Any,
+    BinaryIO,
+    Iterator,
+    Optional,
+    Tuple,
+    MutableMapping,
+    Dict,
+    Mapping,
+    Set,
+)
 
 from griffe.logger import patch_loggers
 from markdown import Markdown
@@ -53,7 +64,7 @@ def __init__(self, *, base_dir: Path, **kwargs: Any) -> None:
     The theme to fall back to.
     """
 
-    default_config: dict = {
+    default_config = {
         "show_root_heading": False,
         "show_root_toc_entry": True,
         "show_root_full_path": True,
@@ -126,12 +137,10 @@ def load_inventory(
     def render(
         self,
         data: VbaModuleInfo,
-        config: dict,
+        config: Mapping[str, Any],
     ) -> str:
-        final_config = ChainMap(config, self.default_config)
-        render_type = "module"
-
-        template = self.env.get_template(f"{render_type}.html")
+        final_config = ChainMap(dict(copy.deepcopy(config)), self.default_config)
+        template = self.env.get_template(f"module.html")
 
         # Heading level is a "state" variable, that will change at each step
         # of the rendering recursion. Therefore, it's easier to use it as a plain value
@@ -148,18 +157,16 @@ def render(
         return template.render(
             **{
                 "config": final_config,
-                render_type: data,
+                "module": data,
                 "heading_level": heading_level,
                 "root": True,
             },
         )
 
-    def get_anchors(self, data: VbaModuleInfo) -> list[str]:
-        return list(
-            {data.path.as_posix(), *(p.signature.name for p in data.procedures)}
-        )
+    def get_anchors(self, data: VbaModuleInfo) -> Set[str]:
+        return {data.path.as_posix(), *(p.signature.name for p in data.procedures)}
 
-    def update_env(self, md: Markdown, config: dict) -> None:
+    def update_env(self, md: Markdown, config: Dict[Any, Any]) -> None:
         super().update_env(md, config)
         self.env.trim_blocks = True
         self.env.lstrip_blocks = True
@@ -171,7 +178,7 @@ def update_env(self, md: Markdown, config: dict) -> None:
     def collect(
         self,
         identifier: str,
-        config: dict,
+        config: MutableMapping[str, Any],
     ) -> VbaModuleInfo:
         """Collect the documentation tree given an identifier and selection options.
 
@@ -222,7 +229,7 @@ def get_handler(
         An instance of `VbaHandler`.
     """
     return VbaHandler(
-        base_dir=Path(config_file_path).parent,
+        base_dir=Path(config_file_path or ".").parent,
         handler="vba",
         theme=theme,
         custom_templates=custom_templates,

mkdocstrings_handlers/vba/_types.py

@@ -7,7 +7,6 @@
 
 @dataclass
 class VbaArgumentInfo:
-
     name: str
 
     optional: bool
@@ -18,7 +17,7 @@ class VbaArgumentInfo:
 
     default: Optional[str]
 
-    def render(self):
+    def render(self) -> str:
         parts = []
         if self.optional:
             parts.append("Optional")
@@ -43,7 +42,6 @@ class VbaSignatureInfo:
 
 @dataclass
 class VbaProcedureInfo:
-
     signature: VbaSignatureInfo
 
     docstring: Optional[Docstring]
@@ -67,7 +65,6 @@ def has_docstrings(self) -> bool:
 
 @dataclass
 class VbaModuleInfo:
-
     docstring: Optional[Docstring]
 
     source: List[str]

mkdocstrings_handlers/vba/_util.py

@@ -4,8 +4,8 @@
 from griffe.dataclasses import Docstring, Function, Parameters, Parameter
 from griffe.docstrings import Parser
 
-from mkdocstrings_handlers.vba._regex import re_signature, re_arg
-from mkdocstrings_handlers.vba._types import (
+from ._regex import re_signature, re_arg
+from ._types import (
     VbaArgumentInfo,
     VbaSignatureInfo,
     VbaProcedureInfo,
@@ -99,14 +99,14 @@ def parse_arg(arg: str) -> VbaArgumentInfo:
 
     if match is None:
         raise RuntimeError(f"Failed to parse argument: {arg}")
-    match = match.groupdict()
+    groups = match.groupdict()
 
     return VbaArgumentInfo(
-        optional=bool(match["optional"]),
-        modifier=match["modifier"],
-        name=match["name"],
-        arg_type=match["type"],
-        default=match["default"],
+        optional=bool(groups["optional"]),
+        modifier=groups["modifier"],
+        name=groups["name"],
+        arg_type=groups["type"],
+        default=groups["default"],
     )
 
 
@@ -120,14 +120,14 @@ def parse_signature(line: str) -> VbaSignatureInfo:
 
     if match is None:
         raise RuntimeError(f"Failed to parse signature: {line}")
-    match = match.groupdict()
+    groups = match.groupdict()
 
     return VbaSignatureInfo(
-        visibility=match["visibility"],
-        return_type=match["returnType"],
-        procedure_type=match["type"],
-        name=match["name"],
-        args=list(parse_args(match["args"] or "")),
+        visibility=groups["visibility"],
+        return_type=groups["returnType"],
+        procedure_type=groups["type"],
+        name=groups["name"],
+        args=list(parse_args(groups["args"] or "")),
     )
 
 

mypy-requirements.txt

@@ -0,0 +1,3 @@
+mypy==1.5.1
+types-setuptools
+types-Markdown

mypy.ini

@@ -0,0 +1,6 @@
+[mypy]
+strict = true
+exclude = build|venv
+
+# Because not all dependencies maintain `__all__`.
+implicit_reexport = true

test/test_examples.py

@@ -29,7 +29,7 @@ def tmp_build(config_file_path: Path) -> Generator[Path, None, None]:
 
 
 class TestExamples(unittest.TestCase):
-    def test_example1(self):
+    def test_example1(self) -> None:
         with tmp_build(examples_dir.joinpath("example1", "mkdocs.yml")) as tmp_dir:
             # TODO: Write assertions. For now, just check that it does not fail.
             pass