Merge pull request #21 from eduardiazf/feat/initial-client

Implement initial Assets API client with CLI support

Author: eduardiazf

CODEOWNERS

@@ -4,4 +4,4 @@
 # Fallback owner.
 # These are the default owners for everything in the repo, unless a later match
 # takes precedence.
-* @frequenz-floss/api-assets-team
+* @frequenz-floss/api-assets-team @frequenz-floss/python-sdk-team

RELEASE_NOTES.md

@@ -2,16 +2,43 @@
 
 ## Summary
 
-<!-- Here goes a general summary of what this release is about -->
+This release introduces a complete Assets API client with CLI support for interacting with Frequenz microgrid assets, including comprehensive error handling and type safety.
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+**Breaking Changes:**
+
+- Added new required dependencies: `frequenz-api-assets`, `frequenz-api-common`, `frequenz-client-base`, `grpcio`
+
+**CLI Support:**
+Install with `pip install "frequenz-client-assets[cli]"` for command-line functionality.
 
 ## New Features
 
-<!-- Here goes the main new features and examples or instructions on how to use them -->
+**Assets API Client:**
+
+- Complete gRPC client for Frequenz Assets API
+- Extends `BaseApiClient` for authentication and connection management
+- `get_microgrid_details()` method for retrieving microgrid information
+
+**Command-Line Interface:**
+
+- `python -m frequenz.client.assets microgrid <id>` command
+- Environment variable support for API credentials
+- JSON output formatting
+
+**Type System:**
+
+- `Microgrid`, `DeliveryArea`, and `Location` data classes
+- Protobuf integration with proper type safety
+
+**Exception Handling:**
+
+- Custom exception hierarchy (`AssetsApiError`, `NotFoundError`, `AuthenticationError`, `ServiceUnavailableError`)
+- JSON serialization support for error responses
 
 ## Bug Fixes
 
-<!-- Here goes notable bug fixes that are worth a special mention or explanation -->
+- Improved dependency management with optional dependency groups
+- Enhanced gRPC error handling and type safety
+- Cleaned up deprecated code

pyproject.toml

@@ -26,15 +26,26 @@ classifiers = [
 ]
 requires-python = ">= 3.11, < 4"
 dependencies = [
-  "typing-extensions >= 4.12.2, < 5",
+  "typing-extensions >= 4.13.0, < 5",
+  "frequenz-api-assets @ git+https://github.com/frequenz-floss/[email protected]",
+  "frequenz-api-common >= 0.8.0, < 1",
+  "frequenz-client-base >= 0.11.0, < 0.12.0",
+  "frequenz-client-common >= 0.3.2, < 0.4.0",
+  "grpcio >= 1.73.1, < 2"
 ]
 dynamic = ["version"]
 
+[project.scripts]
+assets-cli = "frequenz.client.assets.cli.__main__:main"
+
 [[project.authors]]
 name = "Frequenz Energy-as-a-Service GmbH"
 email = "[email protected]"
 
 [project.optional-dependencies]
+cli = [
+  "asyncclick == 8.1.8",
+]
 dev-flake8 = [
   "flake8 == 7.3.0",
   "flake8-docstrings == 1.7.0",
@@ -57,9 +68,10 @@ dev-mkdocs = [
 ]
 dev-mypy = [
   "mypy == 1.16.1",
+  "grpc-stubs == 1.53.0.6",
   "types-Markdown == 3.8.0.20250415",
   # For checking the noxfile, docs/ script, and tests
-  "frequenz-client-assets[dev-mkdocs,dev-noxfile,dev-pytest]",
+  "frequenz-client-assets[dev-mkdocs,dev-noxfile,dev-pytest,cli]",
 ]
 dev-noxfile = [
   "nox == 2025.5.1",
@@ -68,7 +80,7 @@ dev-noxfile = [
 dev-pylint = [
   # dev-pytest already defines a dependency to pylint because of the examples
   # For checking the noxfile, docs/ script, and tests
-  "frequenz-client-assets[dev-mkdocs,dev-noxfile,dev-pytest]",
+  "frequenz-client-assets[dev-mkdocs,dev-noxfile,dev-pytest,cli]",
 ]
 dev-pytest = [
   "pytest == 8.4.1",
@@ -101,7 +113,7 @@ src_paths = ["benchmarks", "examples", "src", "tests"]
 
 [tool.flake8]
 # We give some flexibility to go over 88, there are cases like long URLs or
-# code in documenation that have extra indentation. Black will still take care
+# code in documentation that have extra indentation. Black will still take care
 # of making everything that can be 88 wide, 88 wide.
 max-line-length = 100
 extend-ignore = [

src/frequenz/client/assets/__init__.py

@@ -1,22 +1,8 @@
 # License: MIT
 # Copyright © 2025 Frequenz Energy-as-a-Service GmbH
 
-"""Assets API client for Python."""
+"""Assets API client."""
 
+from ._client import AssetsApiClient
 
-# TODO(cookiecutter): Remove this function
-def delete_me(*, blow_up: bool = False) -> bool:
-    """Do stuff for demonstration purposes.
-
-    Args:
-        blow_up: If True, raise an exception.
-
-    Returns:
-        True if no exception was raised.
-
-    Raises:
-        RuntimeError: if blow_up is True.
-    """
-    if blow_up:
-        raise RuntimeError("This function should be removed!")
-    return True
+__all__ = ["AssetsApiClient"]

src/frequenz/client/assets/_client.py

@@ -0,0 +1,87 @@
+# License: MIT
+# Copyright © 2025 Frequenz Energy-as-a-Service GmbH
+
+"""
+Assets API client.
+
+This module provides a client for the Assets API.
+"""
+
+from __future__ import annotations
+
+from frequenz.api.assets.v1 import assets_pb2, assets_pb2_grpc
+from frequenz.client.base.client import BaseApiClient, call_stub_method
+
+from frequenz.client.assets.types import Microgrid
+
+from .exceptions import ClientNotConnected
+
+
+class AssetsApiClient(BaseApiClient[assets_pb2_grpc.PlatformAssetsStub]):
+    """A client for the Assets API."""
+
+    def __init__(
+        self,
+        server_url: str,
+        auth_key: str | None,
+        sign_secret: str | None,
+        connect: bool = True,
+    ) -> None:
+        """
+        Initialize the AssetsApiClient.
+
+        Args:
+            server_url: The URL of the server to connect to.
+            auth_key: The API key to use when connecting to the service.
+            sign_secret: The secret to use when creating message HMAC.
+            connect: Whether to connect to the server as soon as a client instance is created.
+        """
+        super().__init__(
+            server_url,
+            assets_pb2_grpc.PlatformAssetsStub,
+            connect=connect,
+            auth_key=auth_key,
+            sign_secret=sign_secret,
+        )
+
+    @property
+    def stub(self) -> assets_pb2_grpc.PlatformAssetsAsyncStub:
+        """
+        The gRPC stub for the Assets API.
+
+        Returns:
+            The gRPC stub for the Assets API.
+
+        Raises:
+            ClientNotConnected: If the client is not connected to the server.
+        """
+        if self._channel is None or self._stub is None:
+            raise ClientNotConnected(server_url=self.server_url, operation="stub")
+        # This type: ignore is needed because the stub is a sync stub, but we need to
+        # use the async stub, so we cast the sync stub to the async stub.
+        return self._stub  # type: ignore
+
+    async def get_microgrid_details(  # noqa: DOC502 (raises ApiClientError indirectly)
+        self, microgrid_id: int
+    ) -> Microgrid:
+        """
+        Get the details of a microgrid.
+
+        Args:
+            microgrid_id: The ID of the microgrid to get the details of.
+
+        Returns:
+            The details of the microgrid.
+
+        Raises:
+            ApiClientError: If there are any errors communicating with the Assets API,
+                most likely a subclass of [GrpcError][frequenz.client.base.exception.GrpcError].
+        """
+        request = assets_pb2.GetMicrogridRequest(microgrid_id=microgrid_id)
+        response = await call_stub_method(
+            self,
+            lambda: self.stub.GetMicrogrid(request),
+            method_name="GetMicrogrid",
+        )
+
+        return Microgrid.from_protobuf(response.microgrid)