Add a function to load configurations with correct type hints (#1097)

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.

Author: llucax

RELEASE_NOTES.md

@@ -21,9 +21,10 @@
 ## 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.
+   * Add `LoggerConfig` and `LoggingConfig` to standardize logging configuration.
+   * Create `LoggingConfigUpdater` to handle runtime config updates.
    * Support individual log level settings for each module.
 
 ## Bug Fixes

mkdocs.yml

@@ -119,6 +119,8 @@ 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://lovasoa.github.io/marshmallow_dataclass/html/objects.inv
+            - https://marshmallow.readthedocs.io/en/stable/objects.inv
             - https://networkx.org/documentation/stable/objects.inv
             - https://numpy.org/doc/stable/objects.inv
             - https://typing-extensions.readthedocs.io/en/stable/objects.inv

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,45 @@
+# 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 [`dataclasses.dataclass`][], which is
+    used to create a [`marshmallow.Schema`][] schema to validate the configuration
+    dictionary.
+
+    To customize the schema derived from the configuration dataclass, you can use
+    [`marshmallow_dataclass.dataclass`][] to specify extra metadata.
+
+    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,69 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Tests for the config utilities."""
+
+import dataclasses
+from typing import Any
+
+import marshmallow
+import marshmallow_dataclass
+import pytest
+from pytest_mock import MockerFixture
+
+from frequenz.sdk.config._util import load_config
+
+
+@dataclasses.dataclass
+class SimpleConfig:
+    """A simple configuration class for testing."""
+
+    name: str
+    value: int
+
+
+@marshmallow_dataclass.dataclass
+class MmSimpleConfig:
+    """A simple configuration class for testing."""
+
+    name: str = dataclasses.field(metadata={"validate": lambda s: s.startswith("test")})
+    value: int
+
+
+def test_load_config_dataclass() -> None:
+    """Test that load_config loads a configuration into a configuration class."""
+    config: dict[str, Any] = {"name": "test", "value": 42}
+
+    loaded_config = load_config(SimpleConfig, config)
+    assert loaded_config == SimpleConfig(name="test", value=42)
+
+    config["name"] = "not test"
+    loaded_config = load_config(SimpleConfig, config)
+    assert loaded_config == SimpleConfig(name="not test", value=42)
+
+
+def test_load_config_marshmallow_dataclass() -> None:
+    """Test that load_config loads a configuration into a configuration class."""
+    config: dict[str, Any] = {"name": "test", "value": 42}
+    loaded_config = load_config(MmSimpleConfig, config)
+    assert loaded_config == MmSimpleConfig(name="test", value=42)
+
+    config["name"] = "not test"
+    with pytest.raises(marshmallow.ValidationError):
+        _ = load_config(MmSimpleConfig, config)
+
+
+def test_load_config_type_hints(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
+    _: MmSimpleConfig = load_config(MmSimpleConfig, config, marshmallow_arg=1)
+    mock_class_schema.return_value.load.assert_called_once_with(
+        config, marshmallow_arg=1
+    )