Split mypy check for the source package and dev files

`mypy` tends to have issues with checking source files inside a `src/`
directory. There are tricks[1] but it seems like the only way to do it
is to run `mypy` on `.` using `MYPYPATH=src`, which will still check the
whole `.` directory (include whole virtualenvs if there are any), which
is not what we want. For now we've been using `-p` to check for packages
instead of files, which seemed to have done the trick, but we need to
pass directories that don't really have a package structure (like
benchmarks or examples or tests) as packages, which is also not great.

This commit tries a different approach, we check the source code as a
package separately, and then check the development files (tests,
examples, etc.), which are passed as simple paths. This also opens up
the door to using more relaxed rules for these development files if
needed in the future.

To achieve this we also move the `packages` specification to the
`pyproject.toml` file, so now `mypy` can be called without any arguments
to check the source code package, making it easier to call it without
relaying in `nox`.

[1] https://mypy.readthedocs.io/en/stable/running_mypy.html#mapping-file-paths-to-modules

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

cookiecutter/{{cookiecutter.github_repo_name}}/pyproject.toml

@@ -170,6 +170,7 @@ testpaths = ["pytests"]
 [tool.mypy]
 explicit_package_bases = true
 namespace_packages = true
+packages = ["{{cookiecutter.python_package}}"]
 strict = true
 
 [[tool.mypy.overrides]]

pyproject.toml

@@ -152,6 +152,7 @@ disable = [
 [tool.mypy]
 explicit_package_bases = true
 namespace_packages = true
+packages = ["frequenz.repo.config"]
 strict = true
 
 [[tool.mypy.overrides]]

src/frequenz/repo/config/__init__.py

@@ -182,9 +182,13 @@
 [tool.mypy]
 explicit_package_bases = true
 namespace_packages = true
+packages = ["your_package_name"]  # Use the actual package name here
 strict = true
 ```
 
+You can just call `mypy` to check the package of your sources or you can use `mypy
+tests` to check the tests, for example.
+
 ## `mkdocs` (generating documentation)
 
 ### API reference generation

src/frequenz/repo/config/nox/config.py

@@ -114,7 +114,14 @@ def copy(self, /) -> Self:
             extra_paths=self.extra_paths.copy(),
         )
 
-    def path_args(self, session: _nox.Session, /) -> list[str]:
+    def path_args(
+        self,
+        session: _nox.Session,
+        /,
+        *,
+        include_sources: bool = True,
+        include_extra: bool = True,
+    ) -> list[str]:
         """Return the file paths to run the checks on.
 
         If positional arguments are present in the nox session, those are used
@@ -123,16 +130,22 @@ def path_args(self, session: _nox.Session, /) -> list[str]:
 
         Args:
             session: The nox session to use to look for command-line arguments.
+            include_sources: Whether to include the source paths or not.
+            include_extra: Whether to include the extra paths or not.
 
         Returns:
             The file paths to run the checks on.
         """
         if session.posargs:
             return session.posargs
 
-        return list(
-            str(p) for p in _util.existing_paths(self.source_paths + self.extra_paths)
-        )
+        paths: list[str] = []
+        if include_sources:
+            paths.extend(self.source_paths)
+        if include_extra:
+            paths.extend(self.extra_paths)
+
+        return list(str(p) for p in _util.existing_paths(paths))
 
     def package_args(self, session: _nox.Session, /) -> list[str]:
         """Return the package names to run the checks on.

src/frequenz/repo/config/nox/session.py

@@ -62,8 +62,22 @@ def mypy(session: nox.Session, install_deps: bool = True) -> None:
         session.install("-e", ".[dev-mypy]")
 
     conf = _config.get()
-    pkg_args = _util.flatten(("-p", p) for p in conf.package_args(session))
-    session.run("mypy", *conf.opts.mypy, *pkg_args)
+
+    # If we get CLI options, we run mypy on those, but still passing the
+    # configured options (they can be overridden by the CLI options).
+    if session.posargs:
+        session.run("mypy", *conf.opts.mypy, *session.posargs)
+        return
+
+    # We separate running the mypy checks into two runs, one is the default, as
+    # configured in `pyproject.toml`, which should run against the sources.
+    session.run("mypy", *conf.opts.mypy)
+
+    # The second run checks development files, like tests, benchmarks, etc.
+    # This is an attempt to minimize mypy internal errors.
+    session.run(
+        "mypy", *conf.opts.mypy, *conf.path_args(session, include_sources=False)
+    )
 
 
 @nox.session