Initial client

Signed-off-by: Flora <[email protected]>

Author: flora-hofmann-frequenz

RELEASE_NOTES.md

@@ -2,15 +2,20 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release introduces the initial version of the Assets API client, enabling retrieval of asset-related data.
 
 ## Upgrading
 
 <!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+Introducing the initial version of the Assets API client, designed to streamline access to asset-related data.
+
+* Supports querying asset components and retrieving their metrics efficiently.
+* Provides a structured data representation while retaining raw protobuf responses.
+* Currently focused on retrieving asset data for individual components.
+* Examples are provided to guide users through the basic usage of the client.
 
 ## Bug Fixes
 

examples/client.py

@@ -0,0 +1,46 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Examples usage of PlatformAssets API."""
+
+import argparse
+import asyncio
+from pprint import pprint
+
+from frequenz.client.assets import AssetsApiClient
+
+
+async def main(microgrid_id: int) -> None:
+    """Test the AssetsApiClient.
+
+    Args:
+        microgrid_id: The ID of the microgrid to query.
+    """
+    server_url = "localhost:50052"
+    client = AssetsApiClient(server_url)
+
+    print("########################################################")
+    print("Fetching microgrid details")
+
+    microgrid_details = await client.get_microgrid(microgrid_id)
+    pprint(microgrid_details)
+
+    print("########################################################")
+    print("Listing microgrid components")
+
+    components = await client.list_microgrid_components(microgrid_id)
+    pprint(components)
+
+    print("########################################################")
+    print("Listing microgrid component connections")
+
+    connections = await client.list_microgrid_component_connections(microgrid_id)
+    pprint(connections)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("microgrid_id", type=int, help="Microgrid ID")
+
+    args = parser.parse_args()
+    asyncio.run(main(args.microgrid_id))

pyproject.toml

@@ -27,6 +27,9 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.12.2, < 5",
+  "frequenz-api-assets >= 0.0.1, < 1",
+  "frequenz-client-common >= 0.3.0, < 1",
+  "frequenz-client-base >= 0.9.0, < 1",
 ]
 dynamic = ["version"]
 
@@ -82,6 +85,10 @@ dev = [
   "frequenz-client-assets[dev-mkdocs,dev-flake8,dev-formatting,dev-mkdocs,dev-mypy,dev-noxfile,dev-pylint,dev-pytest]",
 ]
 
+examples = [
+    "grpcio >= 1.51.1, < 2",
+]
+
 [project.urls]
 Documentation = "https://frequenz-floss.github.io/frequenz-client-assets-python/"
 Changelog = "https://github.com/frequenz-floss/frequenz-client-assets-python/releases"

src/frequenz/client/assets/__init__.py

@@ -13,7 +13,6 @@ def delete_me(*, blow_up: bool = False) -> bool:
 
     Returns:
         True if no exception was raised.
-
     Raises:
         RuntimeError: if blow_up is True.
     """

src/frequenz/client/assets/_client.py

@@ -0,0 +1,117 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""Client for requests to the PlatformAssets API."""
+
+from typing import Iterable, Optional
+
+# pylint: disable=no-name-in-module
+from frequenz.api.assets.v1.assets_pb2 import (
+    GetMicrogridRequest as PBGetMicrogridRequest,
+)
+from frequenz.api.assets.v1.assets_pb2 import (
+    GetMicrogridResponse as PBGetMicrogridResponse,
+)
+from frequenz.api.assets.v1.assets_pb2 import (
+    ListMicrogridComponentConnectionsRequest as PBListMicrogridComponentConnectionsRequest,
+)
+from frequenz.api.assets.v1.assets_pb2 import (
+    ListMicrogridComponentConnectionsResponse as PBListMicrogridComponentConnectionsResponse,
+)
+from frequenz.api.assets.v1.assets_pb2 import (
+    ListMicrogridComponentsRequest as PBListMicrogridComponentsRequest,
+)
+from frequenz.api.assets.v1.assets_pb2 import (
+    ListMicrogridComponentsResponse as PBListMicrogridComponentsResponse,
+)
+from frequenz.api.assets.v1.assets_pb2_grpc import PlatformAssetsStub
+from frequenz.api.common.v1.microgrid.components.components_pb2 import (
+    ComponentCategory as PBComponentCategory,
+)
+from frequenz.client.base.client import BaseApiClient, call_stub_method
+from frequenz.client.base.exception import ClientNotConnected
+
+# pylint: enable=no-name-in-module
+
+
+class AssetsApiClient(BaseApiClient[PlatformAssetsStub]):
+    """A client for the Frequenz PlatformAssets service."""
+
+    def __init__(self, server_url: str, *, connect: bool = True) -> None:
+        """Initialize the client.
+
+        Args:
+            server_url: The URL of the PlatformAssets service.
+            connect: Whether to establish a connection immediately.
+        """
+        super().__init__(server_url, PlatformAssetsStub, connect=connect)
+
+    @property
+    def stub(self) -> PlatformAssetsStub:
+        """Return the gRPC stub for the PlatformAssets service."""
+        if self.channel is None or self._stub is None:
+            raise ClientNotConnected(server_url=self.server_url, operation="stub")
+        return self._stub
+
+    async def get_microgrid(self, microgrid_id: int) -> PBGetMicrogridResponse:
+        """Fetch details of a specific microgrid.
+
+        Args:
+            microgrid_id: The ID of the microgrid to fetch.
+
+        Returns:
+            The response containing the microgrid details.
+        """
+        request = PBGetMicrogridRequest(microgrid_id=microgrid_id)
+        return await call_stub_method(self, lambda: self.stub.GetMicrogrid(request))
+
+    async def list_microgrid_components(
+        self,
+        microgrid_id: int,
+        component_ids: Optional[list[int]] | None,
+        categories: Optional[Iterable[PBComponentCategory]] | None,
+    ) -> PBListMicrogridComponentsResponse:
+        """List electrical components of a microgrid.
+
+        Args:
+            microgrid_id: The ID of the microgrid to fetch components for.
+            component_ids: The IDs of the components to fetch.
+            categories: The categories of the components to fetch.
+
+        Returns:
+            The response containing the microgrid components.
+        """
+        request = PBListMicrogridComponentsRequest(
+            microgrid_id=microgrid_id,
+            component_ids=component_ids,
+            categories=categories,
+        )
+        return await call_stub_method(
+            self, lambda: self.stub.ListMicrogridComponents(request)
+        )
+
+    async def list_microgrid_component_connections(
+        self,
+        microgrid_id: int,
+        source_component_ids: Optional[list[int]] | None,
+        destination_component_ids: Optional[list[int]] | None,
+    ) -> PBListMicrogridComponentConnectionsResponse:
+        """List electrical connections between components in a microgrid.
+
+        Args:
+            microgrid_id: The ID of the microgrid to fetch component connections for.
+            source_component_ids: The IDs of the source components to fetch connections for.
+            destination_component_ids: The IDs of the destination components to fetch
+                                       connections for.
+
+        Returns:
+            The response containing the component connections.
+        """
+        request = PBListMicrogridComponentConnectionsRequest(
+            microgrid_id=microgrid_id,
+            source_component_ids=source_component_ids,
+            destination_component_ids=destination_component_ids,
+        )
+        return await call_stub_method(
+            self, lambda: self.stub.ListMicrogridComponentConnections(request)
+        )