ci: Quality

Author: pawamoy

config/mypy.ini

@@ -3,3 +3,5 @@ ignore_missing_imports = true
 exclude = tests/fixtures/
 warn_unused_ignores = true
 show_error_codes = true
+namespace_packages = true
+explicit_package_bases = true

duties.py

@@ -124,6 +124,7 @@ def check_types(ctx: Context) -> None:
     Parameters:
         ctx: The context instance (passed automatically).
     """
+    os.environ["MYPYPATH"] = "src"
     ctx.run(
         mypy.run(*PY_SRC_LIST, config_file="config/mypy.ini"),
         title=pyprefix("Type-checking"),

mkdocs.yml

@@ -4,7 +4,7 @@ site_url: "https://mkdocstrings.github.io/python-legacy"
 repo_url: "https://github.com/mkdocstrings/python-legacy"
 repo_name: "mkdocstrings/python-legacy"
 site_dir: "site"
-watch: [mkdocs.yml, README.md, CONTRIBUTING.md, CHANGELOG.md, src/mkdocstrings]
+watch: [mkdocs.yml, README.md, CONTRIBUTING.md, CHANGELOG.md, src/mkdocstrings_handlers]
 copyright: Copyright © 2021 Timothée Mazzucotelli
 edit_uri: edit/main/docs/
 

src/mkdocstrings_handlers/python/handler.py

@@ -12,7 +12,7 @@
 import traceback
 from collections import ChainMap
 from subprocess import PIPE, Popen
-from typing import TYPE_CHECKING, Any, BinaryIO, Iterator
+from typing import TYPE_CHECKING, Any, BinaryIO, ClassVar, Iterator, Mapping, MutableMapping
 
 from mkdocstrings_handlers.python.rendering import (
     do_brief_xref,
@@ -48,7 +48,7 @@ class PythonHandler(BaseHandler):
     enable_inventory: bool = True
 
     fallback_theme = "material"
-    fallback_config = {"docstring_style": "markdown", "filters": ["!.*"]}
+    fallback_config: ClassVar[dict] = {"docstring_style": "markdown", "filters": ["!.*"]}
     """The configuration used when falling back to re-collecting an object to get its anchor.
 
     This configuration is used in [`Handlers.get_anchors`][mkdocstrings.handlers.base.Handlers.get_anchors].
@@ -63,7 +63,7 @@ class PythonHandler(BaseHandler):
     which we know will not generate any warnings.
     """
 
-    default_config: dict = {
+    default_config: ClassVar[dict] = {
         "filters": ["!^_[^_]"],
         "show_root_heading": False,
         "show_root_toc_entry": True,
@@ -122,11 +122,11 @@ class PythonHandler(BaseHandler):
 
     def __init__(
         self,
-        *args,
+        *args: Any,
         setup_commands: list[str] | None = None,
         config_file_path: str | None = None,
         paths: list[str] | None = None,
-        **kwargs,
+        **kwargs: Any,
     ) -> None:
         """Initialize the handler.
 
@@ -153,7 +153,7 @@ def __init__(
         search_paths = []
         for path in paths:
             if not os.path.isabs(path) and config_file_path:
-                path = os.path.abspath(os.path.join(os.path.dirname(config_file_path), path))
+                path = os.path.abspath(os.path.join(os.path.dirname(config_file_path), path))  # noqa: PLW2901
             if path not in search_paths:
                 search_paths.append(path)
         self._paths = search_paths
@@ -188,7 +188,7 @@ def __init__(
             cmd = [sys.executable, "-m", "pytkdocs", "--line-by-line"]
 
         self.process = Popen(
-            cmd,
+            cmd,  # noqa: S603
             universal_newlines=True,
             stdout=PIPE,
             stdin=PIPE,
@@ -203,7 +203,7 @@ def load_inventory(
         in_file: BinaryIO,
         url: str,
         base_url: str | None = None,
-        **kwargs,
+        **kwargs: Any,  # noqa: ARG003
     ) -> Iterator[tuple[str, str]]:
         """Yield items and their URLs from an inventory file streamed from `in_file`.
 
@@ -224,7 +224,7 @@ def load_inventory(
         for item in Inventory.parse_sphinx(in_file, domain_filter=("py",)).values():
             yield item.name, posixpath.join(base_url, item.uri)
 
-    def collect(self, identifier: str, config: dict) -> CollectorItem:
+    def collect(self, identifier: str, config: MutableMapping[str, Any]) -> CollectorItem:
         """Collect the documentation tree given an identifier and selection options.
 
         In this method, we feed one line of JSON to the standard input of the subprocess that was opened
@@ -265,11 +265,11 @@ def collect(self, identifier: str, config: dict) -> CollectorItem:
         json_input = json.dumps({"objects": [{"path": identifier, **final_config}]})
 
         logger.debug("Writing to process' stdin")
-        self.process.stdin.write(json_input + "\n")  # type: ignore
-        self.process.stdin.flush()  # type: ignore
+        self.process.stdin.write(json_input + "\n")  # type: ignore[union-attr]
+        self.process.stdin.flush()  # type: ignore[union-attr]
 
         logger.debug("Reading process' stdout")
-        stdout = self.process.stdout.readline()  # type: ignore
+        stdout = self.process.stdout.readline()  # type: ignore[union-attr]
 
         logger.debug("Loading JSON output as Python object")
         try:
@@ -304,8 +304,8 @@ def teardown(self) -> None:
         logger.debug("Tearing process down")
         self.process.terminate()
 
-    def render(self, data: CollectorItem, config: dict) -> str:  # noqa: D102 (ignore missing docstring)
-        final_config = ChainMap(config, self.default_config)
+    def render(self, data: CollectorItem, config: Mapping[str, Any]) -> str:  # noqa: D102 (ignore missing docstring)
+        final_config = ChainMap(config, self.default_config)  # type: ignore[arg-type]
 
         template = self.env.get_template(f"{data['category']}.html")
 
@@ -348,7 +348,7 @@ def get_handler(
     setup_commands: list[str] | None = None,
     config_file_path: str | None = None,
     paths: list[str] | None = None,
-    **config: Any,
+    **config: Any,  # noqa: ARG001
 ) -> PythonHandler:
     """Simply return an instance of `PythonHandler`.
 

tests/conftest.py

@@ -1,14 +1,23 @@
 """Configuration for the pytest test suite."""
 
+from __future__ import annotations
+
 from collections import ChainMap
+from typing import TYPE_CHECKING, Iterator
 
 import pytest
 from markdown.core import Markdown
 from mkdocs.config.defaults import MkDocsConfig
 
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from mkdocstrings.extension import MkdocstringsExtension
+    from mkdocstrings.plugin import MkdocstringsPlugin
+
 
 @pytest.fixture(name="mkdocs_conf")
-def fixture_mkdocs_conf(request, tmp_path):
+def fixture_mkdocs_conf(request: pytest.FixtureRequest, tmp_path: Path) -> Iterator[MkDocsConfig]:
     """Yield a MkDocs configuration object.
 
     Parameters:
@@ -45,7 +54,7 @@ def fixture_mkdocs_conf(request, tmp_path):
 
 
 @pytest.fixture(name="plugin")
-def fixture_plugin(mkdocs_conf):
+def fixture_plugin(mkdocs_conf: MkDocsConfig) -> MkdocstringsPlugin:
     """Return a plugin instance.
 
     Parameters:
@@ -60,7 +69,7 @@ def fixture_plugin(mkdocs_conf):
 
 
 @pytest.fixture(name="ext_markdown")
-def fixture_ext_markdown(plugin):
+def fixture_ext_markdown(plugin: MkdocstringsPlugin) -> MkdocstringsExtension:
     """Return a Markdown instance with MkdocstringsExtension.
 
     Parameters:
@@ -69,4 +78,4 @@ def fixture_ext_markdown(plugin):
     Returns:
         The plugin Markdown instance.
     """
-    return plugin.md
+    return plugin.md  # type: ignore[attr-defined]

tests/test_collector.py

@@ -15,14 +15,14 @@
         ({"error": "", "traceback": "hello"}, "\nhello"),
     ],
 )
-def test_collect_result_error(retval, exp_res):
+def test_collect_result_error(retval: dict, exp_res: str) -> None:
     """Test handling of errors when collecting an object.
 
     Args:
         retval: Return value to mock `json.loads` with.
         exp_res: Expected result.
     """
-    with mock.patch("mkdocstrings_handlers.python.handler.json.loads") as m_loads:
+    with mock.patch("mkdocstrings_handlers.python.handler.json.loads") as m_loads:  # noqa: SIM117
         with pytest.raises(CollectionError) as excinfo:  # noqa: PT012
             m_loads.return_value = retval
             handler = get_handler("material")

tests/test_renderer.py

@@ -1,5 +1,7 @@
 """Tests for the handlers.python module."""
 
+from __future__ import annotations
+
 from copy import deepcopy
 
 from mkdocstrings_handlers.python.rendering import (
@@ -10,9 +12,9 @@
 )
 
 
-def test_members_order():
+def test_members_order() -> None:
     """Assert that members sorting functions work correctly."""
-    subcategories = {key: [] for key in ("attributes", "classes", "functions", "methods", "modules")}
+    subcategories: dict[str, list] = {key: [] for key in ("attributes", "classes", "functions", "methods", "modules")}
     categories = {"children": {}, **subcategories}
     collected = {
         "name": "root",

tests/test_themes.py

@@ -1,8 +1,14 @@
 """Tests for the different themes we claim to support."""
 
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
 
 import pytest
 
+if TYPE_CHECKING:
+    from mkdocstrings.plugin import MkdocstringsPlugin
+
 
 @pytest.mark.parametrize(
     "plugin",
@@ -25,14 +31,14 @@
         "mkdocstrings_handlers.python.rendering",
     ],
 )
-def test_render_themes_templates(module, plugin):
+def test_render_themes_templates(module: str, plugin: MkdocstringsPlugin) -> None:
     """Test rendering of a given theme's templates.
 
     Parameters:
         module: The module to load and render (parametrized).
         plugin: The plugin instance (parametrized fixture).
     """
     handler = plugin.handlers.get_handler("python")
-    handler._update_env(plugin.md, plugin.handlers._config)
+    handler._update_env(plugin.md, plugin.handlers._config)  # type: ignore[attr-defined]
     data = handler.collect(module, {})
     handler.render(data, {})