Add a setuptools support for building proto files (#1)

Author: llucax

.darglint

@@ -0,0 +1,2 @@
+[darglint]
+docstring_style=google

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,10 @@
+# Frequenz repository common configuration for Python
+
+This is very opinionated set of tools and configurations to setup a Python
+repository for Frequenz projects.
+
+If offers:
+
+* Trivial build of `noxfile.py` with some predefined sessions with all common
+  checks.
+* Tools to build protobuf/grpc files as Python, including type information.

pyproject.toml

@@ -4,10 +4,21 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "frequenz-repo-config"
-description = "Frequenz project setup tools and common configuration"
+description = "Frequenz repository setup tools and common configuration"
 readme = "README.md"
 license = { text = "MIT" }
-keywords = ["frequenz", "package", "project", "config", "tool"]
+keywords = [
+  "frequenz",
+  "package",
+  "project",
+  "config",
+  "tool",
+  "repository",
+  "setuptools",
+  "nox",
+  "grpc",
+  "protobuf",
+]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
@@ -26,6 +37,11 @@ name = "Frequenz Energy-as-a-Service GmbH"
 email = "[email protected]"
 
 [project.optional-dependencies]
+api = [
+  "grpcio-tools >= 1.47.0, < 2",
+  "mypy-protobuf >= 3.0.0, < 4",
+  "setuptools >= 67.6.0, < 68",
+]
 docs-gen = [
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.4.0",
@@ -38,6 +54,7 @@ docs-lint = ["pydocstyle == 6.3.0", "darglint == 1.8.1"]
 format = ["black == 23.3.0", "isort == 5.12.0"]
 mypy = [
   "mypy == 1.1.1",
+  "types-setuptools >= 67.6.0, < 68", # Should match the global dependency
   # For checking the docs/ script, and tests
   "frequenz-repo-config[docs-gen,pytest]",
 ]

src/frequenz/repo/config/__init__.py

@@ -1,10 +1,150 @@
 # License: MIT
 # Copyright © 2023 Frequenz Energy-as-a-Service GmbH
 
-"""Frequenz project setup tools and common configuration."""
+"""Frequenz project setup tools and common configuration.
 
-from . import nox
+The tools are provided to configure 4 main types of repositories:
+
+- APIs (api)
+- Actors (actor)
+- Applications (app)
+- Libraries (lib)
+
+# Common
+
+## `nox`
+
+Projects wanting to use `nox` to run lint checkers and other utilities can use
+the [`frequenz.repo.config.nox`][] package.
+
+Make sure to add this package as `dev` dependency to your project's
+`pyproject.tom` file, for example:
+
+```toml
+[project.optional-dependencies]
+nox = [
+    "nox == 2022.11.21",
+    "frequenz-repo-config[lib] == 0.1.0",
+]
+```
+
+Please note the `lib` optional dependency. Make sure you specify the correct
+one based on the type of your project (`api`, `actor`, `app`, `lib`). Also make
+sure to adjust the versions.
+
+When writing the `noxfile.py` you should import the `nox` module from this
+package and use the [`frequenz.repo.config.nox.configure`][] function,
+which will configure all nox sessions.
+
+You should call `configure()` using one of the default configurations provided
+in the [`frequenz.repo.config.nox.default`][] module. For example:
+
+```python
+from frequenz.repo import config
+
+config.nox.configure(config.nox.default.lib_config)
+```
+
+Again, make sure to pick the correct default configuration based on the type of
+your project (`api_config`, `actor_config`, `app_config`, `lib_config`).
+
+If you need to modify the configuration, you can copy one of the default
+configurations by using the
+[`copy()`][frequenz.repo.config.nox.config.Config.copy] method:
+
+```python
+from frequenz.repo import config
+
+conf = config.nox.default.lib_config.copy()
+conf.opts.black.append("--diff")
+config.nox.configure(conf)
+```
+
+If you need further customization or to define new sessions, you can use the
+following modules:
+
+- [`frequenz.repo.config.nox.config`][]: Low-level utilities to configure nox
+  sessions. It defines the `Config` and CommandsOptions` classes and the actual
+  implementation of the `configure()` function. It also defines the `get()`
+  function, which can be used to get the currently used configuration object.
+
+- [`frequenz.repo.config.nox.session`][]: Predefined nox sessions. These are
+  the sessions that are used by default.
+
+- [`frequenz.repo.config.nox.util`][]: General purpose utility functions.
+
+
+# APIs
+
+## `setuptools` gRPC support
+
+When configuring APIs it is assumed that they have a gRPC interface.
+
+Normally Frequenz APIs use basic types from
+[`google/api-common-protos`](https://github.com/googleapis/api-common-protos),
+so you need to make sure the proper submodule is added to your project:
+
+```sh
+mkdir submodules
+git submodule add https://github.com:googleapis/api-common-protos.git submodules/api-common-protos
+git commit -m "Add Google api-common-protos submodule" submodules/api-common-protos
+```
+
+Then you need to create a `setup.py` file with the following content:
+
+```py
+import setuptools
+
+from frequenz.repo.config.setuptools import grpc_tools
+
+if __name__ == "__main__":
+    setuptools.setup(cmdclass=grpc_tools.build_proto_cmdclass())
+```
+
+Then you need to add this package as a build dependency and a few extra
+dependencies to your project, for example:
+
+```toml
+requires = [
+  "setuptools >= 67.3.2, < 68",
+  "setuptools_scm[toml] >= 7.1.0, < 8",
+  "frequenz-repo-config[api] >= 0.1.0, < 0.2.0",
+]
+build-backend = "setuptools.build_meta"
+
+[project]
+dependencies = [
+  "googleapis-common-protos == 1.56.2",
+  "grpcio == 1.51.0",
+]
+```
+
+Note the `api` extra in `frequenz-repo-config[api]`, this will ensure all
+dependencies to build the protocol files will be installed when building the
+package. Of course you need to replace the version numbers with the correct
+ones too.
+
+Finally you need to make sure to include the generated `*.pyi` files in the
+source distribution, as well as the Google api-common-protos files, as it
+is not handled automatically yet
+([#13](https://github.com/frequenz-floss/frequenz-repo-config-python/issues/13)):
+
+```
+recursive-include py *.pyi
+recursive-include submodules/api-common-protos/google *.proto
+```
+
+If you need to customize how the protobuf files are compiled, you can pass
+a path to look for the protobuf files, a glob pattern to find the protobuf
+files, and a list of paths to include when compiling the protobuf files. By
+default `submodules/api-common-protos` is used as an include path, so if
+yout configured the submodules in a different path, you need to pass the
+correct path to the `include_paths` argument.
+"""
+
+from . import nox, setuptools
 
 __all__ = [
     "nox",
+    "setuptools",
 ]

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

@@ -1,6 +1,45 @@
-"""TODO."""
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
 
-from __future__ import annotations
+"""Utilities to build noxfiles.
+
+The main entry point is the [`configure()`][configure] function, which will
+configure all nox sessions according to some configuration.
+
+You should call `configure()` using one of the default configurations provided
+in the [`default`][] module. For example:
+
+```python
+from frequenz.repo import config
+
+config.nox.configure(config.nox.default.lib_config)
+```
+
+If you need to modify the configuration, you can copy one of the default
+configurations by using the
+[`copy()`][frequenz.repo.config.nox.config.Config.copy] method:
+
+```python
+from frequenz.repo import config
+
+conf = config.nox.default.lib_config.copy()
+conf.opts.black.append("--diff")
+config.nox.configure(conf)
+```
+
+If you need further customization or to define new sessions, you can use the
+following modules:
+
+- [`config`][]: Low-level utilities to configure nox sessions. It defines the
+  `Config` and CommandsOptions` classes and the actual implementation of the
+  `configure()` function. It also defines the `get()` function, which can be
+  used to get the currently used configuration object.
+
+- [`session`][]: Predefined nox sessions. These are the sessions that are used
+  by default.
+
+- [`util`][]: General purpose utility functions.
+"""
 
 from . import config, default, session, util
 from .config import configure