Add a function to load configurations with correct type hints

When loading configurations from dictionaries, using
`marshmallow_dataclass`, the type hints are not preserved by the
`load()` method, leading to repetitive casting every time `load()` needs
to be used.

This commit adds a new `load_config()` function to the
`frequenz.sdk.config` module that takes care of loading configurations
from dictionaries into configuration classes with correct type hints.

Signed-off-by: Leandro Lucarella <[email protected]>

Author: llucax

RELEASE_NOTES.md

@@ -21,6 +21,7 @@
 ## New Features
 
 - The `ConfigManagingActor` can now take multiple configuration files as input, allowing to override default configurations with custom configurations.
+* A new `frequenz.sdk.config.load_config()` function is available to load configurations using `marshmallow_dataclass`es with correct type hints.
 - Implement and standardize logging configuration with the following changes:
    * Add `LoggerConfig` and `LoggingConfig` to standardize logging configuration.
    * Create `LoggingConfigUpdater` to handle runtime config updates.

src/frequenz/sdk/config/__init__.py

@@ -5,10 +5,12 @@
 
 from ._config_managing import ConfigManagingActor
 from ._logging_config_updater import LoggerConfig, LoggingConfig, LoggingConfigUpdater
+from ._util import load_config
 
 __all__ = [
     "ConfigManagingActor",
     "LoggingConfig",
     "LoggerConfig",
     "LoggingConfigUpdater",
+    "load_config",
 ]

src/frequenz/sdk/config/_util.py

@@ -0,0 +1,39 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Utilities to deal with configuration."""
+
+from collections.abc import Mapping
+from typing import Any, TypeVar, cast
+
+from marshmallow_dataclass import class_schema
+
+T = TypeVar("T")
+"""Type variable for configuration classes."""
+
+
+def load_config(
+    cls: type[T],
+    config: Mapping[str, Any],
+    /,
+    **marshmallow_load_kwargs: Any,
+) -> T:
+    """Load a configuration from a dictionary into an instance of a configuration class.
+
+    The configuration class is expected to be a [`marshmallow_dataclass.dataclass`][].
+    Additional arguments can be passed to [`marshmallow.Schema.load`][] using keyword
+    arguments.
+
+    Args:
+        cls: The configuration class.
+        config: The configuration dictionary.
+        **marshmallow_load_kwargs: Additional arguments to be passed to
+            [`marshmallow.Schema.load`][].
+
+    Returns:
+        The loaded configuration as an instance of the configuration class.
+    """
+    instance = class_schema(cls)().load(config, **marshmallow_load_kwargs)
+    # We need to cast because `.load()` comes from marshmallow and doesn't know which
+    # type is returned.
+    return cast(T, instance)

tests/config/test_util.py

@@ -0,0 +1,35 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for the config utilities."""
+
+from typing import Any
+
+import marshmallow_dataclass
+from pytest_mock import MockerFixture
+
+from frequenz.sdk.config._util import load_config
+
+
+@marshmallow_dataclass.dataclass
+class SimpleConfig:
+    """A simple configuration class for testing."""
+
+    name: str
+    value: int
+
+
+def test_load_config(mocker: MockerFixture) -> None:
+    """Test that load_config loads a configuration into a configuration class."""
+    mock_class_schema = mocker.Mock()
+    mock_class_schema.return_value.load.return_value = {"name": "test", "value": 42}
+    mocker.patch(
+        "frequenz.sdk.config._util.class_schema", return_value=mock_class_schema
+    )
+    config: dict[str, Any] = {}
+
+    # We add the type hint to test that the return type (hint) is correct
+    _: SimpleConfig = load_config(SimpleConfig, config, marshmallow_arg=1)
+    mock_class_schema.return_value.load.assert_called_once_with(
+        config, marshmallow_arg=1
+    )