Update linting (#113)

.github/workflows/ci.yml

@@ -14,6 +14,7 @@ concurrency:
 
 env:
   PIP_ROOT_USER_ACTION: ignore
+  COLUMNS: 200
 
 jobs:
   build:

.gitignore

@@ -6,9 +6,9 @@ _version.py
 /.python-version
 
 # Testing
-/.coverage
+/.coverage*
 /coverage.*
-/.pytest_cache/
+/.*cache/
 
 # Docs
 /docs/_build/

.pre-commit-config.yaml

@@ -4,7 +4,7 @@ repos:
     hooks:
       - id: trailing-whitespace
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.9
+    rev: v0.1.11
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
@@ -16,3 +16,11 @@ repos:
         additional_dependencies:
           - prettier@3.0.2
           - prettier-plugin-jinja-template@1.0.0
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.8.0
+    hooks:
+      - id: mypy
+        additional_dependencies:
+          - sphinx
+          - pytest
+          - types-docutils

.vscode/settings.json

@@ -1,14 +1,14 @@
 {
-    "python.testing.pytestArgs": ["-v", "--color=yes"],
+    "python.testing.pytestArgs": ["-vv", "--color=yes"],
     "python.testing.unittestEnabled": false,
     "python.testing.pytestEnabled": true,
     "python.terminal.activateEnvironment": false,
     "[python]": {
         "editor.defaultFormatter": "charliermarsh.ruff",
         "editor.formatOnSave": true,
         "editor.codeActionsOnSave": {
-            "source.fixAll": true,
-            "source.organizeImports": true,
+            "source.fixAll": "explicit",
+            "source.organizeImports": "explicit",
         },
     },
 }

docs/conf.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING
+from pathlib import PurePosixPath
 from datetime import datetime
 from datetime import timezone as tz
 from importlib.metadata import metadata
-from pathlib import PurePosixPath
-from typing import TYPE_CHECKING
 
 
 if TYPE_CHECKING:

pyproject.toml

@@ -45,7 +45,7 @@ theme = [
 [project.entry-points.'sphinx.html_themes']
 scanpydoc = 'scanpydoc.theme'
 
-[tool.ruff]
+[tool.ruff.lint]
 select = ['ALL']
 allowed-confusables = ['’', '×', 'l']
 ignore = [
@@ -57,8 +57,10 @@ ignore = [
     'D407',   # We’re not using Numpydoc style
     'FIX002', # TODOs are OK
     'PD',     # False positives
+    'COM812', # Conflicts with formatting
+    'ISC001', # Conflicts with formatting
 ]
-[tool.ruff.per-file-ignores]
+[tool.ruff.lint.per-file-ignores]
 'example.py' = ['ALL']
 'docs/conf.py' = [
     'INP001', # `docs` is not a namespace package
@@ -68,16 +70,25 @@ ignore = [
     'D103', # Test functions don’t need docstrings
     'S101', # Pytest tests use `assert`
 ]
-
-[tool.ruff.isort]
+[tool.ruff.lint.flake8-type-checking]
+strict = true
+[tool.ruff.lint.isort]
+length-sort = true
 lines-after-imports = 2
 known-first-party = ['scanpydoc']
 
+[tool.mypy]
+strict = true
+explicit_package_bases = true
+mypy_path = ['$MYPY_CONFIG_FILE_DIR/src']
+
 [tool.hatch.version]
 source = 'vcs'
 [tool.hatch.build.hooks.vcs]
 version-file = 'src/scanpydoc/_version.py'
 
+[tool.hatch.envs.default]
+dependencies = ['types-docutils']
 [tool.hatch.envs.docs]
 python = '3.11'
 features = ['doc']
@@ -101,6 +112,19 @@ addopts = [
     '-psphinx.testing.fixtures',
 ]
 
+[tool.coverage.run]
+source_pkgs = ["scanpydoc"]
+[tool.coverage.paths]
+scanpydoc = ["src/scanpydoc"]
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+[tool.coverage_rich]
+fail-under = 70
+
 [build-system]
 requires = ['hatchling', 'hatch-vcs']
 build-backend = 'hatchling.build'

src/scanpydoc/__init__.py

@@ -4,15 +4,14 @@
 """
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any, TypeVar
 from textwrap import indent
-from typing import TYPE_CHECKING, Any
+from collections.abc import Callable
 
 from ._version import __version__
 
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
-
     from sphinx.application import Sphinx
 
 
@@ -28,9 +27,11 @@
     :ref:`Metadata <sphinx:ext-metadata>` for this extension.
 """
 
+C = TypeVar("C", bound=Callable[..., Any])
+
 
-def _setup_sig(fn: Callable) -> Callable:
-    fn.__doc__ += "\n\n" + indent(setup_sig_str, " " * 4)
+def _setup_sig(fn: C) -> C:
+    fn.__doc__ = f"{fn.__doc__ or ''}\n\n{indent(setup_sig_str, ' ' * 4)}"
     return fn
 
 

src/scanpydoc/autosummary_generate_imported.py

@@ -13,13 +13,13 @@
 from __future__ import annotations
 
 import logging
-from pathlib import Path
 from typing import TYPE_CHECKING, Any
+from pathlib import Path
 
 from sphinx.ext import autosummary
 from sphinx.ext.autosummary.generate import generate_autosummary_docs
 
-from . import _setup_sig, metadata
+from . import metadata, _setup_sig
 
 
 if TYPE_CHECKING:
@@ -35,7 +35,7 @@ def _generate_stubs(app: Sphinx) -> None:
     if gen_files and not hasattr(gen_files, "__len__"):
         env = app.builder.env
         gen_files = [
-            env.doc2path(x, base=None)
+            env.doc2path(x, base=False)
             for x in env.found_docs
             if Path(env.doc2path(x)).is_file()
         ]
@@ -54,9 +54,6 @@ def _generate_stubs(app: Sphinx) -> None:
 
     generate_autosummary_docs(
         gen_files,
-        builder=app.builder,
-        warn=logger.warning,
-        info=logger.info,
         suffix=suffix,
         base_path=app.srcdir,
         imported_members=True,

src/scanpydoc/definition_list_typed_field.py

@@ -7,13 +7,13 @@
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, cast
 
-from docutils import nodes
 from sphinx import addnodes
+from docutils import nodes
 from sphinx.domains.python import PyObject, PyTypedField
 
-from . import _setup_sig, metadata
+from . import metadata, _setup_sig
 
 
 if TYPE_CHECKING:
@@ -37,34 +37,31 @@ class DLTypedField(PyTypedField):
     #: Override the list type
     list_type = nodes.definition_list
 
-    def make_field(
+    def make_field(  # type: ignore[override]
         self,
         types: dict[str, list[nodes.Node]],
         domain: str,
         items: tuple[str, list[nodes.inline]],
         env: BuildEnvironment | None = None,
-        **kw,  # noqa: ANN003
+        **kw: Any,  # noqa: ANN401
     ) -> nodes.field:
         """Render a field to a documenttree node representing a definition list item."""
 
         def make_refs(
-            role_name: str,
-            name: str,
-            node: type[TextLikeNode],
+            role_name: str, name: str, node: type[TextLikeNode]
         ) -> list[nodes.Node]:
             return self.make_xrefs(role_name, domain, name, node, env=env, **kw)
 
         def handle_item(
-            fieldarg: str,
-            content: list[nodes.inline],
+            fieldarg: str, content: list[nodes.inline]
         ) -> nodes.definition_list_item:
             term = nodes.term()
             term += make_refs(self.rolename, fieldarg, addnodes.literal_strong)
 
             field_type = types.pop(fieldarg, None)
             if field_type is not None:
                 if len(field_type) == 1 and isinstance(field_type[0], nodes.Text):
-                    (text_node,) = field_type  # type: nodes.Text
+                    [text_node] = cast(tuple[nodes.Text], field_type)
                     classifier_content = make_refs(
                         self.typerolename,
                         text_node.astext(),

src/scanpydoc/elegant_typehints/__init__.py

@@ -47,25 +47,25 @@ def x() -> Tuple[int, float]:
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+from pathlib import Path
+from functools import partial
 from collections import ChainMap
 from dataclasses import dataclass
-from functools import partial
-from pathlib import Path
-from typing import TYPE_CHECKING, Any
 
-from docutils.parsers.rst import roles
 from sphinx.ext.autodoc import ClassDocumenter
+from docutils.parsers.rst import roles
 
-from scanpydoc import _setup_sig, metadata
+from scanpydoc import metadata, _setup_sig
 
 from .example import example_func
 
 
 if TYPE_CHECKING:
     from collections.abc import Callable
 
-    from sphinx.application import Sphinx
     from sphinx.config import Config
+    from sphinx.application import Sphinx
 
 
 __all__ = ["example_func", "setup"]
@@ -96,12 +96,12 @@ def _init_vars(_app: Sphinx, config: Config) -> None:
         raise ValueError(msg)
     if config.typehints_defaults is None and config.annotate_defaults:
         # override default for “typehints_defaults”
-        config.typehints_defaults = "braces"
+        config.typehints_defaults = "braces"  # type: ignore[attr-defined]
 
 
 @dataclass
 class PickleableCallable:
-    func: Callable
+    func: Callable[..., Any]
 
     __call__ = property(lambda self: self.func)
 
@@ -124,7 +124,7 @@ def setup(app: Sphinx) -> dict[str, Any]:
 
     from ._autodoc_patch import dir_head_adder
 
-    ClassDocumenter.add_directive_header = dir_head_adder(
+    ClassDocumenter.add_directive_header = dir_head_adder(  # type: ignore[method-assign,assignment]
         qualname_overrides,
         ClassDocumenter.add_directive_header,
     )

src/scanpydoc/elegant_typehints/_autodoc_patch.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
-from functools import wraps
 from typing import TYPE_CHECKING
+from functools import wraps
 
 
 if TYPE_CHECKING:
-    from collections.abc import Callable, Mapping
+    from collections.abc import Mapping, Callable
 
-    from docutils.statemachine import StringList
     from sphinx.ext.autodoc import ClassDocumenter
+    from docutils.statemachine import StringList
 
 
 def dir_head_adder(
@@ -41,9 +41,7 @@ def add_directive_header(self: ClassDocumenter, sig: str) -> None:
 
 
 def replace_multi_suffix(
-    lines: StringList,
-    old: tuple[str, str],
-    new: tuple[str, str],
+    lines: StringList, old: tuple[str, str], new: tuple[str, str]
 ) -> None:
     if len(old) != len(new) != 2:  # noqa: PLR2004
         msg = "Only supports replacing 2 lines"