Initial client

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,86 @@
+# 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._client import AssetsApiClient
+
+
+async def main(
+    microgrid_id: int,
+    component_ids: list[int],
+    categories: list[int] | None,
+    source_component_ids: list[int] | None,
+    destination_component_ids: list[int] | None,
+) -> None:
+    """Test the AssetsApiClient.
+
+    Args:
+        microgrid_id: The ID of the microgrid to query.
+        component_ids: List of component IDs to filter.
+        categories: List of component categories to filter.
+        source_component_ids: List of source component IDs to filter.
+        destination_component_ids: List of destination component IDs to filter.
+    """
+    server_url = "localhost:50052"
+    client = AssetsApiClient(server_url)
+
+    print("########################################################")
+    print("Fetching microgrid details")
+
+    microgrid_details = await client.get_microgrid_details(microgrid_id)
+    pprint(microgrid_details)
+
+    print("########################################################")
+    print("Listing microgrid components")
+
+    components = await client.list_microgrid_component_connections(
+        microgrid_id, component_ids, categories
+    )
+    pprint(components)
+
+    print("########################################################")
+    print("Listing microgrid component connections")
+
+    connections = await client.list_microgrid_component_connections(
+        microgrid_id, source_component_ids, destination_component_ids
+    )
+    pprint(connections)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser()
+    parser.add_argument("microgrid_id", type=int, help="Microgrid ID")
+    parser.add_argument(
+        "component_ids", nargs="*", type=int, help="List of component IDs to filter"
+    )
+    parser.add_argument(
+        "categories", nargs="*", type=str, help="List of component categories to filter"
+    )
+    parser.add_argument(
+        "source_component_ids",
+        nargs="*",
+        type=int,
+        help="List of source component IDs to filter",
+    )
+    parser.add_argument(
+        "destination_component_ids",
+        nargs="*",
+        type=int,
+        help="List of destination component IDs to filter",
+    )
+
+    args = parser.parse_args()
+    asyncio.run(
+        main(
+            args.microgrid_id,
+            args.component_ids,
+            args.categories,
+            args.source_component_ids,
+            args.destination_component_ids,
+        )
+    )

pyproject.toml

@@ -27,6 +27,9 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 dependencies = [
   "typing-extensions >= 4.12.2, < 5",
+  "frequenz-api-assets @ git+https://github.com/frequenz-floss/[email protected]",
+  "frequenz-client-common >= 0.3.0, < 1",
+  "frequenz-client-base >= 0.11.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"
@@ -146,7 +153,15 @@ disable = [
 ]
 
 [tool.pytest.ini_options]
-addopts = "-W=all -Werror -Wdefault::DeprecationWarning -Wdefault::PendingDeprecationWarning -vv"
+addopts = "-vv"
+filterwarnings = [
+  "error",
+  "once::DeprecationWarning",
+  "once::PendingDeprecationWarning",
+  # We use a raw string (single quote) to avoid the need to escape special
+  # chars as this is a regex
+  'ignore:Protobuf gencode version .*exactly one major version older.*:UserWarning',
+]
 testpaths = ["tests", "src"]
 asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"

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.
     """