Implement SetComponentPowerActive/Reactive

These 2 calls are identically, they just affect active or reactive power
respectively, so there are a few utility function that are shared, as
well as test cases.

For test cases we need to use a couple of hacks to share them.

* `*_case.py` files for `set_reactive_power` are symlinks to
    `set_active_power()`
* Both have their own `_config.py` file where we define the classes used
    for the tests, so we can share them, as only the request/response
    objects change between both.
* Because of the client test framework works, `_config` must be imported
    as a top-level module.
* We need to ignore `pylint` and `mypy` checks when importing, as they
    can't find the `_config` module at the top-level.

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

Author: llucax

src/frequenz/client/microgrid/_client.py

@@ -7,18 +7,21 @@
 
 import asyncio
 import itertools
+import math
 from dataclasses import replace
-from typing import Any
+from datetime import datetime, timedelta
+from typing import Any, assert_never
 
-from frequenz.api.microgrid.v1 import microgrid_pb2_grpc
-from frequenz.client.base import channel, client, retry, streaming
+from frequenz.api.microgrid.v1 import microgrid_pb2, microgrid_pb2_grpc
+from frequenz.client.base import channel, client, conversion, retry, streaming
 from frequenz.client.common.microgrid.components import ComponentId
 from google.protobuf.empty_pb2 import Empty
 from typing_extensions import override
 
 from ._exception import ClientNotConnected
 from ._microgrid_info import MicrogridInfo
 from ._microgrid_info_proto import microgrid_info_from_proto
+from .component._component import Component
 
 DEFAULT_GRPC_CALL_TIMEOUT = 60.0
 """The default timeout for gRPC calls made by this client (in seconds)."""
@@ -153,3 +156,182 @@ async def get_microgrid_info(  # noqa: DOC502 (raises ApiClientError indirectly)
         )
 
         return microgrid_info_from_proto(microgrid.microgrid)
+
+    async def set_component_power_active(  # noqa: DOC502 (raises ApiClientError indirectly)
+        self,
+        component: ComponentId | Component,
+        power: float,
+        *,
+        request_lifetime: timedelta | None = None,
+        validate_arguments: bool = True,
+    ) -> datetime | None:
+        """Set the active power output of a component.
+
+        The power output can be negative or positive, depending on whether the component
+        is supposed to be discharging or charging, respectively.
+
+        The power output is specified in watts.
+
+        The return value is the timestamp until which the given power command will
+        stay in effect. After this timestamp, the component's active power will be
+        set to 0, if the API receives no further command to change it before then.
+        By default, this timestamp will be set to the current time plus 60 seconds.
+
+        Note:
+            The target component may have a resolution of more than 1 W. E.g., an
+            inverter may have a resolution of 88 W. In such cases, the magnitude of
+            power will be floored to the nearest multiple of the resolution.
+
+        Args:
+            component: The component to set the output active power of.
+            power: The output active power level, in watts. Negative values are for
+                discharging, and positive values are for charging.
+            request_lifetime: The duration, until which the request will stay in effect.
+                This duration has to be between 10 seconds and 15 minutes (including
+                both limits), otherwise the request will be rejected. It has
+                a resolution of a second, so fractions of a second will be rounded for
+                `timedelta` objects, and it is interpreted as seconds for `int` objects.
+                If not provided, it usually defaults to 60 seconds.
+            validate_arguments: Whether to validate the arguments before sending the
+                request. If `True` a `ValueError` will be raised if an argument is
+                invalid without even sending the request to the server, if `False`, the
+                request will be sent without validation.
+
+        Returns:
+            The timestamp until which the given power command will stay in effect, or
+                `None` if it was not provided by the server.
+
+        Raises:
+            ApiClientError: If there are any errors communicating with the Microgrid API,
+                most likely a subclass of
+                [GrpcError][frequenz.client.microgrid.GrpcError].
+        """
+        lifetime_seconds = _delta_to_seconds(request_lifetime)
+
+        if validate_arguments:
+            _validate_set_power_args(power=power, request_lifetime=lifetime_seconds)
+
+        response = await client.call_stub_method(
+            self,
+            lambda: self.stub.SetComponentPowerActive(
+                microgrid_pb2.SetComponentPowerActiveRequest(
+                    component_id=_get_component_id(component),
+                    power=power,
+                    request_lifetime=lifetime_seconds,
+                ),
+                timeout=DEFAULT_GRPC_CALL_TIMEOUT,
+            ),
+            method_name="SetComponentPowerActive",
+        )
+
+        if response.HasField("valid_until"):
+            return conversion.to_datetime(response.valid_until)
+
+        return None
+
+    async def set_component_power_reactive(  # noqa: DOC502 (raises ApiClientError indirectly)
+        self,
+        component: ComponentId | Component,
+        power: float,
+        *,
+        request_lifetime: timedelta | None = None,
+        validate_arguments: bool = True,
+    ) -> datetime | None:
+        """Set the reactive power output of a component.
+
+        We follow the polarity specified in the IEEE 1459-2010 standard
+        definitions, where:
+
+        - Positive reactive is inductive (current is lagging the voltage)
+        - Negative reactive is capacitive (current is leading the voltage)
+
+        The power output is specified in VAr.
+
+        The return value is the timestamp until which the given power command will
+        stay in effect. After this timestamp, the component's reactive power will
+        be set to 0, if the API receives no further command to change it before
+        then. By default, this timestamp will be set to the current time plus 60
+        seconds.
+
+        Note:
+            The target component may have a resolution of more than 1 VAr. E.g., an
+            inverter may have a resolution of 88 VAr. In such cases, the magnitude of
+            power will be floored to the nearest multiple of the resolution.
+
+        Args:
+            component: The component to set the output reactive power of.
+            power: The output reactive power level, in VAr. The standard of polarity is
+                as per the IEEE 1459-2010 standard definitions: positive reactive is
+                inductive (current is lagging the voltage); negative reactive is
+                capacitive (current is leading the voltage).
+            request_lifetime: The duration, until which the request will stay in effect.
+                This duration has to be between 10 seconds and 15 minutes (including
+                both limits), otherwise the request will be rejected. It has
+                a resolution of a second, so fractions of a second will be rounded for
+                `timedelta` objects, and it is interpreted as seconds for `int` objects.
+                If not provided, it usually defaults to 60 seconds.
+            validate_arguments: Whether to validate the arguments before sending the
+                request. If `True` a `ValueError` will be raised if an argument is
+                invalid without even sending the request to the server, if `False`, the
+                request will be sent without validation.
+
+        Returns:
+            The timestamp until which the given power command will stay in effect, or
+                `None` if it was not provided by the server.
+
+        Raises:
+            ApiClientError: If there are any errors communicating with the Microgrid API,
+                most likely a subclass of
+                [GrpcError][frequenz.client.microgrid.GrpcError].
+        """
+        lifetime_seconds = _delta_to_seconds(request_lifetime)
+
+        if validate_arguments:
+            _validate_set_power_args(power=power, request_lifetime=lifetime_seconds)
+
+        response = await client.call_stub_method(
+            self,
+            lambda: self.stub.SetComponentPowerReactive(
+                microgrid_pb2.SetComponentPowerReactiveRequest(
+                    component_id=_get_component_id(component),
+                    power=power,
+                    request_lifetime=lifetime_seconds,
+                ),
+                timeout=DEFAULT_GRPC_CALL_TIMEOUT,
+            ),
+            method_name="SetComponentPowerReactive",
+        )
+
+        if response.HasField("valid_until"):
+            return conversion.to_datetime(response.valid_until)
+
+        return None
+
+
+def _get_component_id(component: ComponentId | Component) -> int:
+    """Get the component ID from a component or component ID."""
+    match component:
+        case ComponentId():
+            return int(component)
+        case Component():
+            return int(component.id)
+        case unexpected:
+            assert_never(unexpected)
+
+
+def _delta_to_seconds(delta: timedelta | None) -> int | None:
+    """Convert a `timedelta` to seconds (or `None` if `None`)."""
+    return round(delta.total_seconds()) if delta is not None else None
+
+
+def _validate_set_power_args(*, power: float, request_lifetime: int | None) -> None:
+    """Validate the request lifetime."""
+    if math.isnan(power):
+        raise ValueError("power cannot be NaN")
+    if request_lifetime is not None:
+        minimum_lifetime = 10  # 10 seconds
+        maximum_lifetime = 900  # 15 minutes
+        if not minimum_lifetime <= request_lifetime <= maximum_lifetime:
+            raise ValueError(
+                "request_lifetime must be between 10 seconds and 15 minutes"
+            )

tests/client_test_cases/set_component_power_active/_config.py

@@ -0,0 +1,9 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Configuration for `SetComponentPowerActive` test cases."""
+
+
+from frequenz.api.microgrid.v1 import microgrid_pb2
+
+RESPONSE_CLASS = microgrid_pb2.SetComponentPowerActiveResponse

tests/client_test_cases/set_component_power_active/invalid_big_lifetime_case.py

@@ -0,0 +1,31 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test case with invalid power and validate_arguments=False."""
+
+from datetime import timedelta
+from unittest.mock import AsyncMock
+
+# pylint: disable-next=import-error
+from _config import RESPONSE_CLASS  # type: ignore[import-not-found]
+from frequenz.client.common.microgrid.components import ComponentId
+
+client_kwargs = {
+    "component": ComponentId(1),
+    "power": 1000.0,
+    "request_lifetime": timedelta(minutes=15.01),
+}
+
+
+def assert_stub_method_call(stub_method: AsyncMock) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    stub_method.assert_not_called()
+
+
+grpc_response = RESPONSE_CLASS()
+
+
+def assert_client_exception(result: Exception) -> None:
+    """Assert that the client raises a ValueError."""
+    assert isinstance(result, ValueError)
+    assert str(result) == "request_lifetime must be between 10 seconds and 15 minutes"

tests/client_test_cases/set_component_power_active/invalid_power_case.py

@@ -0,0 +1,31 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test case with invalid power and validate_arguments=False."""
+
+from datetime import timedelta
+from unittest.mock import AsyncMock
+
+# pylint: disable-next=import-error
+from _config import RESPONSE_CLASS  # type: ignore[import-not-found]
+from frequenz.client.common.microgrid.components import ComponentId
+
+client_kwargs = {
+    "component": ComponentId(1),
+    "power": float("nan"),
+    "request_lifetime": timedelta(seconds=60),
+}
+
+
+def assert_stub_method_call(stub_method: AsyncMock) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    stub_method.assert_not_called()
+
+
+grpc_response = RESPONSE_CLASS()
+
+
+def assert_client_exception(result: Exception) -> None:
+    """Assert that the client raises a ValueError."""
+    assert isinstance(result, ValueError)
+    assert str(result) == "power cannot be NaN"

tests/client_test_cases/set_component_power_active/invalid_power_no_validate_case.py

@@ -0,0 +1,40 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test case with invalid power and validate_arguments=False."""
+
+import math
+from datetime import timedelta
+from typing import Any
+
+# pylint: disable-next=import-error
+from _config import RESPONSE_CLASS  # type: ignore[import-not-found]
+from frequenz.client.common.microgrid.components import ComponentId
+
+client_kwargs = {
+    "component": ComponentId(1),
+    "power": float("nan"),
+    "request_lifetime": timedelta(seconds=60),
+    "validate_arguments": False,
+}
+
+
+def assert_stub_method_call(stub_method: Any) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    # We can't use float("nan") when comparing here because nan != nan
+    # so instead of using assert_called_once_with, we use assert_called_once
+    # and then check the arguments manually
+    stub_method.assert_called_once()
+    request = stub_method.call_args[0][0]
+    assert request.component_id == 1
+    assert math.isnan(request.power)
+    assert request.request_lifetime == 60
+    assert stub_method.call_args[1]["timeout"] == 60.0
+
+
+grpc_response = RESPONSE_CLASS()
+
+
+def assert_client_result(result: None) -> None:
+    """Assert that the client result is None."""
+    assert result is None

tests/client_test_cases/set_component_power_active/invalid_small_lifetime_case.py

@@ -0,0 +1,31 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test case with invalid power and validate_arguments=False."""
+
+from datetime import timedelta
+from unittest.mock import AsyncMock
+
+# pylint: disable-next=import-error
+from _config import RESPONSE_CLASS  # type: ignore[import-not-found]
+from frequenz.client.common.microgrid.components import ComponentId
+
+client_kwargs = {
+    "component": ComponentId(1),
+    "power": 1000.0,
+    "request_lifetime": timedelta(seconds=1),
+}
+
+
+def assert_stub_method_call(stub_method: AsyncMock) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    stub_method.assert_not_called()
+
+
+grpc_response = RESPONSE_CLASS()
+
+
+def assert_client_exception(result: Exception) -> None:
+    """Assert that the client raises a ValueError."""
+    assert isinstance(result, ValueError)
+    assert str(result) == "request_lifetime must be between 10 seconds and 15 minutes"

tests/client_test_cases/set_component_power_active/no_lifetime_case.py

@@ -0,0 +1,35 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Test set_component_power_active with no lifetime: result should be None."""
+
+from typing import Any
+
+import pytest
+
+# pylint: disable-next=import-error
+from _config import RESPONSE_CLASS  # type: ignore[import-not-found]
+from frequenz.client.common.microgrid.components import ComponentId
+
+client_args = (ComponentId(1), 1000.0)
+
+
+# No client_kwargs needed for this call
+
+
+def assert_stub_method_call(stub_method: Any) -> None:
+    """Assert that the gRPC request matches the expected request."""
+    stub_method.assert_called_once()
+    request = stub_method.call_args[0][0]
+    assert request.component_id == 1
+    assert request.power == pytest.approx(1000.0)
+    assert stub_method.call_args[1]["timeout"] == 60.0
+
+
+grpc_response = RESPONSE_CLASS()
+
+
+def assert_client_result(result: Any) -> None:  # noqa: D103
+    """Assert that the client result is None when no lifetime is provided."""
+    assert result is None
+    assert result is None