Add initial structure for dispatch client

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

Author: Marenz

pyproject.toml

@@ -27,13 +27,16 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.6.1, < 5",
-# Use marenz fork @ 0d04bc3 until the next release
-  "frequenz-api-dispatch @ git+https://github.com/marenz/frequenz-api-dispatch.git@0d04bc3",
-#  "frequenz-api-dispatch >= 0.12.0, < 0.13",
-# Directly use unreleased/unmerged commit fe4e238 until the next release
-  "frequenz-client-base @ git+https://github.com/marenz/frequenz-client-base-python.git@fe4e238",
+# Use direct commit until merge
+  "frequenz-api-dispatch @ git+https://github.com/marenz/frequenz-api-dispatch.git@f74d15",
+#  "frequenz-api-dispatch >= 0.13.0, < 0.14",
+# Directly use unreleased/unmerged commit until the next release
+  "frequenz-client-base @ git+https://github.com/frequenz-floss/frequenz-client-base-python.git@57d3093",
 #  "frequenz-client-base >= 0.1.0, < 0.2",
-  "frequenz-sdk == v1.0.0-rc4",
+# Directly use unreleased/unmerged commit until the first release
+  "frequenz-client-common @ git+https://github.com/marenz/frequenz-client-common-python.git@0a3abd3",
+#  "frequenz-client-common == 0.1.0",
+  "grpcio >= 1.51.1, < 2"
 ]
 dynamic = ["version"]
 
@@ -66,6 +69,7 @@ dev-mypy = [
   "types-Markdown == 3.4.2.10",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-dispatch-client[dev-mkdocs,dev-noxfile,dev-pytest]",
+  "grpc-stubs == 1.53.0.2",
 ]
 dev-noxfile = [
   "nox == 2023.4.22",
@@ -75,6 +79,7 @@ dev-pylint = [
   "pylint == 3.0.2",
   # For checking the noxfile, docs/ script, and tests
   "frequenz-dispatch-client[dev-mkdocs,dev-noxfile,dev-pytest]",
+  "frequenz-api-dispatch @ git+https://github.com/marenz/frequenz-api-dispatch.git@f74d15",
 ]
 dev-pytest = [
   "pytest == 7.4.2",

src/frequenz/client/dispatch/__init__.py

@@ -2,3 +2,7 @@
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
 """Dispatch API client for Python."""
+
+from ._client import Client
+
+__all__ = ["Client"]

src/frequenz/client/dispatch/_client.py

@@ -0,0 +1,120 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Dispatch API client for Python."""
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Awaitable
+
+import grpc
+from frequenz.api.dispatch.v1 import dispatch_pb2_grpc
+
+# pylint: disable=no-name-in-module
+from frequenz.api.dispatch.v1.dispatch_pb2 import (
+    ComponentSelector,
+    DispatchFilter,
+    DispatchList,
+    DispatchListRequest,
+)
+from frequenz.api.dispatch.v1.dispatch_pb2 import (
+    TimeIntervalFilter as PBTimeIntervalFilter,
+)
+from frequenz.client.common.microgrid.components.components import (
+    ComponentCategory,
+    _component_category_to_protobuf,
+)
+from google.protobuf.timestamp_pb2 import Timestamp
+
+# pylint: enable=no-name-in-module
+
+
+@dataclass(frozen=True, kw_only=True)
+class TimeIntervalFilter:
+    """Filter for a time interval."""
+
+    start_from: datetime
+    """Filter by start_time >= start_from."""
+
+    start_to: datetime
+    """Filter by start_time < start_to."""
+
+    end_from: datetime
+    """Filter by end_time >= end_from."""
+
+    end_to: datetime
+    """Filter by end_time < end_to."""
+
+
+class Client:
+    """Dispatch API client."""
+
+    def __init__(self, grpc_channel: grpc.aio.Channel, svc_addr: str) -> None:
+        """Initialize the client.
+
+        Args:
+            grpc_channel: gRPC channel to use for communication with the API.
+            svc_addr: Address of the service to connect to.
+        """
+        self._svc_addr = svc_addr
+        self._stub = dispatch_pb2_grpc.MicrogridDispatchServiceStub(grpc_channel)
+
+    # pylint: disable=too-many-arguments
+    async def list(
+        self,
+        microgrid_id: int,
+        component_selectors: list[list[int] | ComponentCategory] | None = None,
+        interval_filter: TimeIntervalFilter | None = None,
+        is_active: bool | None = None,
+        is_dry_run: bool | None = None,
+    ) -> DispatchList:
+        """List dispatches.
+
+        Args:
+            microgrid_id: The microgrid_id to list dispatches for.
+            component_selectors: optional, list of component ids or categories to filter by.
+            interval_filter: optional, filter by time interval.
+            is_active: optional, filter by is_active status.
+            is_dry_run: optional, filter by is_dry_run status.
+
+        Returns:
+            DispatchList: List of dispatches.
+        """
+        time_interval = None
+
+        def to_timestamp(dt: datetime) -> Timestamp:
+            ts = Timestamp()
+            ts.FromDatetime(dt)
+            return ts
+
+        if interval_filter:
+            time_interval = PBTimeIntervalFilter(
+                start_from=to_timestamp(interval_filter.start_from),
+                start_to=to_timestamp(interval_filter.start_to),
+                end_from=to_timestamp(interval_filter.end_from),
+                end_to=to_timestamp(interval_filter.end_to),
+            )
+
+        selectors = []
+
+        if component_selectors is not None:
+            for selector in component_selectors:
+                proto_selector = ComponentSelector()
+                if isinstance(selector, list):
+                    proto_selector.component_ids.component_ids.extend(selector)
+                elif isinstance(selector, ComponentCategory):
+                    proto_selector.component_category = _component_category_to_protobuf(
+                        selector
+                    )
+                selectors.append(proto_selector)
+
+        filters = DispatchFilter(
+            selectors=selectors,
+            time_interval=time_interval,
+            is_active=is_active,
+            is_dry_run=is_dry_run,
+        )
+        request = DispatchListRequest(microgrid_id=microgrid_id, filter=filters)
+
+        response: Awaitable[DispatchList]
+        response = self._stub.ListMicrogridDispatches(request)  # type: ignore
+        return await response

src/frequenz/client/dispatch/_types.py

@@ -0,0 +1,6 @@
+# License: MIT
+# Copyright © 2024 Frequenz Energy-as-a-Service GmbH
+
+"""Type wrappers for the generated protobuf messages."""
+
+# from frequenz.api.dispatch.v1 import dispatch_pb2, dispatch_pb2_grpc

tests/test_dispatch_client.py

@@ -2,4 +2,97 @@
 # Copyright © 2024 Frequenz Energy-as-a-Service GmbH
 
 """Tests for the frequenz.client.dispatch package."""
+
+from contextlib import asynccontextmanager
+from typing import AsyncGenerator
+
 import pytest
+
+# pylint: disable=no-name-in-module
+from frequenz.api.dispatch.v1 import dispatch_pb2_grpc
+from frequenz.api.dispatch.v1.dispatch_pb2 import (
+    Dispatch,
+    DispatchCreateRequest,
+    DispatchDeleteRequest,
+    DispatchGetRequest,
+    DispatchList,
+    DispatchListRequest,
+    DispatchUpdateRequest,
+)
+from google.protobuf.empty_pb2 import Empty
+from grpc import aio
+
+from frequenz.client.dispatch import Client
+
+# pylint: enable=no-name-in-module
+
+
+class DispatchServicer(dispatch_pb2_grpc.MicrogridDispatchServiceServicer):
+    """Dispatch servicer for testing."""
+
+    def ListMicrogridDispatches(
+        self, request: DispatchListRequest, context: aio.ServicerContext  # type: ignore
+    ) -> DispatchList:
+        """List microgrid dispatches."""
+        return DispatchList()
+
+    def CreateMicrogridDispatch(
+        self,
+        request: DispatchCreateRequest,
+        context: aio.ServicerContext,  # type: ignore
+    ) -> Empty:
+        """Create a new dispatch."""
+        return Empty()
+
+    def UpdateMicrogridDispatch(
+        self,
+        request: DispatchUpdateRequest,
+        context: aio.ServicerContext,  # type: ignore
+    ) -> Empty:
+        """Update a dispatch."""
+        return Empty()
+
+    def GetMicrogridDispatch(
+        self,
+        request: DispatchGetRequest,
+        context: aio.ServicerContext,  # type: ignore
+    ) -> Dispatch:
+        """Get a single dispatch."""
+        return Dispatch()
+
+    def DeleteMicrogridDispatch(
+        self,
+        request: DispatchDeleteRequest,
+        context: aio.ServicerContext,  # type: ignore
+    ) -> Empty:
+        """Delete a given dispatch."""
+        return Empty()
+
+
+ServicerType = AsyncGenerator[tuple[aio.Server, int], None]
+
+
+@asynccontextmanager
+async def grpc_servicer() -> AsyncGenerator[tuple[aio.Server, str], None]:
+    """Async context manager to setup and teardown a gRPC server for testing."""
+    server = aio.server()
+    dispatch_servicer = DispatchServicer()
+    dispatch_pb2_grpc.add_MicrogridDispatchServiceServicer_to_server(
+        dispatch_servicer, server
+    )
+    port = server.add_insecure_port("localhost:0")
+    await server.start()
+    try:
+        yield server, f"localhost:{port}"
+    finally:
+        await server.stop(None)
+
+
+@pytest.mark.asyncio
+async def test_list_dispatches() -> None:
+    """Test listing dispatches."""
+    async with grpc_servicer() as (server, address):
+        async with aio.insecure_channel(address) as channel:
+            client = Client(channel, address)
+            response = await client.list(microgrid_id=1)
+            assert response is not None