Change all client types to be frozen datatypes (#214)

Author: shsms

RELEASE_NOTES.md

@@ -2,28 +2,18 @@
 
 ## Summary
 
-This release adds enhanced filtering capabilities for gridpool orders and trades, with support for tag-based filtering and more flexible time-based queries.
+<!-- Here goes a general summary of what this release is about -->
 
-## New Features
-
-* **Tag filtering for gridpool trades**: The `gridpool_trades()` method now accepts a `tag` parameter to filter trades by tag. The `GridpoolTradeFilter` dataclass has been updated accordingly.
+## Upgrading
 
-* **Flexible time filtering with `DeliveryTimeFilter`**: Replaced the restrictive `delivery_period` parameter with a more flexible `delivery_time_filter` across gridpool orders and trades methods. The new `DeliveryTimeFilter` supports:
-  - Time interval filtering with optional start/end times
-  - Multiple delivery duration filters
-  - More granular control over time-based queries
+- `DeliveryPeriod` instances now require a `DeliveryDuration` as an argument in their constructors, and can't be instantiated from `timedelta`s any more.  Instead, `DeliveryDuration`s can be created from `timedelta` instances with `DeliveryDuration.from_timedelta()`.
 
-* **New types for time filtering**: Added `Interval` and `DeliveryTimeFilter` types to support the enhanced filtering API.
+- Timestamps are no-longer automatically converted to UTC.  If provided timestamps are not in UTC, the client will raise an exception.
 
-* Support tags in CLI create-order command.
-
-## Breaking Changes
+## New Features
 
-* The `delivery_period` parameter has been replaced with `delivery_time_filter` in the following methods:
-  - `list_gridpool_orders()`
-  - `stream_gridpool_orders()`
-  - `gridpool_trades()`
+<!-- Here goes the main new features and examples or instructions on how to use them -->
 
-  Note: The `create_gridpool_order()` method maintains backward compatibility by keeping both parameters.
+## Bug Fixes
 
-* Updated API imports from v1 to v1alpha8 for common types.
+<!-- Here goes notable bug fixes that are worth a special mention or explanation -->

src/frequenz/client/electricity_trading/__init__.py

@@ -192,9 +192,11 @@ async def stream_trades():
     DeliveryArea,
     DeliveryDuration,
     DeliveryPeriod,
+    DeliveryTimeFilter,
     EnergyMarketCodeType,
     GridpoolOrderFilter,
     GridpoolTradeFilter,
+    Interval,
     MarketActor,
     MarketSide,
     Order,
@@ -222,9 +224,11 @@ async def stream_trades():
     "DeliveryArea",
     "DeliveryDuration",
     "DeliveryPeriod",
+    "DeliveryTimeFilter",
     "EnergyMarketCodeType",
     "GridpoolOrderFilter",
     "GridpoolTradeFilter",
+    "Interval",
     "MarketSide",
     "MarketActor",
     "Order",

src/frequenz/client/electricity_trading/_types.py

@@ -312,6 +312,34 @@ class DeliveryDuration(enum.Enum):
     MINUTES_60 = delivery_duration_pb2.DeliveryDuration.DELIVERY_DURATION_60
     """1-hour contract duration."""
 
+    @classmethod
+    def from_timedelta(cls, duration: timedelta) -> Self:
+        """Convert a timedelta to a DeliveryDuration enum.
+
+        Args:
+            duration: The duration as a timedelta.
+
+        Returns:
+            The corresponding DeliveryDuration enum value.
+
+        Raises:
+            ValueError: If the duration is not one of the supported values.
+        """
+        minutes = duration.total_seconds() / 60
+        match minutes:
+            case 5:
+                return DeliveryDuration.MINUTES_5
+            case 15:
+                return DeliveryDuration.MINUTES_15
+            case 30:
+                return DeliveryDuration.MINUTES_30
+            case 60:
+                return DeliveryDuration.MINUTES_60
+            case _:
+                raise ValueError(
+                    "Invalid duration value. Duration must be 5, 15, 30, or 60 minutes."
+                )
+
     @classmethod
     @from_pb
     def from_pb(
@@ -343,6 +371,7 @@ def to_pb(self) -> delivery_duration_pb2.DeliveryDuration.ValueType:
         return delivery_duration_pb2.DeliveryDuration.ValueType(self.value)
 
 
+@dataclass(frozen=True)
 class DeliveryPeriod:
     """
     Time period during which the contract is delivered.
@@ -358,54 +387,10 @@ class DeliveryPeriod:
     duration: DeliveryDuration
     """The length of the delivery period."""
 
-    def __init__(
-        self,
-        start: datetime,
-        duration: timedelta,
-    ) -> None:
-        """
-        Initialize the DeliveryPeriod object.
-
-        Args:
-            start: Start UTC timestamp represents the beginning of the delivery period.
-            duration: The length of the delivery period.
-
-        Raises:
-            ValueError: If the start timestamp does not have a timezone.
-                        or if the duration is not 5, 15, 30, or 60 minutes.
-        """
-        if start.tzinfo is None:
-            raise ValueError("Start timestamp must have a timezone.")
-        if start.tzinfo != timezone.utc:
-            _logger.warning(
-                "Start timestamp is not in UTC timezone. Converting to UTC."
-            )
-            start = start.astimezone(timezone.utc)
-        self.start = start
-
-        minutes = duration.total_seconds() / 60
-        match minutes:
-            case 5:
-                self.duration = DeliveryDuration.MINUTES_5
-            case 15:
-                self.duration = DeliveryDuration.MINUTES_15
-            case 30:
-                self.duration = DeliveryDuration.MINUTES_30
-            case 60:
-                self.duration = DeliveryDuration.MINUTES_60
-            case _:
-                raise ValueError(
-                    "Invalid duration value. Duration must be 5, 15, 30, or 60 minutes."
-                )
-
-    def __hash__(self) -> int:
-        """
-        Create hash of the DeliveryPeriod object.
-
-        Returns:
-            Hash of the DeliveryPeriod object.
-        """
-        return hash((self.start, self.duration))
+    def __post_init__(self) -> None:
+        """Validate that the start timestamp is in UTC."""
+        if self.start.tzinfo is None or self.start.tzinfo != timezone.utc:
+            raise ValueError("Start timestamp must be in UTC timezone.")
 
     def __eq__(
         self,
@@ -453,27 +438,10 @@ def from_pb(cls, delivery_period: delivery_duration_pb2.DeliveryPeriod) -> Self:
 
         Returns:
             DeliveryPeriod object corresponding to the protobuf message.
-
-        Raises:
-            ValueError: If the duration is not 5, 15, 30, or 60 minutes.
         """
         start = delivery_period.start.ToDatetime(tzinfo=timezone.utc)
         delivery_duration_enum = DeliveryDuration.from_pb(delivery_period.duration)
-
-        match delivery_duration_enum:
-            case DeliveryDuration.MINUTES_5:
-                duration = timedelta(minutes=5)
-            case DeliveryDuration.MINUTES_15:
-                duration = timedelta(minutes=15)
-            case DeliveryDuration.MINUTES_30:
-                duration = timedelta(minutes=30)
-            case DeliveryDuration.MINUTES_60:
-                duration = timedelta(minutes=60)
-            case _:
-                raise ValueError(
-                    "Invalid duration value. Duration must be 5, 15, 30, or 60 minutes."
-                )
-        return cls(start=start, duration=duration)
+        return cls(start=start, duration=delivery_duration_enum)
 
     def to_pb(self) -> delivery_duration_pb2.DeliveryPeriod:
         """Convert a DeliveryPeriod object to protobuf DeliveryPeriod.
@@ -1025,7 +993,7 @@ def to_pb(
         return self.value
 
 
-@dataclass()
+@dataclass(frozen=True)
 class Order:  # pylint: disable=too-many-instance-attributes
     """Represents an order in the electricity market."""
 
@@ -1074,11 +1042,11 @@ class Order:  # pylint: disable=too-many-instance-attributes
     def __post_init__(self) -> None:
         """Post initialization checks to ensure that all datetimes are UTC."""
         if self.valid_until is not None:
-            if self.valid_until.tzinfo is None:
+            if (
+                self.valid_until.tzinfo is None
+                or self.valid_until.tzinfo != timezone.utc
+            ):
                 raise ValueError("Valid until must be a UTC datetime.")
-            if self.valid_until.tzinfo != timezone.utc:
-                _logger.warning("Valid until is not a UTC datetime. Converting to UTC.")
-                self.valid_until = self.valid_until.astimezone(timezone.utc)
 
     @classmethod
     @from_pb
@@ -1213,7 +1181,7 @@ def __eq__(self, other: object) -> bool:
         )
 
 
-@dataclass()
+@dataclass(frozen=True)
 class Trade:  # pylint: disable=too-many-instance-attributes
     """Represents a private trade in the electricity market."""
 
@@ -1247,11 +1215,11 @@ class Trade:  # pylint: disable=too-many-instance-attributes
 
     def __post_init__(self) -> None:
         """Post initialization checks to ensure that all datetimes are UTC."""
-        if self.execution_time.tzinfo is None:
-            raise ValueError("Execution time must have timezone information")
-        if self.execution_time.tzinfo != timezone.utc:
-            _logger.warning("Execution timenis not in UTC timezone. Converting to UTC.")
-            self.execution_time = self.execution_time.astimezone(timezone.utc)
+        if (
+            self.execution_time.tzinfo is None
+            or self.execution_time.tzinfo != timezone.utc
+        ):
+            raise ValueError("Execution time must be a UTC datetime.")
 
     @classmethod
     @from_pb
@@ -1347,7 +1315,7 @@ def to_pb(self) -> electricity_trading_pb2.OrderDetail.StateDetail:
         )
 
 
-@dataclass()
+@dataclass(frozen=True)
 class OrderDetail:
     """
     Represents an order with full details, including its ID, state, and associated UTC timestamps.
@@ -1378,19 +1346,14 @@ def __post_init__(self) -> None:
             ValueError: If create_time or modification_time do not have timezone information.
 
         """
-        if self.create_time.tzinfo is None:
-            raise ValueError("Create time must have timezone information")
-        if self.create_time.tzinfo != timezone.utc:
-            _logger.warning("Create time is not in UTC timezone. Converting to UTC.")
-            self.create_time = self.create_time.astimezone(timezone.utc)
+        if self.create_time.tzinfo is None or self.create_time.tzinfo != timezone.utc:
+            raise ValueError("Create time must be a UTC datetime.")
 
-        if self.modification_time.tzinfo is None:
-            raise ValueError("Modification time must have timezone information")
-        if self.modification_time.tzinfo != timezone.utc:
-            _logger.warning(
-                "Modification time is not in UTC timezone. Converting to UTC."
-            )
-            self.modification_time = self.modification_time.astimezone(timezone.utc)
+        if (
+            self.modification_time.tzinfo is None
+            or self.modification_time.tzinfo != timezone.utc
+        ):
+            raise ValueError("Modification time must be a UTC datetime.")
 
     @classmethod
     @from_pb
@@ -1439,7 +1402,7 @@ def to_pb(self) -> electricity_trading_pb2.OrderDetail:
         )
 
 
-@dataclass()
+@dataclass(frozen=True)
 class PublicTrade:  # pylint: disable=too-many-instance-attributes
     """Represents a public order in the market."""
 
@@ -1469,11 +1432,11 @@ class PublicTrade:  # pylint: disable=too-many-instance-attributes
 
     def __post_init__(self) -> None:
         """Post initialization checks to ensure that all datetimes are UTC."""
-        if self.execution_time.tzinfo is None:
-            raise ValueError("Execution time must have timezone information")
-        if self.execution_time.tzinfo != timezone.utc:
-            _logger.warning("Execution time is not in UTC timezone. Converting to UTC.")
-            self.execution_time = self.execution_time.astimezone(timezone.utc)
+        if (
+            self.execution_time.tzinfo is None
+            or self.execution_time.tzinfo != timezone.utc
+        ):
+            raise ValueError("Execution time must be a UTC datetime.")
 
     @classmethod
     @from_pb
@@ -1967,7 +1930,7 @@ def to_pb(self) -> electricity_trading_pb2.PublicTradeFilter:
         )
 
 
-@dataclass()
+@dataclass(frozen=True)
 class UpdateOrder:  # pylint: disable=too-many-instance-attributes
     """
     Represents the order properties that can be updated after an order has been placed.
@@ -2010,12 +1973,10 @@ class UpdateOrder:  # pylint: disable=too-many-instance-attributes
 
     def __post_init__(self) -> None:
         """Post initialization checks to ensure that all datetimes are UTC."""
-        if self.valid_until is not None:
-            if self.valid_until.tzinfo is None:
-                raise ValueError("Valid until must be a UTC datetime.")
-            if self.valid_until.tzinfo != timezone.utc:
-                _logger.warning("Valid until is not a UTC datetime. Converting to UTC.")
-                self.valid_until = self.valid_until.astimezone(timezone.utc)
+        if self.valid_until is not None and (
+            self.valid_until.tzinfo is None or self.valid_until.tzinfo != timezone.utc
+        ):
+            raise ValueError("Valid until must be a UTC datetime.")
 
     @classmethod
     @from_pb
@@ -2109,7 +2070,7 @@ def to_pb(self) -> electricity_trading_pb2.UpdateGridpoolOrderRequest.UpdateOrde
         )
 
 
-@dataclass()
+@dataclass(frozen=True)
 class PublicOrder:  # pylint: disable=too-many-instance-attributes
     """Represents a public order in the market."""
 
@@ -2143,18 +2104,6 @@ class PublicOrder:  # pylint: disable=too-many-instance-attributes
     update_time: datetime
     """UTC Timestamp of the last update to the order."""
 
-    def __post_init__(self) -> None:
-        """Post initialization checks to ensure that all datetimes are UTC."""
-        if self.delivery_period.start.tzinfo is None:
-            raise ValueError("Delivery period start must have timezone information")
-        if self.delivery_period.start.tzinfo != timezone.utc:
-            _logger.warning(
-                "Delivery period start is not in UTC timezone. Converting to UTC."
-            )
-            self.delivery_period.start = self.delivery_period.start.astimezone(
-                timezone.utc
-            )
-
     @classmethod
     @from_pb
     def from_pb(
@@ -2222,7 +2171,7 @@ def to_pb(self) -> electricity_trading_pb2.PublicOrderBookRecord:
         )
 
 
-@dataclass()
+@dataclass(frozen=True)
 class PublicOrderBookFilter:
     """Parameters for filtering the public orders in the market."""