Update delivery time checks for gridpool streams and support delivery time filter in CLI (#231)

This pull request refactors and improves the handling of delivery and
execution time filters in the electricity trading CLI and client code.
It standardizes the naming of time-related parameters, enhances
validation for delivery time filters, and updates the CLI and output
formatting to be more consistent and informative.

**Parameter naming and CLI improvements:**

* Standardized CLI arguments for time filters, replacing ambiguous
options like `--start`/`--end` with clearer `--execution-from`,
`--execution-to`, `--delivery-from`, and `--delivery-to` across relevant
commands in `cli/__main__.py` and `cli/etrading.py`. This clarifies the
distinction between execution and delivery periods and improves
usability.
* Updated function signatures and internal variable names to match the
new CLI arguments, ensuring consistency throughout the codebase.

**Validation and robustness:**

* Added an `is_valid` property to the `DeliveryTimeFilter` class to
check that the delivery time interval is logical (start < end), and
updated the streaming methods in `_client.py` to raise a `ValueError` if
an invalid filter is provided. This prevents invalid queries and
improves error messaging.

**Output formatting and clarity:**

* Enhanced output of order and trade listings by adding the
`gridpool_id` to CSV headers and output, and updated the corresponding
print functions to include this information. This makes CSV exports more
informative and easier to analyze.

**Code simplification and cleanup:**

* Simplified the logic for listing and streaming gridpool trades and
orders by removing redundant checks and using the new delivery time
filter structure, leading to cleaner and more maintainable code.

**Other minor changes:**

* Removed unnecessary imports (such as `timezone`) to clean up the code.

Author: matthias-wende-frequenz

RELEASE_NOTES.md

@@ -6,11 +6,12 @@
 
 ## Upgrading
 
-<!-- Here goes notes on how to upgrade from previous versions, including deprecations and what they should be replaced with -->
+* Update delivery period time filter validation to remove inappropriate start time check.
 
 ## New Features
 
 * Add check to validate order details.
+* CLI: Support delivery time filter in gridpool streams.
 
 ## Bug Fixes
 

src/frequenz/client/electricity_trading/_client.py

@@ -300,8 +300,10 @@ def gridpool_orders_stream(
 
         Raises:
             grpc.RpcError: If an error occurs while streaming the orders.
+            ValueError: If an invalid delivery_time_filter is provided.
         """
-        self.validate_params(delivery_time_filter=delivery_time_filter)
+        if delivery_time_filter and not delivery_time_filter.is_valid:
+            raise ValueError("Invalid delivery_time_filter provided.")
 
         gridpool_order_filter = GridpoolOrderFilter(
             order_states=order_states,
@@ -366,8 +368,10 @@ def gridpool_trades_stream(
 
         Raises:
             grpc.RpcError: If an error occurs while streaming gridpool trades.
+            ValueError: If an invalid delivery_time_filter is provided.
         """
-        self.validate_params(delivery_time_filter=delivery_time_filter)
+        if delivery_time_filter and not delivery_time_filter.is_valid:
+            raise ValueError("Invalid delivery_time_filter provided.")
 
         gridpool_trade_filter = GridpoolTradeFilter(
             trade_states=trade_states,

src/frequenz/client/electricity_trading/_types.py

@@ -1577,6 +1577,25 @@ def to_pb(self) -> electricity_trading_pb2.DeliveryTimeFilter:
             ),
         )
 
+    @property
+    def is_valid(self) -> bool:
+        """Check if the DeliveryTimeFilter is valid.
+
+        Verifies that the start and end dates in the time interval are logical, if both are set.
+
+        Returns:
+            True if the filter is valid, False otherwise.
+        """
+        if self.time_interval is None:
+            return True
+
+        start = self.time_interval.start_time
+        end = self.time_interval.end_time
+        if start is None or end is None:
+            return True
+
+        return start < end
+
 
 @dataclass(frozen=True)
 class GridpoolOrderFilter:

src/frequenz/client/electricity_trading/cli/__main__.py

@@ -51,15 +51,15 @@ def cli() -> None:
 @click.option("--url", required=True, type=str)
 @click.option("--auth_key", required=True, type=str)
 @click.option("--delivery-start", default=None, type=iso)
-@click.option("--start", default=None, type=iso)
-@click.option("--end", default=None, type=iso)
+@click.option("--execution-from", default=None, type=iso)
+@click.option("--execution-to", default=None, type=iso)
 @click.option("--sign_secret", default=None, type=str)
 def receive_public_trades(  # pylint: disable=too-many-arguments
     url: str,
     auth_key: str,
     *,
-    start: datetime,
-    end: datetime,
+    execution_from: datetime,
+    execution_to: datetime,
     delivery_start: datetime,
     sign_secret: str | None = None,
 ) -> None:
@@ -69,8 +69,8 @@ def receive_public_trades(  # pylint: disable=too-many-arguments
             url=url,
             auth_key=auth_key,
             delivery_start=delivery_start,
-            start=start,
-            end=end,
+            start=execution_from,
+            end=execution_to,
             sign_secret=sign_secret,
         )
     )
@@ -80,15 +80,15 @@ def receive_public_trades(  # pylint: disable=too-many-arguments
 @click.option("--url", required=True, type=str)
 @click.option("--auth_key", required=True, type=str)
 @click.option("--delivery-start", default=None, type=iso)
-@click.option("--start", default=None, type=iso)
-@click.option("--end", default=None, type=iso)
+@click.option("--execution-from", default=None, type=iso)
+@click.option("--execution-to", default=None, type=iso)
 @click.option("--sign_secret", default=None, type=str)
 def receive_public_orders(  # pylint: disable=too-many-arguments
     url: str,
     auth_key: str,
     *,
-    start: datetime,
-    end: datetime,
+    execution_from: datetime,
+    execution_to: datetime,
     delivery_start: datetime,
     sign_secret: str | None = None,
 ) -> None:
@@ -98,25 +98,38 @@ def receive_public_orders(  # pylint: disable=too-many-arguments
             url=url,
             auth_key=auth_key,
             delivery_start=delivery_start,
-            start=start,
-            end=end,
+            start=execution_from,
+            end=execution_to,
             sign_secret=sign_secret,
         )
     )
 
 
+# pylint: disable=too-many-arguments
 @cli.command()
 @click.option("--url", required=True, type=str)
 @click.option("--auth_key", required=True, type=str)
 @click.option("--gid", required=True, type=int)
-@click.option("--start", default=None, type=iso)
+@click.option(
+    "--delivery-from",
+    default=None,
+    type=iso,
+    help="Start timestamp (inclusive) to filter delivery start times.",
+)
+@click.option(
+    "--delivery-to",
+    default=None,
+    type=iso,
+    help="End timestamp (exclusive) to filter delivery start times.",
+)
 @click.option("--sign_secret", default=None, type=str)
 def receive_gridpool_trades(
     url: str,
     auth_key: str,
     gid: int,
     *,
-    start: datetime,
+    delivery_from: datetime | None,
+    delivery_to: datetime | None,
     sign_secret: str | None = None,
 ) -> None:
     """List and/or stream gridpool trades."""
@@ -125,23 +138,37 @@ def receive_gridpool_trades(
             url=url,
             auth_key=auth_key,
             gid=gid,
-            delivery_start=start,
+            delivery_from=delivery_from,
+            delivery_to=delivery_to,
             sign_secret=sign_secret,
         )
     )
 
 
+# pylint: disable=too-many-arguments
 @cli.command()
 @click.option("--url", required=True, type=str)
 @click.option("--auth_key", required=True, type=str)
-@click.option("--start", default=None, type=iso)
+@click.option(
+    "--delivery-from",
+    default=None,
+    type=iso,
+    help="Start timestamp (inclusive) to filter delivery start times.",
+)
+@click.option(
+    "--delivery-to",
+    default=None,
+    type=iso,
+    help="End timestamp (exclusive) to filter delivery start times.",
+)
 @click.option("--gid", required=True, type=int)
 @click.option("--sign_secret", default=None, type=str)
 def receive_gridpool_orders(
     url: str,
     auth_key: str,
     *,
-    start: datetime,
+    delivery_from: datetime | None,
+    delivery_to: datetime | None,
     gid: int,
     sign_secret: str | None = None,
 ) -> None:
@@ -150,7 +177,8 @@ def receive_gridpool_orders(
         run_list_gridpool_orders(
             url=url,
             auth_key=auth_key,
-            delivery_start=start,
+            delivery_from=delivery_from,
+            delivery_to=delivery_to,
             gid=gid,
             sign_secret=sign_secret,
         )