Replace Energy with Power for the quantity representation (#60)

This PR replaces `Energy` with `Power` for the `quantity`
representation, as a result of a change in the API specs described
[here](frequenz-floss/frequenz-api-electricity-trading#102).

Author: camille-bouvy-frequenz

RELEASE_NOTES.md

@@ -15,6 +15,7 @@
 * Move documentation and code examples to the documentation website
 * Replace the local `PaginationParams` type with the `frequenz-client-common` one
 * Remove dependency to `googleapis-common-protos`
+* Replace `Energy` with `Power` for the `quantity` representation
 
 ## Bug Fixes
 

pyproject.toml

@@ -27,13 +27,13 @@ classifiers = [
 requires-python = ">= 3.11, < 4"
 # TODO(cookiecutter): Remove and add more dependencies if appropriate
 dependencies = [
-  "frequenz-api-common >= 0.6.2, < 0.7.0",
+  "frequenz-api-common >= 0.6.3, < 0.7.0",
   "grpcio >= 1.66.2, < 2",
   "frequenz-channels >= 1.0.0, < 2",
   "frequenz-client-base >= 0.6.1, < 0.7.0",
   "frequenz-client-common >= 0.1.0, < 0.3.0",
-  "frequenz-api-electricity-trading >= 0.2.3, < 1",
-  "protobuf >= 5.27.2, < 6",
+  "frequenz-api-electricity-trading >= 0.2.4, < 1",
+  "protobuf >= 5.28.0, < 6",
 ]
 dynamic = ["version"]
 

src/frequenz/client/electricity_trading/__init__.py

@@ -165,7 +165,6 @@
     DeliveryArea,
     DeliveryDuration,
     DeliveryPeriod,
-    Energy,
     EnergyMarketCodeType,
     GridpoolOrderFilter,
     GridpoolTradeFilter,
@@ -176,6 +175,7 @@
     OrderExecutionOption,
     OrderState,
     OrderType,
+    Power,
     Price,
     PublicTrade,
     PublicTradeFilter,
@@ -192,7 +192,6 @@
     "DeliveryArea",
     "DeliveryDuration",
     "DeliveryPeriod",
-    "Energy",
     "EnergyMarketCodeType",
     "GridpoolOrderFilter",
     "GridpoolTradeFilter",
@@ -203,6 +202,7 @@
     "OrderExecutionOption",
     "OrderState",
     "OrderType",
+    "Power",
     "Price",
     "PublicTrade",
     "PublicTradeFilter",

src/frequenz/client/electricity_trading/_client.py

@@ -24,7 +24,6 @@
 from ._types import (
     DeliveryArea,
     DeliveryPeriod,
-    Energy,
     GridpoolOrderFilter,
     GridpoolTradeFilter,
     MarketSide,
@@ -33,6 +32,7 @@
     OrderExecutionOption,
     OrderState,
     OrderType,
+    Power,
     Price,
     PublicTrade,
     PublicTradeFilter,
@@ -321,10 +321,10 @@ def validate_params(
         # pylint: disable=too-many-arguments, too-many-positional-arguments, too-many-branches
         self,
         price: Price | None | _Sentinel = NO_VALUE,
-        quantity: Energy | None | _Sentinel = NO_VALUE,
+        quantity: Power | None | _Sentinel = NO_VALUE,
         stop_price: Price | None | _Sentinel = NO_VALUE,
         peak_price_delta: Price | None | _Sentinel = NO_VALUE,
-        display_quantity: Energy | None | _Sentinel = NO_VALUE,
+        display_quantity: Power | None | _Sentinel = NO_VALUE,
         delivery_period: DeliveryPeriod | None = None,
         valid_until: datetime | None | _Sentinel = NO_VALUE,
         execution_option: OrderExecutionOption | None | _Sentinel = NO_VALUE,
@@ -355,9 +355,7 @@ def validate_params(
         if not isinstance(price, _Sentinel) and price is not None:
             validate_decimal_places(price.amount, PRECISION_DECIMAL_PRICE, "price")
         if not isinstance(quantity, _Sentinel) and quantity is not None:
-            validate_decimal_places(
-                quantity.mwh, PRECISION_DECIMAL_QUANTITY, "quantity"
-            )
+            validate_decimal_places(quantity.mw, PRECISION_DECIMAL_QUANTITY, "quantity")
         if not isinstance(stop_price, _Sentinel) and stop_price is not None:
             raise NotImplementedError(
                 "STOP_LIMIT orders are not supported yet, so stop_price cannot be set."
@@ -402,10 +400,10 @@ async def create_gridpool_order(
         order_type: OrderType,
         side: MarketSide,
         price: Price,
-        quantity: Energy,
+        quantity: Power,
         stop_price: Price | None = None,
         peak_price_delta: Price | None = None,
-        display_quantity: Energy | None = None,
+        display_quantity: Power | None = None,
         execution_option: OrderExecutionOption | None = None,
         valid_until: datetime | None = None,
         payload: dict[str, struct_pb2.Value] | None = None,
@@ -486,10 +484,10 @@ async def update_gridpool_order(
         gridpool_id: int,
         order_id: int,
         price: Price | None | _Sentinel = NO_VALUE,
-        quantity: Energy | None | _Sentinel = NO_VALUE,
+        quantity: Power | None | _Sentinel = NO_VALUE,
         stop_price: Price | None | _Sentinel = NO_VALUE,
         peak_price_delta: Price | None | _Sentinel = NO_VALUE,
-        display_quantity: Energy | None | _Sentinel = NO_VALUE,
+        display_quantity: Power | None | _Sentinel = NO_VALUE,
         execution_option: OrderExecutionOption | None | _Sentinel = NO_VALUE,
         valid_until: datetime | None | _Sentinel = NO_VALUE,
         payload: dict[str, struct_pb2.Value] | None | _Sentinel = NO_VALUE,
@@ -503,7 +501,7 @@ async def update_gridpool_order(
             order_id: Order ID.
             price: The updated limit price at which the contract is to be traded.
                 This is the maximum price for a BUY order or the minimum price for a SELL order.
-            quantity: The updated quantity of the contract being traded, specified in MWh.
+            quantity: The updated quantity of the contract being traded, specified in MW.
             stop_price: Applicable for STOP_LIMIT orders. This is the updated stop price that
                 triggers the limit order.
             peak_price_delta: Applicable for ICEBERG orders. This is the updated price difference

src/frequenz/client/electricity_trading/_types.py

@@ -16,7 +16,7 @@
 
 # pylint: disable=no-member
 from frequenz.api.common.v1.grid import delivery_area_pb2, delivery_duration_pb2
-from frequenz.api.common.v1.market import energy_pb2, price_pb2
+from frequenz.api.common.v1.market import power_pb2, price_pb2
 from frequenz.api.common.v1.types import decimal_pb2
 from frequenz.api.electricity_trading.v1 import electricity_trading_pb2
 from google.protobuf import json_format, struct_pb2, timestamp_pb2
@@ -117,32 +117,32 @@ def to_pb(self) -> price_pb2.Price:
 
 
 @dataclass(frozen=True)
-class Energy:
-    """Represents energy unit in Megawatthours (MWh)."""
+class Power:
+    """Represents power unit in Megawatthours (MW)."""
 
-    mwh: Decimal
+    mw: Decimal
 
     @classmethod
-    def from_pb(cls, energy: energy_pb2.Energy) -> Self:
-        """Convert a protobuf Energy to Energy object.
+    def from_pb(cls, power: power_pb2.Power) -> Self:
+        """Convert a protobuf Power to Power object.
 
         Args:
-            energy: Energy to convert.
+            power: Power to convert.
 
         Returns:
-            Energy object corresponding to the protobuf message.
+            Power object corresponding to the protobuf message.
         """
-        return cls(mwh=Decimal(energy.mwh.value))
+        return cls(mw=Decimal(power.mw.value))
 
-    def to_pb(self) -> energy_pb2.Energy:
-        """Convert a Energy object to protobuf Energy.
+    def to_pb(self) -> power_pb2.Power:
+        """Convert a Power object to protobuf Power.
 
         Returns:
-            Protobuf message corresponding to the Energy object.
+            Protobuf message corresponding to the Power object.
         """
-        decimal_mwh = decimal_pb2.Decimal()
-        decimal_mwh.value = str(self.mwh)
-        return energy_pb2.Energy(mwh=decimal_mwh)
+        decimal_mw = decimal_pb2.Decimal()
+        decimal_mw.value = str(self.mw)
+        return power_pb2.Power(mw=decimal_mw)
 
 
 class EnergyMarketCodeType(enum.Enum):
@@ -872,7 +872,7 @@ class Order:  # pylint: disable=too-many-instance-attributes
     price: Price
     """The limit price at which the contract is to be traded."""
 
-    quantity: Energy
+    quantity: Power
     """The quantity of the contract being traded."""
 
     stop_price: Price | None = None
@@ -882,7 +882,7 @@ class Order:  # pylint: disable=too-many-instance-attributes
     """Applicable for ICEBERG orders. The price difference between the peak price and
     the limit price."""
 
-    display_quantity: Energy | None = None
+    display_quantity: Power | None = None
     """Applicable for ICEBERG orders. The quantity of the order to be displayed in the order
     book."""
 
@@ -924,7 +924,7 @@ def from_pb(cls, order: electricity_trading_pb2.Order) -> Self:
             type=OrderType.from_pb(order.type),
             side=MarketSide.from_pb(order.side),
             price=Price.from_pb(order.price),
-            quantity=Energy.from_pb(order.quantity),
+            quantity=Power.from_pb(order.quantity),
             stop_price=(
                 Price.from_pb(order.stop_price)
                 if order.HasField("stop_price")
@@ -936,7 +936,7 @@ def from_pb(cls, order: electricity_trading_pb2.Order) -> Self:
                 else None
             ),
             display_quantity=(
-                Energy.from_pb(order.display_quantity)
+                Power.from_pb(order.display_quantity)
                 if order.HasField("display_quantity")
                 else None
             ),
@@ -1019,7 +1019,7 @@ class Trade:  # pylint: disable=too-many-instance-attributes
     price: Price
     """The price at which the trade was executed."""
 
-    quantity: Energy
+    quantity: Power
     """The executed quantity of the trade."""
 
     state: TradeState
@@ -1051,7 +1051,7 @@ def from_pb(cls, trade: electricity_trading_pb2.Trade) -> Self:
             delivery_period=DeliveryPeriod.from_pb(trade.delivery_period),
             execution_time=trade.execution_time.ToDatetime(tzinfo=timezone.utc),
             price=Price.from_pb(trade.price),
-            quantity=Energy.from_pb(trade.quantity),
+            quantity=Power.from_pb(trade.quantity),
             state=TradeState.from_pb(trade.state),
         )
 
@@ -1143,8 +1143,8 @@ class OrderDetail:
     order_id: int
     order: Order
     state_detail: StateDetail
-    open_quantity: Energy
-    filled_quantity: Energy
+    open_quantity: Power
+    filled_quantity: Power
     create_time: datetime
     modification_time: datetime
 
@@ -1184,8 +1184,8 @@ def from_pb(cls, order_detail: electricity_trading_pb2.OrderDetail) -> Self:
             order_id=order_detail.order_id,
             order=Order.from_pb(order_detail.order),
             state_detail=StateDetail.from_pb(order_detail.state_detail),
-            open_quantity=Energy.from_pb(order_detail.open_quantity),
-            filled_quantity=Energy.from_pb(order_detail.filled_quantity),
+            open_quantity=Power.from_pb(order_detail.open_quantity),
+            filled_quantity=Power.from_pb(order_detail.filled_quantity),
             create_time=order_detail.create_time.ToDatetime(tzinfo=timezone.utc),
             modification_time=order_detail.modification_time.ToDatetime(
                 tzinfo=timezone.utc
@@ -1236,7 +1236,7 @@ class PublicTrade:  # pylint: disable=too-many-instance-attributes
     price: Price
     """The limit price at which the contract is to be traded."""
 
-    quantity: Energy
+    quantity: Power
     """The quantity of the contract being traded."""
 
     state: TradeState
@@ -1267,7 +1267,7 @@ def from_pb(cls, public_trade: electricity_trading_pb2.PublicTrade) -> Self:
             delivery_period=DeliveryPeriod.from_pb(public_trade.delivery_period),
             execution_time=public_trade.execution_time.ToDatetime(tzinfo=timezone.utc),
             price=Price.from_pb(public_trade.price),
-            quantity=Energy.from_pb(public_trade.quantity),
+            quantity=Power.from_pb(public_trade.quantity),
             state=TradeState.from_pb(public_trade.state),
         )
 
@@ -1659,8 +1659,8 @@ class UpdateOrder:  # pylint: disable=too-many-instance-attributes
     """The updated limit price at which the contract is to be traded.
     This is the maximum price for a BUY order or the minimum price for a SELL order."""
 
-    quantity: Energy | None = None
-    """The updated quantity of the contract being traded, specified in MWh."""
+    quantity: Power | None = None
+    """The updated quantity of the contract being traded, specified in MW."""
 
     stop_price: Price | None = None
     """Applicable for STOP_LIMIT orders. This is the updated stop price that triggers
@@ -1670,7 +1670,7 @@ class UpdateOrder:  # pylint: disable=too-many-instance-attributes
     """Applicable for ICEBERG orders. This is the updated price difference
     between the peak price and the limit price."""
 
-    display_quantity: Energy | None = None
+    display_quantity: Power | None = None
     """Applicable for ICEBERG orders. This is the updated quantity of the order
     to be displayed in the order book."""
 
@@ -1717,7 +1717,7 @@ def from_pb(
                 else None
             ),
             quantity=(
-                Energy.from_pb(update_order.quantity)
+                Power.from_pb(update_order.quantity)
                 if update_order.HasField("quantity")
                 else None
             ),
@@ -1732,7 +1732,7 @@ def from_pb(
                 else None
             ),
             display_quantity=(
-                Energy.from_pb(update_order.display_quantity)
+                Power.from_pb(update_order.display_quantity)
                 if update_order.HasField("display_quantity")
                 else None
             ),