Revamp config management (#1134)

This pull request adds a new `ConfigManager` class that takes care of
the *client-side* of the `ConfigManagingActor`, providing the common
tasks users of the config system need to do.

The class owns the config channel and provides a convenient method to
get new receivers that validate the configuration using a `dataclass` as
a `marshmallow` schema, and allow filtering to receive only
configuration for a specific key. The receiver also reports errors when
the configuration can't be properly loaded, and avoid spurious updates
when the configuration didn't change compared to the previous one.

The manager also takes care of instantiating both the
`ConfigManagingActor` and the `LoggingConfigUpdatingActor` and provides
a utility function to wait for the first configuration to be received.

RELEASE_NOTES.md

@@ -2,7 +2,7 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release includes a new `ConfigManager` class to simplify managing the configuration, and ships other improvements and fixes to the config system in general.
 
 ## Upgrading
 
@@ -11,7 +11,9 @@
     * `LoggingConfigUpdater`
 
         + Renamed to `LoggingConfigUpdatingActor` to follow the actor naming convention.
-        + Make all arguments to the constructor keyword-only.
+        + The actor must now be constructed using a `ConfigManager` instead of a receiver.
+        + Make all arguments to the constructor keyword-only, except for the `config_manager` argument.
+        + If the configuration is removed, the actor will now load back the default configuration.
 
     * `LoggingConfig`
 
@@ -31,12 +33,30 @@
          + The `base_schema` argument is now keyword-only.
          + The arguments forwarded to `marshmallow.Schema.load()` now must be passed explicitly via the `marshmallow_load_kwargs` argument, as a `dict`, to improve the type-checking.
 
+    * `ConfigManagingActor`: Raise a `ValueError` if the `config_files` argument an empty sequence.
+
 ## New Features
 
-- `LoggingConfigUpdatingActor`
+- `frequenz.sdk.config`
+
+    - Logging was improved in general.
+
+    - Added documentation and user guide.
+
+    - `LoggingConfigUpdatingActor`
 
-    * Added a new `name` argument to the constructor to be able to override the actor's name.
+        * Added a new `name` argument to the constructor to be able to override the actor's name.
+
+    - `ConfigManager`: Added a class to simplify managing the configuration. It takes care of instantiating the config actors and provides a convenient method for creating receivers with a lot of common functionality.
+
+    - `BaseConfigSchema`: Added a `marshmallow` base `Schema` that includes custom fields for `frequenz-quantities`. In the futute more commonly used fields might be added.
+
+    - `wait_for_first()`: Added a function to make it easy to wait for the first configuration to be received with a timeout.
+
+    - `ConfigManagingActor`: Allow passing a single configuration file.
 
 ## Bug Fixes
 
 - Fix a bug in `BackgroundService` where it won't try to `self.cancel()` and `await self.wait()` if there are no internal tasks. This prevented to properly implement custom stop logic without having to redefine the `stop()` method too.
+
+- Fix a bug where if a string was passed to the `ConfigManagingActor` it would be interpreted as a sequence of 1 character strings.

docs/user-guide/config.md

@@ -0,0 +1,9 @@
+# Configuration
+
+::: frequenz.sdk.config
+    options:
+        members: []
+        show_bases: false
+        show_root_heading: false
+        show_root_toc_entry: false
+        show_source: false

mkdocs.yml

@@ -119,6 +119,7 @@ plugins:
             - https://docs.python.org/3/objects.inv
             - https://frequenz-floss.github.io/frequenz-channels-python/v1.1/objects.inv
             - https://frequenz-floss.github.io/frequenz-client-microgrid-python/v0.5/objects.inv
+            - https://frequenz-floss.github.io/frequenz-quantities-python/v1/objects.inv
             - https://lovasoa.github.io/marshmallow_dataclass/html/objects.inv
             - https://marshmallow.readthedocs.io/en/stable/objects.inv
             - https://networkx.org/documentation/stable/objects.inv

pyproject.toml

@@ -30,8 +30,8 @@ dependencies = [
   # changing the version
   # (plugins.mkdocstrings.handlers.python.import)
   "frequenz-client-microgrid >= 0.6.0, < 0.7.0",
-  "frequenz-channels >= 1.2.0, < 2.0.0",
-  "frequenz-quantities >= 1.0.0rc3, < 2.0.0",
+  "frequenz-channels >= 1.4.0, < 2.0.0",
+  "frequenz-quantities[marshmallow] >= 1.0.0, < 2.0.0",
   "networkx >= 2.8, < 4",
   "numpy >= 1.26.4, < 2",
   "typing_extensions >= 4.6.1, < 5",