Small fixes and improvements (#35)

- Add a core module with RepositoryType
- Add test to check for unexpected changes in repo types
- Add test for the `nox.default` module
- Test that pyproject.toml handles all repository types
- Improve description of supported repository types
- Sort repository types alphabetically
- Add support for "model" repositories
- Use sets for config paths and sessions
- Make imports private when only used internally

Author: llucax

noxfile.py

@@ -5,8 +5,4 @@
 
 from frequenz.repo.config import nox
 
-# Remove the pytest sessions because we don't have tests yet
-config = nox.default.lib_config.copy()
-config.sessions = [s for s in config.sessions if not s.startswith("pytest")]
-
-nox.configure(config)
+nox.configure(nox.default.lib_config)

pyproject.toml

@@ -48,6 +48,7 @@ api = [
 ]
 app = []
 lib = []
+model = []
 dev-docs-gen = [
   "mike == 1.1.2",
   "mkdocs-gen-files == 0.4.0",

src/frequenz/repo/config/__init__.py

@@ -3,12 +3,15 @@
 
 """Frequenz project setup tools and common configuration.
 
-The tools are provided to configure 4 main types of repositories:
+The tools are provided to configure the main types of repositories most commonly used at
+Frequenz, defined in
+[`freq.repo.config.RepositoryType`][freq.repo.config.RepositoryType].
 
-- APIs (api)
-- Actors (actor)
-- Applications (app)
-- Libraries (lib)
+- actor: SDK actors
+- api: gRPC APIs
+- app: SDK applications
+- lib: General purpose Python libraries
+- model: SDK machine learning models
 
 # Common
 
@@ -32,8 +35,8 @@
 nox.configure(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`).
+Again, make sure to pick the correct default configuration based on the type of your
+project (`actor_config`, `api_config`, `app_config`, `lib_config`, `model_config`).
 
 If you need to modify the configuration, you can copy one of the default
 configurations by using the
@@ -227,8 +230,10 @@
 """
 
 from . import nox, setuptools
+from ._core import RepositoryType
 
 __all__ = [
+    "RepositoryType",
     "nox",
     "setuptools",
 ]

src/frequenz/repo/config/_core.py

@@ -0,0 +1,25 @@
+# License: MIT
+# Copyright © 2023 Frequenz Energy-as-a-Service GmbH
+
+"""Base types used accross the project."""
+
+import enum as _enum
+
+
+class RepositoryType(_enum.Enum):
+    """Supported types of repository."""
+
+    ACTOR = "actor"
+    """SDK actor repository."""
+
+    API = "api"
+    """gRPC API repository."""
+
+    APP = "app"
+    """SDK application repository."""
+
+    LIB = "lib"
+    """General purpose library repository."""
+
+    MODEL = "model"
+    """SDK machine learning model repository."""

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

@@ -12,37 +12,37 @@
 The `configure()` function must be called before `get()` is used.
 """
 
-import dataclasses
+import dataclasses as _dataclasses
 from typing import Self
 
-import nox
+import nox as _nox
 
-from . import util
+from . import util as _util
 
 
-@dataclasses.dataclass(kw_only=True, slots=True)
+@_dataclasses.dataclass(kw_only=True, slots=True)
 class CommandsOptions:
     """Command-line options for each command."""
 
-    black: list[str] = dataclasses.field(default_factory=lambda: [])
+    black: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `black` command."""
 
-    darglint: list[str] = dataclasses.field(default_factory=lambda: [])
+    darglint: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `darglint` command."""
 
-    isort: list[str] = dataclasses.field(default_factory=lambda: [])
+    isort: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `isort` command."""
 
-    mypy: list[str] = dataclasses.field(default_factory=lambda: [])
+    mypy: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `mypy` command."""
 
-    pydocstyle: list[str] = dataclasses.field(default_factory=lambda: [])
+    pydocstyle: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `pydocstyle` command."""
 
-    pylint: list[str] = dataclasses.field(default_factory=lambda: [])
+    pylint: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `pylint` command."""
 
-    pytest: list[str] = dataclasses.field(default_factory=lambda: [])
+    pytest: list[str] = _dataclasses.field(default_factory=lambda: [])
     """Command-line options for the `pytest` command."""
 
     def copy(self) -> Self:
@@ -51,20 +51,20 @@ def copy(self) -> Self:
         Returns:
             The copy of self.
         """
-        return dataclasses.replace(self)
+        return _dataclasses.replace(self)
 
 
-@dataclasses.dataclass(kw_only=True, slots=True)
+@_dataclasses.dataclass(kw_only=True, slots=True)
 class Config:
     """Configuration for nox sessions."""
 
-    opts: CommandsOptions = dataclasses.field(default_factory=CommandsOptions)
+    opts: CommandsOptions = _dataclasses.field(default_factory=CommandsOptions)
     """Command-line options for each command used by sessions."""
 
-    sessions: list[str] = dataclasses.field(default_factory=lambda: [])
+    sessions: set[str] = _dataclasses.field(default_factory=set)
     """List of sessions to run."""
 
-    source_paths: list[str] = dataclasses.field(default_factory=lambda: [])
+    source_paths: set[str] = _dataclasses.field(default_factory=set)
     """List of paths containing source files that should be analyzed by the sessions.
 
     Source paths are inspected for `__init__.py` files to look for packages.
@@ -77,7 +77,7 @@ class Config:
     checking.
     """
 
-    extra_paths: list[str] = dataclasses.field(default_factory=lambda: [])
+    extra_paths: set[str] = _dataclasses.field(default_factory=set)
     """List of extra paths to be analyzed by the sessions.
 
     These are not inspected for packages, as they are passed verbatim to the
@@ -89,19 +89,19 @@ def __post_init__(self) -> None:
 
         This will add extra paths discovered in config files and other sources.
         """
-        for path in util.discover_paths():
+        for path in _util.discover_paths():
             if path not in self.extra_paths:
-                self.extra_paths.append(path)
+                self.extra_paths.add(path)
 
     def copy(self, /) -> Self:
         """Create a new object as a copy of self.
 
         Returns:
             The copy of self.
         """
-        return dataclasses.replace(self)
+        return _dataclasses.replace(self)
 
-    def path_args(self, session: nox.Session, /) -> list[str]:
+    def path_args(self, session: _nox.Session, /) -> set[str]:
         """Return the file paths to run the checks on.
 
         If positional arguments are present in the nox session, those are used
@@ -115,13 +115,13 @@ def path_args(self, session: nox.Session, /) -> list[str]:
             The file paths to run the checks on.
         """
         if session.posargs:
-            return session.posargs
+            return set(session.posargs)
 
-        return [
-            str(p) for p in util.existing_paths(self.source_paths + self.extra_paths)
-        ]
+        return {
+            str(p) for p in _util.existing_paths(self.source_paths | self.extra_paths)
+        }
 
-    def package_args(self, session: nox.Session, /) -> list[str]:
+    def package_args(self, session: _nox.Session, /) -> set[str]:
         """Return the package names to run the checks on.
 
         If positional arguments are present in the nox session, those are used
@@ -138,24 +138,24 @@ def package_args(self, session: nox.Session, /) -> list[str]:
             The package names found in the `source_paths`.
         """
         if session.posargs:
-            return session.posargs
+            return set(session.posargs)
 
         sources_package_dirs_with_roots = (
-            (p, util.find_toplevel_package_dirs(p))
-            for p in util.existing_paths(self.source_paths)
+            (p, _util.find_toplevel_package_dirs(p))
+            for p in _util.existing_paths(self.source_paths)
         )
 
         source_packages = (
-            util.path_to_package(pkg_path, root=root)
+            _util.path_to_package(pkg_path, root=root)
             for root, pkg_paths in sources_package_dirs_with_roots
             for pkg_path in pkg_paths
         )
 
         extra_packages = (
-            util.path_to_package(p) for p in util.existing_paths(self.extra_paths)
+            _util.path_to_package(p) for p in _util.existing_paths(self.extra_paths)
         )
 
-        return [*source_packages, *extra_packages]
+        return {*source_packages, *extra_packages}
 
 
 _config: Config | None = None
@@ -182,4 +182,4 @@ def configure(conf: Config, /) -> None:
     """
     global _config  # pylint: disable=global-statement
     _config = conf
-    nox.options.sessions = _config.sessions
+    _nox.options.sessions = _config.sessions

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

@@ -3,23 +3,20 @@
 
 """Default nox configuration for different types of repositories.
 
-This module provides the default configuration for different types of
-repositories:
+This module provides the default configuration for the different types of
+repositories defined by
+[`frequenz.repo.config.RepositoryType`][frequenz.repo.config.RepositoryType].
 
-- Libraries (lib)
-- APIs (api)
-- Actors (actor)
-- Applications (app)
+The `actor_config`, `api_config`, `app_config`, `lib_config`, and `model_config`
+variables are the default configurations for libraries, APIs, actors and applications,
+respectively. The `common_config` variable is the default configuration for all types of
+repositories.
 
-The `lib_config`, `api_config`, `actor_config` and `app_config`
-variables are the default configurations for libraries, APIs, actors and
-applications, respectively. The `common_config` variable is the default
-configuration for all types of repositories.
-
-The `lib_command_options`, `api_command_options`, `actor_command_options` and
-`app_command_options` variables are the default command-line options for the same
-types of repositories, and the `common_command_options` variable is the default
-command-line options for all types of repositories.
+The `actor_command_options`, `api_command_options`, `app_command_options`,
+`lib_command_options`, and `model_command_options` variables are the default
+command-line options for the same types of repositories, and the
+`common_command_options` variable is the default command-line options for all types of
+repositories.
 
 They can be modified before being passed to
 [`nox.configure()`][frequenz.repo.config.nox.configure] by using the
@@ -30,7 +27,7 @@
 import dataclasses
 
 from . import config as _config
-from . import util
+from . import util as _util
 
 common_command_options: _config.CommandsOptions = _config.CommandsOptions(
     black=[
@@ -59,32 +56,32 @@
 
 common_config = _config.Config(
     opts=common_command_options.copy(),
-    sessions=[
+    sessions={
         "formatting",
         "mypy",
         "pylint",
         "docstrings",
         "pytest_min",
         "pytest_max",
-    ],
-    source_paths=[
+    },
+    source_paths={
         "src",
-    ],
-    extra_paths=[
+    },
+    extra_paths={
         "benchmarks",
         "docs",
         "examples",
         "noxfile.py",
         "tests",
-    ],
+    },
 )
 """Default configuration for all types of repositories."""
 
-lib_command_options: _config.CommandsOptions = common_command_options.copy()
-"""Default command-line options for libraries."""
+actor_command_options: _config.CommandsOptions = common_command_options.copy()
+"""Default command-line options for actors."""
 
-lib_config: _config.Config = common_config.copy()
-"""Default configuration for libraries."""
+actor_config: _config.Config = common_config.copy()
+"""Default configuration for actors."""
 
 api_command_options: _config.CommandsOptions = common_command_options.copy()
 """Default command-line options for APIs."""
@@ -93,24 +90,30 @@
     common_config,
     opts=api_command_options,
     # We don't check the sources at all because they are automatically generated.
-    source_paths=[],
+    source_paths=set(),
     # We adapt the path to the tests.
-    extra_paths=list(util.replace(common_config.extra_paths, {"tests": "pytests"})),
+    extra_paths=set(_util.replace(common_config.extra_paths, {"tests": "pytests"})),
 )
 """Default configuration for APIs.
 
 Same as `common_config`, but with `source_paths` replacing `"src"` with `"py"`
 and `extra_paths` replacing `"tests"` with `"pytests"`.
 """
 
-actor_command_options: _config.CommandsOptions = common_command_options.copy()
-"""Default command-line options for actors."""
-
-actor_config: _config.Config = common_config.copy()
-"""Default configuration for actors."""
-
 app_command_options: _config.CommandsOptions = common_command_options.copy()
 """Default command-line options for applications."""
 
 app_config: _config.Config = common_config.copy()
 """Default configuration for applications."""
+
+lib_command_options: _config.CommandsOptions = common_command_options.copy()
+"""Default command-line options for libraries."""
+
+lib_config: _config.Config = common_config.copy()
+"""Default configuration for libraries."""
+
+model_command_options: _config.CommandsOptions = common_command_options.copy()
+"""Default command-line options for models."""
+
+model_config: _config.Config = common_config.copy()
+"""Default configuration for models."""