Migrate to repo-config (#488)

- Migrate to use `repo-config`
- Fix pylint false positive for `pydantic.parse_raw_as`
- Add more cross-linking to generated docs
- Drop dependency on the `toml` package
- Fix missing `import` in a code example
- Fix some typing issues in `src/conftest.py`
- Add explicit dependency to `types-protobuf`

Author: llucax

.cookiecutter-replay.json

@@ -0,0 +1,28 @@
+{
+  "cookiecutter": {
+    "type": "lib",
+    "name": "sdk",
+    "description": "A development kit to interact with the Frequenz development platform",
+    "title": "Frequenz Python SDK",
+    "keywords": "microgrid,actor,ml,machine-learning,ai",
+    "github_org": "frequenz-floss",
+    "license": "MIT",
+    "author_name": "Frequenz Energy-as-a-Service GmbH",
+    "author_email": "[email protected]",
+    "python_package": "frequenz.sdk",
+    "pypi_package_name": "frequenz-sdk",
+    "github_repo_name": "frequenz-sdk-python",
+    "default_codeowners": "@frequenz-floss/python-sdk-team",
+    "_extensions": [
+      "jinja2_time.TimeExtension",
+      "local_extensions.default_codeowners",
+      "local_extensions.github_repo_name",
+      "local_extensions.keywords",
+      "local_extensions.pypi_package_name",
+      "local_extensions.python_package",
+      "local_extensions.src_path",
+      "local_extensions.title"
+    ],
+    "_template": "gh:frequenz-floss/frequenz-repo-config-python"
+  }
+}

.github/RELEASE_NOTES.template.md

@@ -1,12 +1,12 @@
-# Release Notes
+# Frequenz Python SDK Release Notes
 
 ## Summary
 
 <!-- Here goes a general summary of what this release is about -->
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with --> 
+<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
 

.github/labeler.yml

@@ -20,7 +20,7 @@
   - "src/frequenz/sdk/_data_ingestion/**"
   - "src/frequenz/sdk/timeseries/**"
 
-"part:docs": 
+"part:docs":
   - "**/*.md"
   - "docs/**"
   - "examples/**"
@@ -40,12 +40,9 @@
   - "**/*.toml"
   - "**/*.yaml"
   - "**/*.yml"
-  - "*requirements*.txt"
   - ".git*"
   - ".git*/**"
+  - "docs/*.py"
   - CODEOWNERS
   - MANIFEST.in
-  - docs/mkdocstrings_autoapi.py
   - noxfile.py
-  - setup.cfg
-  - setup.py

.github/workflows/ci.yaml

@@ -1,9 +1,11 @@
-name: frequenz-sdk-python
+name: CI
 
 on:
   merge_group:
   pull_request:
   push:
+    # We need to explicitly include tags because otherwise when adding
+    # `branches-ignore` it will only trigger on branches.
     tags:
       - '*'
     branches-ignore:
@@ -14,10 +16,15 @@ on:
   workflow_dispatch:
 
 env:
+  # Please make sure this version is included in the `matrix`, as the
+  # `matrix` section can't use `env`, so it must be entered manually
   DEFAULT_PYTHON_VERSION: '3.11'
+  # It would be nice to be able to also define a DEFAULT_UBUNTU_VERSION
+  # but sadly `env` can't be used either in `runs-on`.
 
 jobs:
-  test:
+  nox:
+    name: Test with nox
     strategy:
       fail-fast: false
       matrix:
@@ -37,23 +44,19 @@ jobs:
           python-version: ${{ matrix.python }}
           cache: 'pip'
 
-      - uses: actions/cache@v3
-        with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-${{ matrix.python-version }}-pip-${{ hashFiles('minimum-requirements-ci.txt', 'pyproject.toml') }}
-          restore-keys: |
-            ${{ runner.os }}-${{ matrix.python-version }}-pip-
-
       - name: Install required Python packages
         run: |
           python -m pip install --upgrade pip
-          python -m pip install nox toml
+          python -m pip install -e .[dev-noxfile]
 
-      - name: run nox
+      - name: Run nox
+        # To speed things up a bit we use the speciall ci_checks_max session
+        # that uses the same venv to run multiple linting sessions
         run: nox -e ci_checks_max pytest_min
         timeout-minutes: 10
 
-  build-dist:
+  build:
+    name: Build distribution packages
     runs-on: ubuntu-20.04
     steps:
       - name: Fetch sources
@@ -62,25 +65,26 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v4
         with:
-          python-version: '3.11'
+          python-version: ${{ env.DEFAULT_PYTHON_VERSION }}
           cache: 'pip'
 
-      - name: Install build dependencies
+      - name: Install required Python packages
         run: |
           python -m pip install -U pip
           python -m pip install -U build
 
       - name: Build the source and binary distribution
         run: python -m build
 
-      - name: Upload dist files
+      - name: Upload distribution files
         uses: actions/upload-artifact@v3
         with:
-          name: frequenz-sdk-python-dist
+          name: dist-packages
           path: dist/
           if-no-files-found: error
 
-  test-generate-docs:
+  test-docs:
+    name: Test documentation website generation
     if: github.event_name != 'push'
     runs-on: ubuntu-20.04
     steps:
@@ -99,7 +103,7 @@ jobs:
       - name: Install build dependencies
         run: |
           python -m pip install -U pip
-          python -m pip install .[docs-gen]
+          python -m pip install .[dev-mkdocs]
 
       - name: Generate the documentation
         env:
@@ -111,12 +115,13 @@ jobs:
       - name: Upload site
         uses: actions/upload-artifact@v3
         with:
-          name: frequenz-channels-python-site
+          name: docs-site
           path: site/
           if-no-files-found: error
 
   publish-docs:
-    needs: ["test", "build-dist"]
+    name: Publish documentation website to GitHub pages
+    needs: ["nox", "build"]
     if: github.event_name == 'push'
     runs-on: ubuntu-20.04
     permissions:
@@ -178,7 +183,7 @@ jobs:
         if: steps.mike-metadata.outputs.version
         run: |
           python -m pip install -U pip
-          python -m pip install .[docs-gen]
+          python -m pip install .[dev-mkdocs]
 
       - name: Fetch the gh-pages branch
         if: steps.mike-metadata.outputs.version
@@ -193,6 +198,7 @@ jobs:
           mike deploy --push --update-aliases "$VERSION" $ALIASES
 
   create-github-release:
+    name: Create GitHub release
     needs: ["publish-docs"]
     # Create a release only on tags creation
     if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
@@ -203,10 +209,10 @@ jobs:
       discussions: write
     runs-on: ubuntu-20.04
     steps:
-      - name: Download dist files
+      - name: Download distribution files
         uses: actions/download-artifact@v3
         with:
-          name: frequenz-sdk-python-dist
+          name: dist-packages
           path: dist
 
       - name: Download RELEASE_NOTES.md
@@ -230,7 +236,6 @@ jobs:
           if echo "$REF_NAME" | grep -- -; then extra_opts=" --prerelease"; fi
           gh release create \
             -R "$REPOSITORY" \
-            --discussion-category announcements \
             --notes-file RELEASE_NOTES.md \
             --generate-notes \
             $extra_opts \
@@ -242,17 +247,18 @@ jobs:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
   publish-to-pypi:
+    name: Publish packages to PyPI
     needs: ["create-github-release"]
     runs-on: ubuntu-20.04
     permissions:
       # For trusted publishing. See:
       # https://blog.pypi.org/posts/2023-04-20-introducing-trusted-publishers/
       id-token: write
     steps:
-      - name: Download dist files
+      - name: Download distribution files
         uses: actions/download-artifact@v3
         with:
-          name: frequenz-sdk-python-dist
+          name: dist-packages
           path: dist
 
       - name: Publish the Python distribution to PyPI

.github/workflows/labeler.yml

@@ -1,13 +1,5 @@
 name: Pull Request Labeler
 
-# XXX: !!! SECURITY WARNING !!!
-# pull_request_target has write access to the repo, and can read secrets. We
-# need to audit any external actions executed in this workflow and make sure no
-# checked out code is run (not even installing dependencies, as installing
-# dependencies usually can execute pre/post-install scripts). We should also
-# only use hashes to pick the action to execute (instead of tags or branches).
-# For more details read:
-# https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
 on: [pull_request_target]
 
 jobs:
@@ -18,7 +10,14 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Labeler
-        # Only use hashes, see the security comment above
+        # XXX: !!! SECURITY WARNING !!!
+        # pull_request_target has write access to the repo, and can read secrets. We
+        # need to audit any external actions executed in this workflow and make sure no
+        # checked out code is run (not even installing dependencies, as installing
+        # dependencies usually can execute pre/post-install scripts). We should also
+        # only use hashes to pick the action to execute (instead of tags or branches).
+        # For more details read:
+        # https://securitylab.github.com/research/github-actions-preventing-pwn-requests/
         uses: actions/labeler@0967ca812e7fdc8f5f71402a1b486d5bd061fe20  # 4.2.0
         with:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"

.gitignore

@@ -114,6 +114,9 @@ venv/
 ENV/
 env.bak/
 venv.bak/
+# direnv https://github.com/direnv/direnv
+.envrc
+.direnv/
 
 # Spyder project settings
 .spyderproject

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to `frequenz-sdk`
+# Contributing to Frequenz Python SDK
 
 ## Build
 
@@ -28,7 +28,7 @@ If you don't want to install all the dependencies, you can also use `nox` to
 run the tests and other checks creating its own virtual environments:
 
 ```sh
-python -m pip install nox toml
+python -m pip install .[dev-noxfile]
 nox
 ```
 
@@ -41,23 +41,23 @@ For a better development test cycle you can install the runtime and test
 dependencies and run `pytest` manually.
 
 ```sh
-python -m pip install .[pytest]  # included in .[dev] too
+python -m pip install .[dev-pytest]  # included in .[dev] too
 
 # And for example
-pytest tests/test_sdk.py
+pytest tests/test_*.py
 ```
 
 Or you can use `nox`:
 
 ```sh
-nox -R -s pytest -- test/test_sdk.py
+nox -R -s pytest -- test/test_*.py
 ```
 
 The same appliest to `pylint` or `mypy` for example:
 
 ```sh
-nox -R -s pylint -- test/test_sdk.py
-nox -R -s mypy -- test/test_sdk.py
+nox -R -s pylint -- test/test_*.py
+nox -R -s mypy -- test/test_*.py
 ```
 
 ### Building the documentation
@@ -66,7 +66,7 @@ To build the documentation, first install the dependencies (if you didn't
 install all `dev` dependencies):
 
 ```sh
-python -m pip install -e .[docs-gen]
+python -m pip install -e .[dev-mkdocs]
 ```
 
 Then you can build the documentation (it will be written in the `site/`
@@ -122,28 +122,27 @@ These are the steps to create a new release:
 1. Get the latest head you want to create a release from.
 
 2. Update the `RELEASE_NOTES.md` file if it is not complete, up to date, and
-   clean from template comments (`<!-- ... ->`) and empty sections. Submit
-   a pull request if an update is needed, wait until it is merged, and update
-   the latest head you want to create a release from to get the new merged pull
+   remove template comments (`<!-- ... ->`) and empty sections. Submit a pull
+   request if an update is needed, wait until it is merged, and update the
+   latest head you want to create a release from to get the new merged pull
    request.
 
 3. Create a new signed tag using the release notes and
    a [semver](https://semver.org/) compatible version number with a `v` prefix,
    for example:
 
    ```sh
-   git tag -s -F RELEASE_NOTES.md v0.0.1
+   git tag -s --cleanup=whitespace -F RELEASE_NOTES.md v0.0.1
    ```
 
 4. Push the new tag.
 
 5. A GitHub action will test the tag and if all goes well it will create
    a [GitHub
    Release](https://github.com/frequenz-floss/frequenz-sdk-python/releases),
-   create a new
-   [announcement](https://github.com/frequenz-floss/frequenz-sdk-python/discussions/categories/announcements)
-   about the release, and upload a new package to
-   [PyPI](https://pypi.org/project/frequenz-sdk/) automatically.
+   and upload a new package to
+   [PyPI](https://pypi.org/project/frequenz-sdk/)
+   automatically.
 
 6. Once this is done, reset the `RELEASE_NOTES.md` with the template:
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Frequenz Energy-as-a-Service GmbH
+Copyright © 2022 Frequenz Energy-as-a-Service GmbH
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -4,6 +4,8 @@
 [![PyPI Package](https://img.shields.io/pypi/v/frequenz-sdk)](https://pypi.org/project/frequenz-sdk/)
 [![Docs](https://img.shields.io/badge/docs-latest-informational)](https://frequenz-floss.github.io/frequenz-sdk-python/)
 
+## Introduction
+
 A development kit to interact with the Frequenz development platform.
 
 ## Quick Start

RELEASE_NOTES.md

@@ -1,4 +1,4 @@
-# Release Notes
+# Frequenz Python SDK Release Notes
 
 ## Summary