Upgrade to repo-config v0.6.1 (#620)

The new repo-config version brings a few important changes:

* Dependabot grouping
* Replace `darglint` with `pydoclint`
* Introduction of `flake8` basic checks
* Start checking docstrings and `flake8` basic checks in tests and
benchmarks

Becuase of this, this PR is very big, as it needs to fix a lot of issues
detected by `pydoclint` and `flake8`.

The first commits, up to **Add `mypy` configuration to
`pyproject.toml`** deal with the upgrade of repo-config templates.

The rest of the commits are documentation fixes (first from `pydoclint`
and then from `pydocstyle`) plus some other `flake8` fixes, usually in
that order.

Author: llucax

.github/dependabot.yml

@@ -3,7 +3,7 @@ updates:
   - package-ecosystem: "pip"
     directory: "/"
     schedule:
-      interval: "daily"
+      interval: "weekly"
       time: "07:00"
     labels:
       - "part:tooling"
@@ -13,11 +13,28 @@ updates:
     versioning-strategy: auto
     # Allow up to 10 open pull requests for updates to dependency versions
     open-pull-requests-limit: 10
+    # We group production and development ("optional" in the context of
+    # pyproject.toml) dependency updates when they are patch and minor updates,
+    # so we end up with less PRs being generated.
+    # Major updates are still managed, but they'll create one PR per
+    # dependency, as major updates are expected to be breaking, it is better to
+    # manage them individually.
+    groups:
+      required:
+        dependency-type: "production"
+        update-types:
+          - "minor"
+          - "patch"
+      optional:
+        dependency-type: "development"
+        update-types:
+          - "minor"
+          - "patch"
 
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:
-      interval: "daily"
+      interval: "weekly"
       time: "06:00"
     labels:
       - "part:tooling"

.github/workflows/ci.yaml

@@ -32,9 +32,17 @@ jobs:
           - ubuntu-20.04
         python:
           - "3.11"
+        nox-session:
+          # To speed things up a bit we use the special ci_checks_max session
+          # that uses the same venv to run multiple linting sessions
+          - "ci_checks_max"
+          - "pytest_min"
     runs-on: ${{ matrix.os }}
 
     steps:
+      - name: Print environment (debug)
+        run: env
+
       - name: Fetch sources
         uses: actions/checkout@v3
         with:
@@ -50,11 +58,25 @@ jobs:
         run: |
           python -m pip install --upgrade pip
           python -m pip install -e .[dev-noxfile]
+          pip freeze
+
+      - name: Create nox venv
+        env:
+          NOX_SESSION: ${{ matrix.nox-session }}
+        run: nox --install-only -e "$NOX_SESSION"
+
+      - name: Print pip freeze for nox venv (debug)
+        env:
+          NOX_SESSION: ${{ matrix.nox-session }}
+        run: |
+          . ".nox/$NOX_SESSION/bin/activate"
+          pip freeze
+          deactivate
 
       - name: Run nox
-        # To speed things up a bit we use the special ci_checks_max session
-        # that uses the same venv to run multiple linting sessions
-        run: nox -e ci_checks_max pytest_min
+        env:
+          NOX_SESSION: ${{ matrix.nox-session }}
+        run: nox -R -e "$NOX_SESSION"
         timeout-minutes: 10
 
   build:
@@ -76,6 +98,7 @@ jobs:
         run: |
           python -m pip install -U pip
           python -m pip install -U build
+          pip freeze
 
       - name: Build the source and binary distribution
         run: python -m build
@@ -135,6 +158,7 @@ jobs:
         run: |
           python -m pip install -U pip
           python -m pip install .[dev-mkdocs]
+          pip freeze
 
       - name: Generate the documentation
         env:
@@ -217,6 +241,7 @@ jobs:
         run: |
           python -m pip install -U pip
           python -m pip install .[dev-mkdocs]
+          pip freeze
 
       - name: Fetch the gh-pages branch
         if: steps.mike-metadata.outputs.version

MANIFEST.in

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

benchmarks/power_distribution/power_distributor.py

@@ -36,7 +36,6 @@ async def send_requests(batteries: Set[int], request_num: int) -> List[Result]:
     """Send requests to the PowerDistributingActor and wait for the response.
 
     Args:
-        user: user that should send request
         batteries: set of batteries where the power should be set
         request_num: number of requests that should be send
 

benchmarks/timeseries/benchmark_ringbuffer.py

@@ -39,8 +39,7 @@ def test_days(days: int, buffer: OrderedRingBuffer[Any]) -> None:
     basetime = datetime(2022, 1, 1, tzinfo=timezone.utc)
 
     for day in range(days):
-        # pylint: disable=unused-variable
-        minutes = buffer.window(
+        _ = buffer.window(
             basetime + timedelta(days=day), basetime + timedelta(days=day + 1)
         )
 

benchmarks/timeseries/periodic_feature_extractor.py

@@ -64,7 +64,6 @@ def _calculate_avg_window(
         feature_extractor: The instance of the PeriodicFeatureExtractor to use.
         window: The window to calculate the average over.
         window_size: The size of the window to calculate the average over.
-        weights: The weights to use for the average calculation.
 
     Returns:
         The averaged window.
@@ -113,6 +112,7 @@ def _num_windows(
         Args:
             window: The buffer that is used for the average calculation.
             window_size: The size of the window in samples.
+            period: The distance between two succeeding intervals in samples.
 
         Returns:
             The number of windows that are fully contained in the MovingWindow.
@@ -168,7 +168,7 @@ def run_avg_np(
         The return value is discarded such that it can be used by timit.
 
         Args:
-            a: The array containing all data.
+            array: The array containing all data.
             window_size: The size of the window.
             feature_extractor: An instance of the PeriodicFeatureExtractor.
         """
@@ -185,7 +185,7 @@ def run_avg_py(
         The return value is discarded such that it can be used by timit.
 
         Args:
-            a: The array containing all data.
+            array: The array containing all data.
             window_size: The size of the window.
             feature_extractor: An instance of the PeriodicFeatureExtractor.
         """

benchmarks/timeseries/ringbuffer_serialization.py

@@ -45,6 +45,9 @@ def benchmark_serialization(
     Args:
         ringbuffer: Ringbuffer to benchmark to serialize.
         iterations: amount of iterations to run.
+
+    Returns:
+        Average time to dump and load the ringbuffer.
     """
     total = 0.0
     for _ in range(iterations):

pyproject.toml

@@ -5,7 +5,7 @@
 requires = [
   "setuptools == 68.1.0",
   "setuptools_scm[toml] == 7.1.0",
-  "frequenz-repo-config[lib] == 0.5.2",
+  "frequenz-repo-config[lib] == 0.6.1",
 ]
 build-backend = "setuptools.build_meta"
 
@@ -49,10 +49,12 @@ name = "Frequenz Energy-as-a-Service GmbH"
 email = "[email protected]"
 
 [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.1",
   "pydocstyle == 6.3.0",
-  "darglint == 1.8.1",
-  "tomli == 2.0.1",      # Needed by pydocstyle to read pyproject.toml
 ]
 dev-examples = ["polars == 0.18.15"]
 dev-formatting = ["black == 23.7.0", "isort == 5.12.0"]
@@ -63,35 +65,40 @@ dev-mkdocs = [
   "mkdocs-material == 9.2.5",
   "mkdocs-section-index == 0.3.5",
   "mkdocstrings[python] == 0.22.0",
-  "frequenz-repo-config[lib] == 0.5.2",
+  "frequenz-repo-config[lib] == 0.6.1",
 ]
 dev-mypy = [
   "mypy == 1.5.1",
-  "grpc-stubs == 1.24.12",      # This dependency introduces breaking changes in patch releases
+  "grpc-stubs == 1.24.12",              # This dependency introduces breaking changes in patch releases
+  "types-Markdown == 3.4.2.10",
+  "types-PyYAML == 6.0.12.11",
+  "types-Pygments == 2.16.0.0",
+  "types-colorama == 0.4.15.12",
   "types-protobuf == 4.24.0.1",
+  "types-python-dateutil == 2.8.19.14",
+  "types-pytz == 2023.3.0.1",
+  "types-setuptools == 68.1.0.0",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-sdk[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
-dev-noxfile = ["nox == 2023.4.22", "frequenz-repo-config[lib] == 0.5.2"]
+dev-noxfile = ["nox == 2023.4.22", "frequenz-repo-config[lib] == 0.6.1"]
 dev-pylint = [
   "pylint == 2.17.5",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-sdk[dev-mkdocs,dev-noxfile,dev-pytest]",
 ]
 dev-pytest = [
   "pytest == 7.4.0",
-  "frequenz-repo-config[extra-lint-examples] == 0.5.2",
+  "frequenz-repo-config[extra-lint-examples] == 0.6.1",
   "pytest-mock == 3.11.1",
   "pytest-asyncio == 0.21.1",
   "time-machine == 2.12.0",
   "async-solipsism == 0.5",
   # For checking docstring code examples
-  "sybil == 5.0.3",
-  "pylint == 2.17.5",
   "frequenz-sdk[dev-examples]",
 ]
 dev = [
-  "frequenz-sdk[dev-mkdocs,dev-docstrings,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
+  "frequenz-sdk[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
 ]
 
 [project.urls]
@@ -110,6 +117,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"
+allow-init-docstring = true
+arg-type-hints-in-docstring = false
+arg-type-hints-in-signature = true
+check-return-types = false
+check-yield-types = false
+
 [tool.pylint.similarities]
 ignore-comments = ['yes']
 ignore-docstrings = ['yes']
@@ -125,6 +149,10 @@ disable = [
   # pylint's unsubscriptable check is buggy and is not needed because
   # it is a type-check, for which we already have mypy.
   "unsubscriptable-object",
+  # Checked by flake8
+  "line-too-long",
+  "unused-variable",
+  "unnecessary-lambda-assignment",
 ]
 
 [tool.pylint.design]

src/frequenz/sdk/actor/_run_utils.py

@@ -16,7 +16,7 @@ async def run(*actors: Actor) -> None:
     """Await the completion of all actors.
 
     Args:
-        actors: the actors to be awaited.
+        *actors: the actors to be awaited.
     """
     _logger.info("Starting %s actor(s)...", len(actors))
 

src/frequenz/sdk/actor/power_distributing/_battery_pool_status.py

@@ -70,7 +70,7 @@ class BatteryPoolStatus:
     Send set of working and uncertain batteries, when the any battery change status.
     """
 
-    def __init__(
+    def __init__(  # noqa: DOC502 (RuntimeError is raised indirectly by BatteryStatus)
         self,
         battery_ids: Set[int],
         battery_status_sender: Sender[BatteryStatus],