Replace darglint with pydoclint

MANIFEST.in

@@ -1,5 +1,4 @@
 exclude .cookiecutter-replay.json
-exclude .darglint
 exclude .editorconfig
 exclude .gitignore
 exclude CODEOWNERS

RELEASE_NOTES.md

@@ -6,25 +6,36 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+- `flake8` basic checks are enabled now. Most are already covered by `pylint`, but there are a few differences, so you might need to fix your code if `flake8` find some issues.
+
+- `darglint` was replaced by `pydoclint`, `pydoclint` can find a few more issues than `darglint`, so your code might need adjusting.
+
+- `darglint` is not used anymore, but if it is installed, it will make `flake8` run extremely slowly anyways, so it is extremely recommended to uninstall it (`pip uninstall darglint`) and rebuild you `nox` *venvs* if you use `-R`.
+
+- If you are upgrading without regenerating the cookiecutter templates, you'll need to adjust the dependencies accordingly.
 
 ### Cookiecutter template
 
-<!-- Here upgrade steps for cookiecutter specifically -->
+- CI: The `nox` job now uses a matrix to run the different `nox` sessions in parallel. If you use branch projection with the `nox` job you need to update the rules to include each matrix job.
+
+- See the general upgrading section.
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+- `flake8` is now used to check the files.
 
-### Cookiecutter template
+- `darlint` was replaced by `pydoclint`, which is way faster and detect more issues.
 
+### Cookiecutter template
 
 - Now dependabot updates will be done weekly and grouped by *required* and *optional* for minor and patch updates (major updates are still done individually for each dependency).
 
 - ci: Add debug information when installing pip packages.
 
   The output of `pip freeze` is printed to be able to more easily debug different behaviours between GitHub workflow runs and local runs.
 
+- See the general new features section.
+
 ## Bug Fixes
 
 <!-- Here goes notable bug fixes that are worth a special mention or explanation -->

cookiecutter/local_extensions.py

@@ -230,7 +230,8 @@ def introduction(
 
 Welcome to repo-config Cookiecutter template!
 
-This template will help you to create a new repository for your project. You will be asked to provide some information about your project.
+This template will help you to create a new repository for your project. \
+You will be asked to provide some information about your project.
 
 Here is an explanation of what each variable is for and will be used for:
 

cookiecutter/{{cookiecutter.github_repo_name}}/MANIFEST.in

@@ -1,5 +1,4 @@
 exclude .cookiecutter-replay.json
-exclude .darglint
 exclude .editorconfig
 exclude .gitignore
 {%- if cookiecutter.type == "api" %}

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

@@ -60,10 +60,12 @@ email = "{{cookiecutter.author_email}}"
 
 # TODO(cookiecutter): Remove and add more optional dependencies if appropriate
 [project.optional-dependencies]
-dev-docstrings = [
+dev-flake8 = [
+  "flake8 == 6.1.0",
+  "flake8-docstrings == 1.7.0",
+  "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.3.0",
   "pydocstyle == 6.3.0",
-  "darglint == 1.8.1",
-  "tomli == 2.0.1",      # Needed by pydocstyle to read pyproject.toml
 ]
 dev-formatting = ["black == 23.7.0", "isort == 5.12.0"]
 dev-mkdocs = [
@@ -99,7 +101,7 @@ dev-pytest = [
 {%- endif %}
 ]
 dev = [
-  "{{cookiecutter.pypi_package_name}}[dev-mkdocs,dev-docstrings,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+  "{{cookiecutter.pypi_package_name}}[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
 ]
 
 [project.urls]
@@ -121,6 +123,23 @@ line_length = 88
 {#- We don't include "py" here for API because we don't want to check generated files #}
 src_paths = ["benchmarks", "examples", "src", "tests"]
 
+[tool.flake8]
+# We give some flexibility to go over 88, there are cases like long URLs or
+# code in documenation that have extra indentation. Black will still take care
+# of making everything that can be 88 wide, 88 wide.
+max-line-length = 100
+extend-ignore = [
+  "E203", # Whitespace before ':' (conflicts with black)
+  "W503", # Line break before binary operator (conflicts with black)
+]
+# pydoclint options
+style = "google"
+check-return-types = false
+check-yield-types = false
+arg-type-hints-in-docstring = false
+arg-type-hints-in-signature = true
+allow-init-docstring = true
+
 [tool.pylint.similarities]
 ignore-comments = ['yes']
 ignore-docstrings = ['yes']

pyproject.toml

@@ -61,10 +61,12 @@ extra-lint-examples = [
   "pytest >= 7.3.0, < 8",
   "sybil >= 5.0.3, < 6",
 ]
-dev-docstrings = [
+dev-flake8 = [
+  "flake8 == 6.1.0",
+  "flake8-docstrings == 1.7.0",
+  "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.3.0",
   "pydocstyle == 6.3.0",
-  "darglint == 1.8.1",
-  "tomli == 2.0.1",      # Needed by pydocstyle to read pyproject.toml
 ]
 dev-formatting = ["black == 23.7.0", "isort == 5.12.0"]
 dev-mkdocs = [
@@ -94,7 +96,7 @@ dev-pytest = [
   "sybil == 5.0.3",        # Should be consistent with the extra-lint-examples dependency
 ]
 dev = [
-  "frequenz-repo-config[dev-mkdocs,dev-docstrings,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+  "frequenz-repo-config[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
 ]
 
 [project.urls]
@@ -113,6 +115,23 @@ profile = "black"
 line_length = 88
 src_paths = ["benchmarks", "examples", "src", "tests"]
 
+[tool.flake8]
+# We give some flexibility to go over 88, there are cases like long URLs or
+# code in documenation that have extra indentation. Black will still take care
+# of making everything that can be 88 wide, 88 wide.
+max-line-length = 100
+extend-ignore = [
+  "E203", # Whitespace before ':' (conflicts with black)
+  "W503", # Line break before binary operator (conflicts with black)
+]
+# pydoclint options
+style = "google"
+check-return-types = false
+check-yield-types = false
+arg-type-hints-in-docstring = false
+arg-type-hints-in-signature = true
+allow-init-docstring = true
+
 [tool.pylint.similarities]
 ignore-comments = ['yes']
 ignore-docstrings = ['yes']

src/frequenz/repo/config/__init__.py

@@ -73,12 +73,12 @@
 
 The following optional dependencies are used and must be defined:
 
-- `dev-docstrings`: Dependencies to lint the documentation.
+- `dev-flake8`: Dependencies to do flake8 lint, including the documentation.
 
   At least these packages should be included:
 
   - `pydocstyle`: To check the docstrings' format.
-  - `darglint`: To check the docstrings' content.
+  - `pydoclint`: To check the docstrings' content.
 
 - `dev-formatting`: Dependencies to check the code's formatting.
 
@@ -130,7 +130,13 @@
 # ...
 
 [project.optional-dependencies]
-dev-docstrings = ["pydocstyle == 6.3.0", "darglint == 1.8.1"]
+dev-flake8 = [
+  "flake8 == 6.1.0",
+  "flake8-docstrings == 1.7.0",
+  "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.2.4",
+  "pydocstyle == 6.3.0",
+]
 dev-formatting = ["black == 23.3.0", "isort == 5.12.0"]
 dev-mkdocs = [
   "mike == 1.1.2",
@@ -157,7 +163,7 @@
   "pytest-mock == 3.10.0",
 ]
 dev = [
-  "my-package[dev-mkdocs,dev-docstrings,dev-formatting,dev-mypy,dev-nox,dev-pylint,dev-pytest]",
+  "my-package[dev-mkdocs,dev-flake8,dev-formatting,dev-mypy,dev-nox,dev-pylint,dev-pytest]",
 ]
 ```
 

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

@@ -29,18 +29,15 @@ class CommandsOptions:
     black: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `black` command."""
 
-    darglint: list[str] = _dataclasses.field(default_factory=lambda: [])
-    """Command-line options for the `darglint` command."""
+    flake8: list[str] = _dataclasses.field(default_factory=lambda: [])
+    """Command-line options for the `flake8` command."""
 
     isort: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `isort` command."""
 
     mypy: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `mypy` command."""
 
-    pydocstyle: list[str] = _dataclasses.field(default_factory=lambda: [])
-    """Command-line options for the `pydocstyle` command."""
-
     pylint: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `pylint` command."""
 
@@ -56,10 +53,9 @@ def copy(self) -> Self:
         return _dataclasses.replace(
             self,
             black=self.black.copy(),
-            darglint=self.darglint.copy(),
+            flake8=self.flake8.copy(),
             isort=self.isort.copy(),
             mypy=self.mypy.copy(),
-            pydocstyle=self.pydocstyle.copy(),
             pylint=self.pylint.copy(),
             pytest=self.pytest.copy(),
         )
@@ -239,7 +235,7 @@ def configure(
     # We need to make sure sessions are imported, otherwise they won't be visible to nox.
     if import_default_sessions:
         # pylint: disable=import-outside-toplevel,cyclic-import
-        from . import session as _
+        from . import session as _  # noqa: F401
 
     match conf:
         case Config():

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

@@ -30,9 +30,7 @@
     black=[
         "--check",
     ],
-    darglint=[
-        "-v2",  # for verbose error messages.
-    ],
+    flake8=[],
     isort=[
         "--diff",
         "--check",
@@ -56,9 +54,9 @@
     opts=common_command_options.copy(),
     sessions=[
         "formatting",
+        "flake8",
         "mypy",
         "pylint",
-        "docstrings",
         "pytest_min",
         "pytest_max",
     ],

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

@@ -28,7 +28,7 @@ def ci_checks_max(session: nox.Session) -> None:
     formatting(session, False)
     mypy(session, False)
     pylint(session, False)
-    docstrings(session, False)
+    flake8(session, False)
     pytest_max(session, False)
 
 
@@ -84,30 +84,18 @@ def pylint(session: nox.Session, install_deps: bool = True) -> None:
 
 
 @nox.session
-def docstrings(session: nox.Session, install_deps: bool = True) -> None:
-    """Check docstring tone with pydocstyle and param descriptions with darglint.
+def flake8(session: nox.Session, install_deps: bool = True) -> None:
+    """Check for common errors and in particular documentation format and style.
 
     Args:
         session: the nox session.
         install_deps: True if dependencies should be installed.
     """
     if install_deps:
-        session.install("-e", ".[dev-docstrings]")
+        session.install("-e", ".[dev-flake8]")
 
     conf = _config.get()
-    session.run("pydocstyle", *conf.opts.pydocstyle, *conf.path_args(session))
-
-    # Darglint checks that function argument and return values are documented.
-    # This is needed only for the `src` dir, so we exclude the other top level
-    # dirs that contain code, unless some paths were specified by argument, in
-    # which case we use those untouched.
-    darglint_paths = session.posargs or filter(
-        # pylint: disable=fixme
-        # TODO: Make these exclusions configurable
-        lambda path: not (path.startswith("tests") or path.startswith("benchmarks")),
-        conf.path_args(session),
-    )
-    session.run("darglint", *conf.opts.darglint, *darglint_paths)
+    session.run("flake8", *conf.opts.flake8, *conf.path_args(session))
 
 
 @nox.session

src/frequenz/repo/config/setuptools/grpc_tools.py

@@ -13,7 +13,6 @@
 import pathlib as _pathlib
 import subprocess as _subprocess
 import sys as _sys
-import tomllib as _tomllib
 
 import setuptools as _setuptools
 import setuptools.command.build as _build_command

tests/integration/test_cookiecutter_generation.py

@@ -154,6 +154,7 @@ def _write_golden_file(golden_path: pathlib.Path, name: str, contents: str) -> i
     Args:
         golden_path: The path to the directory containing the golden files.
         name: The name of the golden file.
+        contents: The contents of the golden file to write.
 
     Returns:
         The number of bytes written.
@@ -259,9 +260,9 @@ def _filter_generation_output(
     the generated repo (a temporary directory).
     """
     stdout = b"\n".join(
-        l
-        for l in result.stdout.splitlines()
-        if not l.startswith((b"WARNING: The replay file's `_template` (",))
+        line
+        for line in result.stdout.splitlines()
+        if not line.startswith((b"WARNING: The replay file's `_template` (",))
     )
     return stdout, result.stderr
 

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/MANIFEST.in

@@ -1,5 +1,4 @@
 exclude .cookiecutter-replay.json
-exclude .darglint
 exclude .editorconfig
 exclude .gitignore
 exclude CODEOWNERS

tests_golden/integration/test_cookiecutter_generation/actor/frequenz-actor-test/pyproject.toml

@@ -42,10 +42,12 @@ email = "floss@frequenz.com"
 
 # TODO(cookiecutter): Remove and add more optional dependencies if appropriate
 [project.optional-dependencies]
-dev-docstrings = [
+dev-flake8 = [
+  "flake8 == 6.1.0",
+  "flake8-docstrings == 1.7.0",
+  "flake8-pyproject == 1.2.3",  # For reading the flake8 config from pyproject.toml
+  "pydoclint == 0.3.0",
   "pydocstyle == 6.3.0",
-  "darglint == 1.8.1",
-  "tomli == 2.0.1",      # Needed by pydocstyle to read pyproject.toml
 ]
 dev-formatting = ["black == 23.7.0", "isort == 5.12.0"]
 dev-mkdocs = [
@@ -79,7 +81,7 @@ dev-pytest = [
   "async-solipsism == 0.5",
 ]
 dev = [
-  "frequenz-actor-test[dev-mkdocs,dev-docstrings,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+  "frequenz-actor-test[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
 ]
 
 [project.urls]
@@ -98,6 +100,23 @@ profile = "black"
 line_length = 88
 src_paths = ["benchmarks", "examples", "src", "tests"]
 
+[tool.flake8]
+# We give some flexibility to go over 88, there are cases like long URLs or
+# code in documenation that have extra indentation. Black will still take care
+# of making everything that can be 88 wide, 88 wide.
+max-line-length = 100
+extend-ignore = [
+  "E203", # Whitespace before ':' (conflicts with black)
+  "W503", # Line break before binary operator (conflicts with black)
+]
+# pydoclint options
+style = "google"
+check-return-types = false
+check-yield-types = false
+arg-type-hints-in-docstring = false
+arg-type-hints-in-signature = true
+allow-init-docstring = true
+
 [tool.pylint.similarities]
 ignore-comments = ['yes']
 ignore-docstrings = ['yes']