docs: update release notes for v0.4.0 API features

Signed-off-by: Mathias L. Baumann <[email protected]>

Author: Marenz

RELEASE_NOTES.md

@@ -7,7 +7,12 @@ Initial release of the Frequenz Market Metering API client for Python.
 ## New Features
 
 - `MarketMeteringApiClient`: Main client class for connecting to the Market Metering service
-- `stream_samples()`: Async iterator for streaming metering samples from Market Locations
+- `upsert_samples()`: Bidirectional streaming for upserting metering samples.
+- `create_market_location()`: Create a new Market Location.
+- `update_market_location()`: Update an existing Market Location.
+- `activate_market_location()`: Activate a Market Location.
+- `deactivate_market_location()`: Deactivate a Market Location.
+- `list_market_locations()`: List Market Locations with filtering and pagination.
 - `stream()`: Channel-based receiver for streaming with automatic reconnection
 - CLI tool (`marketmetering-cli`) for quick access to metering data
 - Support for multiple market identifier types:

mkdocs.yml

@@ -102,9 +102,9 @@ plugins:
   - mkdocstrings:
       default_handler: python
       handlers:
-        paths: ["src"]
         python:
           options:
+            paths: ["src"]
             docstring_section_style: spacy
             inherited_members: true
             merge_init_into_class: false
@@ -116,7 +116,7 @@ plugins:
             show_source: true
             show_symbol_type_toc: true
             signature_crossrefs: true
-          inventories:
+          import:
             # TODO(cookiecutter): You might want to add other external references here
             # See https://mkdocstrings.github.io/python/usage/#import for details
             - https://docs.python.org/3/objects.inv

src/frequenz/client/marketmetering/_client.py

@@ -29,12 +29,10 @@
     MarketLocationsFilter,
     MarketLocationUpdate,
     MetricType,
-    MetricUnit,
     PaginationParams,
     ResamplingOptions,
     RevisionSelection,
     UpsertResult,
-    MarketLocationSample,
 )
 
 DEFAULT_PORT = 443
@@ -159,16 +157,9 @@ def stream_timeout(self) -> timedelta:
     @property
     def stub(self) -> marketmetering_pb2_grpc.MarketMeteringServiceStub:
         """The stub for the service."""
-        # If we have an injected mock stub (for testing), return it directly
-        if self._stub is not None:
-            return self._stub  # type: ignore
-
-        if self._channel is None:
+        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 we need to cast the sync stub to
-        # the async stub, but we can't use cast because the async stub doesn't
-        # actually exist to the eyes of the interpreter.
-        return self._stub  # type: ignore
+        return self._stub
 
     async def create_market_location(
         self,
@@ -186,7 +177,7 @@ async def create_market_location(
             market_location_ref=market_location_ref.to_protobuf(),
             market_location=market_location.to_protobuf(),
         )
-        await self.stub.CreateMarketLocation(
+        await self.stub.CreateMarketLocation(  # type: ignore[misc]
             request,
             timeout=self._call_timeout_seconds,
         )
@@ -209,7 +200,7 @@ async def update_market_location(
             update_fields=update_pb,
             update_mask=update_mask_pb,
         )
-        await self.stub.UpdateMarketLocation(
+        await self.stub.UpdateMarketLocation(  # type: ignore[misc]
             request,
             timeout=self._call_timeout_seconds,
         )
@@ -227,7 +218,7 @@ async def activate_market_location(
         request = pb.ActivateMarketLocationRequest(
             market_location_refs=[market_location_ref.to_protobuf()],
         )
-        await self.stub.ActivateMarketLocation(
+        await self.stub.ActivateMarketLocation(  # type: ignore[misc]
             request,
             timeout=self._call_timeout_seconds,
         )
@@ -245,7 +236,7 @@ async def deactivate_market_location(
         request = pb.DeactivateMarketLocationRequest(
             market_location_refs=[market_location_ref.to_protobuf()],
         )
-        await self.stub.DeactivateMarketLocation(
+        await self.stub.DeactivateMarketLocation(  # type: ignore[misc]
             request,
             timeout=self._call_timeout_seconds,
         )
@@ -280,7 +271,7 @@ async def list_market_locations(
                 pagination_params.to_protobuf() if pagination_params else None
             ),
         )
-        response = await self.stub.ListMarketLocations(
+        response = await self.stub.ListMarketLocations(  # type: ignore[misc]
             request,
             timeout=self._call_timeout_seconds,
         )
@@ -311,9 +302,9 @@ async def upsert_samples(
             UpsertResult objects indicating success or failure for each sample.
         """
 
-        async def request_generator() -> AsyncIterator[
-            pb.UpsertMarketLocationSamplesStreamRequest
-        ]:
+        async def request_generator() -> (
+            AsyncIterator[pb.UpsertMarketLocationSamplesStreamRequest]
+        ):
             async for ml_ref, series in samples_stream:
                 for sample in series.samples:
                     yield pb.UpsertMarketLocationSamplesStreamRequest(
@@ -327,7 +318,7 @@ async def request_generator() -> AsyncIterator[
         response_stream = cast(
             AsyncIterator[pb.UpsertMarketLocationSamplesStreamResponse],
             self.stub.UpsertMarketLocationSamplesStream(
-                request_generator(),
+                request_generator(),  # type: ignore[arg-type]
                 timeout=self._stream_timeout_seconds,
             ),
         )

src/frequenz/client/marketmetering/types.py

@@ -12,8 +12,7 @@
     pagination_params_pb2 as pagination_params_pb,
 )
 from frequenz.api.marketmetering.v1alpha1 import marketmetering_pb2 as pb
-from google.protobuf import struct_pb2
-from google.protobuf import field_mask_pb2
+from google.protobuf import field_mask_pb2, struct_pb2
 from google.protobuf.timestamp_pb2 import Timestamp
 
 
@@ -265,11 +264,11 @@ class DataQuality(Enum):
     MISSING = pb.DATA_QUALITY_MISSING
     """No valid value is available for this interval."""
 
-    def to_protobuf(self) -> pb.DataQuality:
+    def to_protobuf(self) -> int:
         """Convert to protobuf message.
 
         Returns:
-            The protobuf representation.
+            The protobuf representation (integer enum value).
         """
         return self.value
 
@@ -373,13 +372,7 @@ def from_protobuf(cls, pb_obj: pb.MarketLocation) -> Self:
                 EnergyFlowDirection(d) for d in pb_obj.supported_directions
             ],
             time_resolution=TimeResolution(pb_obj.time_resolution),
-            payload={
-                k: v
-                for k, v in pb_obj.payload.items()
-                # Struct values are converted to native Python types automatically
-                # by the protobuf library when accessing them via items(), but
-                # we want to ensure we have a clean dict.
-            },
+            payload=dict(pb_obj.payload.items()),
         )
 
     def to_protobuf(self) -> pb.MarketLocation:
@@ -691,11 +684,13 @@ def from_protobuf(
             # Here we assume it's always present or defaults to 0.
             revision=pb_obj.revision,
             update_time=update_time,
-            resampling_method=ResamplingMethod(pb_obj.resampling_method)
-            if isinstance(pb_obj, pb.MarketLocationSampleDetail)
-            # Fallback to UNSPECIFIED if it's a simple MarketLocationSample
-            # which does not have this field.
-            else ResamplingMethod.UNSPECIFIED,
+            resampling_method=(
+                ResamplingMethod(pb_obj.resampling_method)
+                if isinstance(pb_obj, pb.MarketLocationSampleDetail)
+                # Fallback to UNSPECIFIED if it's a simple MarketLocationSample
+                # which does not have this field.
+                else ResamplingMethod.UNSPECIFIED
+            ),
         )
 
     def to_protobuf(self) -> pb.MarketLocationSample:
@@ -704,12 +699,14 @@ def to_protobuf(self) -> pb.MarketLocationSample:
         Returns:
             The protobuf representation.
         """
-        return pb.MarketLocationSample(
+        sample = pb.MarketLocationSample(
             sample_time=_datetime_to_timestamp(self.sample_time),
             value=self.value,
             quality=self.quality.value,
-            revision=self.revision,
         )
+        if self.revision is not None:
+            sample.revision = self.revision
+        return sample
 
 
 @dataclass(frozen=True)