WIP: Add full example in the config module.

Author: llucax

src/frequenz/sdk/config/__init__.py

@@ -1,7 +1,107 @@
 # License: MIT
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
-"""Configuration management."""
+"""Configuration management.
+
+Example: App configuring the global config manager.
+    ```python
+    import asyncio
+    import dataclasses
+    import logging
+    import sys
+
+    from collections.abc import Sequence
+    from typing import assert_never
+
+    import marshmallow
+
+    from frequenz.channels import select, selected_from
+    from frequenz.sdk.actor import Actor
+    from frequenz.sdk.config import (
+        ConfigManager,
+        LoggingConfigUpdatingActor,
+        wait_for_first
+    )
+
+    _logger = logging.getLogger(__name__)
+
+    @dataclasses.dataclass
+    class ActorConfig:
+        name: str
+
+    class MyActor(Actor):
+        def __init__(self, config_manager: ConfigManager, config_key: str | Sequence[str]) -> None:
+            super().__init__()
+            self._config_receiver = config_manager().new_receiver(config_key, ActorConfig)
+            self._receiver = ...
+
+        async def _run(self) -> None:
+            self._reconfigure(await wait_for_first(self._config_receiver))
+
+            async for selected in select(self._receiver, self._config_receiver):
+                if selected_from(selected, self._receiver):
+                    ...
+                elif selected_from(selected, self._config_receiver):
+                    self._reconfigure(selected.value)
+
+        def _reconfigure(self, config_update: ActorConfig | Exception | None) -> None:
+            match config_update:
+                case ActorConfig():
+                    _logger.info(
+                        "New configuration received, updating actor settings."
+                    )
+                    # ...
+                case None:
+                    _logger.info(
+                        "Configuration was unset, resetting to the default configuration."
+                    )
+                    # ...
+                case Exception():
+                    _logger.info(
+                        "New configuration has errors, keeping the old configuration."
+                    )
+                case unexpected:
+                    assert_never(unexpected)
+
+
+    @dataclasses.dataclass
+    class AppConfig:
+        positive_int: int = dataclasses.field(
+            default=42,
+            metadata={"validate": marshmallow.validate.Range(min=0)},
+        )
+
+    async def main() -> None:
+        async with ConfigManager(["config.toml"]) as config_manager:
+            receiver = config_manager.new_receiver("app", AppConfig)
+            try:
+                initial_config = await wait_for_first(receiver)
+            except asyncio.TimeoutError:
+                print("No configuration received in time")
+                sys.exit(1)
+
+            _logger.info("App initialized with %s", initial_config.positive_int)
+            actor = MyActor(config_manager, "actor")
+            actor.start()
+
+            # Keep listening for new configurations updates
+            async for config_update in receiver:
+                ...
+    ```
+
+    Example config:
+
+    ```toml
+    [app]
+    positive_int = 42
+
+    [actor]
+    name = "my_actor"
+
+    [logging.root_logger]
+    level = "DEBUG"
+    ```
+"""
 
 from ._logging_actor import LoggerConfig, LoggingConfig, LoggingConfigUpdatingActor
 from ._manager import ConfigManager, InvalidValueForKeyError, wait_for_first