Add support for start_immediately

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

RELEASE_NOTES.md

@@ -4,6 +4,7 @@
 
 * Update BaseApiClient to get the http2 keepalive feature.
 * Some Methods from the high-level API have been moved to this repo: The dispatch class now offers: `until`, `started`, `next_run` and `next_run_after`.
+* Add `start_immediately` support to the `create` method. You can now specify "NOW" as the start time to trigger immediate dispatch. Note: While the dispatch CLI previously allowed this by converting "NOW" to a timestamp client-side before sending it to the server, this functionality is now supported directly on the server side!
 
 ## Bug Fixes
 

src/frequenz/client/dispatch/_cli_types.py

@@ -5,7 +5,7 @@
 
 import json
 from datetime import datetime, timedelta, timezone
-from typing import Any, cast
+from typing import Any, Literal, cast
 
 import asyncclick as click
 import parsedatetime  # type: ignore
@@ -32,12 +32,15 @@ def __init__(self) -> None:
 
     def convert(
         self, value: Any, param: click.Parameter | None, ctx: click.Context | None
-    ) -> datetime:
-        """Convert the value to a datetime object."""
+    ) -> datetime | Literal["NOW"] | None:
+        """Convert the value to a datetime object or the string "NOW"."""
         if isinstance(value, datetime):
             return value
 
         try:
+            if value.upper() == "NOW":
+                return "NOW"
+
             parsed_dt, parse_status = self.cal.parseDT(value, tzinfo=self.local_tz)
             if parse_status == 0:
                 self.fail(f"Invalid time expression: {value}", param, ctx)

src/frequenz/client/dispatch/_client.py

@@ -7,7 +7,7 @@
 from datetime import datetime, timedelta
 from importlib.resources import files
 from pathlib import Path
-from typing import Any, AsyncIterator, Awaitable, Iterator, cast
+from typing import Any, AsyncIterator, Awaitable, Iterator, Literal, cast
 
 # pylint: disable=no-name-in-module
 from frequenz.api.common.v1.pagination.pagination_params_pb2 import PaginationParams
@@ -254,7 +254,7 @@ async def create(  # pylint: disable=too-many-positional-arguments
         self,
         microgrid_id: int,
         type: str,  # pylint: disable=redefined-builtin
-        start_time: datetime,
+        start_time: datetime | Literal["NOW"],
         duration: timedelta | None,
         target: TargetComponents,
         *,
@@ -268,7 +268,7 @@ async def create(  # pylint: disable=too-many-positional-arguments
         Args:
             microgrid_id: The microgrid_id to create the dispatch for.
             type: User defined string to identify the dispatch type.
-            start_time: The start time of the dispatch.
+            start_time: The start time of the dispatch. Can be "NOW" for immediate start.
             duration: The duration of the dispatch. Can be `None` for infinite
                 or no-duration dispatches (e.g. switching a component on).
             target: The component target for the dispatch.
@@ -283,12 +283,16 @@ async def create(  # pylint: disable=too-many-positional-arguments
         Raises:
             ValueError: If start_time is in the past.
         """
-        if start_time <= datetime.now(tz=start_time.tzinfo):
-            raise ValueError("start_time must not be in the past")
-
-        # Raise if it's not UTC
-        if start_time.tzinfo is None or start_time.tzinfo.utcoffset(start_time) is None:
-            raise ValueError("start_time must be timezone aware")
+        if isinstance(start_time, datetime):
+            if start_time <= datetime.now(tz=start_time.tzinfo):
+                raise ValueError("start_time must not be in the past")
+
+            # Raise if it's not UTC
+            if (
+                start_time.tzinfo is None
+                or start_time.tzinfo.utcoffset(start_time) is None
+            ):
+                raise ValueError("start_time must be timezone aware")
 
         request = DispatchCreateRequest(
             microgrid_id=microgrid_id,

src/frequenz/client/dispatch/_internal_types.py

@@ -6,7 +6,7 @@
 
 from dataclasses import dataclass
 from datetime import datetime, timedelta
-from typing import Any
+from typing import Any, Literal
 
 # pylint: disable=no-name-in-module
 from frequenz.api.dispatch.v1.dispatch_pb2 import (
@@ -15,6 +15,7 @@
 from frequenz.api.dispatch.v1.dispatch_pb2 import DispatchData
 from google.protobuf.json_format import MessageToDict
 from google.protobuf.struct_pb2 import Struct
+from google.protobuf.timestamp_pb2 import Timestamp
 
 from frequenz.client.base.conversion import to_datetime, to_timestamp
 
@@ -41,7 +42,7 @@ class DispatchCreateRequest:
 
     This is understood and processed by downstream applications."""
 
-    start_time: datetime
+    start_time: datetime | Literal["NOW"]
     """The start time of the dispatch in UTC."""
 
     duration: timedelta | None
@@ -92,8 +93,10 @@ def from_protobuf(
         return DispatchCreateRequest(
             microgrid_id=pb_object.microgrid_id,
             type=pb_object.dispatch_data.type,
-            start_time=rounded_start_time(
-                to_datetime(pb_object.dispatch_data.start_time)
+            start_time=(
+                "NOW"
+                if pb_object.start_immediately
+                else rounded_start_time(to_datetime(pb_object.dispatch_data.start_time))
             ),
             duration=duration,
             target=_target_components_from_protobuf(pb_object.dispatch_data.target),
@@ -116,7 +119,11 @@ def to_protobuf(self) -> PBDispatchCreateRequest:
             microgrid_id=self.microgrid_id,
             dispatch_data=DispatchData(
                 type=self.type,
-                start_time=to_timestamp(self.start_time),
+                start_time=(
+                    to_timestamp(self.start_time)
+                    if isinstance(self.start_time, datetime)
+                    else Timestamp()
+                ),
                 duration=(
                     round(self.duration.total_seconds()) if self.duration else None
                 ),
@@ -126,6 +133,7 @@ def to_protobuf(self) -> PBDispatchCreateRequest:
                 payload=payload,
                 recurrence=self.recurrence.to_protobuf() if self.recurrence else None,
             ),
+            start_immediately=self.start_time == "NOW",
         )
 
 

src/frequenz/client/dispatch/test/_service.py

@@ -397,6 +397,9 @@ def _dispatch_from_request(
     params = _request.__dict__
     params.pop("microgrid_id")
 
+    if _request.start_time == "NOW":
+        params["start_time"] = datetime.now(tz=timezone.utc)
+
     return Dispatch(
         id=_id,
         create_time=create_time,

tests/test_cli.py

@@ -5,7 +5,7 @@
 
 from dataclasses import replace
 from datetime import datetime, timedelta, timezone
-from typing import Any, Generator
+from typing import Any, Generator, Literal
 from unittest.mock import patch
 
 import pytest
@@ -309,6 +309,24 @@ async def test_list_command(
             ),
             0,
         ),
+        (
+            [
+                "create",
+                "1",
+                "test_start_immediately",
+                "BATTERY",
+                "now",
+                "1h",
+            ],
+            1,
+            "test_start_immediately",
+            "NOW",
+            timedelta(seconds=3600),
+            [ComponentCategory.BATTERY],
+            {},
+            RecurrenceRule(),
+            0,
+        ),
     ],
 )
 async def test_create_command(
@@ -317,7 +335,7 @@ async def test_create_command(
     args: list[str],
     expected_microgrid_id: int,
     expected_type: str,
-    expected_start_time_delta: timedelta,
+    expected_start_time_delta: timedelta | Literal["NOW"],
     expected_duration: timedelta,
     expected_target: list[int] | list[ComponentCategory],
     expected_options: dict[str, Any],
@@ -355,10 +373,17 @@ async def test_create_command(
     assert len(dispatches) == 1
     created_dispatch = dispatches[0]
     assert created_dispatch.type == expected_type
-    assert created_dispatch.start_time.timestamp() == pytest.approx(
-        (now + expected_start_time_delta).astimezone(timezone.utc).timestamp(),
-        abs=2,
-    )
+
+    if isinstance(expected_start_time_delta, timedelta):
+        assert created_dispatch.start_time.timestamp() == pytest.approx(
+            (now + expected_start_time_delta).astimezone(timezone.utc).timestamp(),
+            abs=2,
+        )
+    else:
+        assert created_dispatch.start_time.timestamp() == pytest.approx(
+            now.astimezone(timezone.utc).timestamp(), abs=2
+        )
+
     assert created_dispatch.duration and (
         created_dispatch.duration.total_seconds()
         == pytest.approx(expected_duration.total_seconds(), abs=2)

tests/test_proto.py

@@ -149,3 +149,20 @@ def test_dispatch_create_request_with_no_recurrence() -> None:
     )
 
     assert request.to_protobuf().dispatch_data.HasField("recurrence") is False
+
+
+def test_dispatch_create_start_immediately() -> None:
+    """Test the dispatch create request with no start time."""
+    request = DispatchCreateRequest(
+        microgrid_id=123,
+        type="test",
+        start_time="NOW",
+        duration=timedelta(days=10),
+        target=[1, 2, 3],
+        active=True,
+        dry_run=False,
+        payload={"key": "value"},
+        recurrence=RecurrenceRule(),
+    )
+
+    assert request == DispatchCreateRequest.from_protobuf(request.to_protobuf())