WIP: Revamp config management

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",

src/frequenz/sdk/config/__init__.py

@@ -1,13 +1,78 @@
 # License: MIT
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
-"""Read and update config variables."""
+"""Configuration management.
+
+Example: App configuring the global config manager.
+    ```python
+    import asyncio
+    import dataclasses
+    import sys
+
+    import marshmallow
+
+    from frequenz.channels import select, selected_from
+    from frequenz.sdk.actor import Actor
+    from frequenz.sdk.config import (
+        initialize_config,
+        config_manager,
+        LoggingConfigUpdatingActor,
+        ConfigManager,
+    )
+
+    @dataclasses.dataclass
+    class ActorConfig:
+        name: str
+
+    class MyActor(Actor):
+        def __init__(self, config: ActorConfig) -> None:
+            self._config = config
+            super().__init__()
+
+        async def _run(self) -> None:
+            receiver = ...
+            config_receiver = await config_manager().new_receiver(schema=ActorConfig)
+
+            async for selected in select(receiver, config_receiver):
+                if selected_from(selected, receiver):
+                    ...
+                elif selected_from(selected, config_receiver):
+                    self._config = selected.message
+                    # Restart whatever is needed after a config update
+
+
+    @dataclasses.dataclass
+    class AppConfig:
+        positive_int: int = dataclasses.field(
+            default=42,
+            metadata={"validate": marshmallow.validate.Range(min=0)},
+        )
+        my_actor: ActorConfig | None = None
+        logging: LoggingConfig = LoggingConfig()
+
+    async def main() -> None:
+        config_manager = initialize_config_manager(["config.toml"])
+        try:
+            # Receive the first configuration
+            initial_config = await config_manager.new_receiver(schema=AppConfig,
+                                                                  wait_for_first=True)
+        except asyncio.TimeoutError:
+            print("No configuration received in time")
+            sys.exit(1)
+
+        actor = MyActor(ActorConfig(name=initial_config.my_actor))
+        actor.start()
+        await actor
+    ```
+"""
 
 from ._logging_actor import LoggerConfig, LoggingConfig, LoggingConfigUpdatingActor
+from ._manager import ConfigManager
 from ._managing_actor import ConfigManagingActor
 from ._util import load_config
 
 __all__ = [
+    "ConfigManager",
     "ConfigManagingActor",
     "LoggerConfig",
     "LoggingConfig",

src/frequenz/sdk/config/_base_schema.py

@@ -0,0 +1,10 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Base schema for configuration classes."""
+
+from frequenz.quantities.experimental.marshmallow import QuantitySchema
+
+
+class BaseConfigSchema(QuantitySchema):
+    """A base schema for configuration classes."""