|
| 1 | +# License: MIT |
| 2 | +# Copyright © 2024 Frequenz Energy-as-a-Service GmbH |
| 3 | + |
| 4 | +"""Types for the Reporting API client.""" |
| 5 | + |
| 6 | +from collections import namedtuple |
| 7 | +from collections.abc import Iterable, Iterator |
| 8 | +from dataclasses import dataclass |
| 9 | +from datetime import timezone |
| 10 | +from typing import Any |
| 11 | + |
| 12 | +# pylint: disable=no-name-in-module |
| 13 | +from frequenz.api.reporting.v1.reporting_pb2 import ( |
| 14 | + ReceiveAggregatedMicrogridComponentsDataStreamResponse as PBAggregatedStreamResponse, |
| 15 | +) |
| 16 | +from frequenz.api.reporting.v1.reporting_pb2 import ( |
| 17 | + ReceiveMicrogridComponentsDataStreamResponse as PBReceiveMicrogridComponentsDataStreamResponse, |
| 18 | +) |
| 19 | +from frequenz.api.reporting.v1.reporting_pb2 import ( |
| 20 | + ReceiveMicrogridSensorsDataStreamResponse as PBReceiveMicrogridSensorsDataStreamResponse, |
| 21 | +) |
| 22 | + |
| 23 | +# pylint: enable=no-name-in-module |
| 24 | +from frequenz.client.common.metric import Metric |
| 25 | + |
| 26 | +MetricSample = namedtuple( |
| 27 | + "MetricSample", ["timestamp", "microgrid_id", "component_id", "metric", "value"] |
| 28 | +) |
| 29 | +"""Type for a sample of a time series incl. metric type, microgrid and component ID |
| 30 | +
|
| 31 | +A named tuple was chosen to allow safe access to the fields while keeping the |
| 32 | +simplicity of a tuple. This data type can be easily used to create a numpy array |
| 33 | +or a pandas DataFrame. |
| 34 | +""" |
| 35 | + |
| 36 | + |
| 37 | +@dataclass(frozen=True) |
| 38 | +class GenericDataBatch: |
| 39 | + """Base class for batches of microgrid data (components or sensors). |
| 40 | +
|
| 41 | + This class serves as a base for handling batches of data related to microgrid |
| 42 | + components or sensors. It manages the received protocol buffer (PB) data, |
| 43 | + provides access to relevant items via specific attributes, and includes |
| 44 | + functionality to work with bounds if applicable. |
| 45 | + """ |
| 46 | + |
| 47 | + _data_pb: Any |
| 48 | + id_attr: str |
| 49 | + items_attr: str |
| 50 | + has_bounds: bool = False |
| 51 | + |
| 52 | + def is_empty(self) -> bool: |
| 53 | + """Check if the batch contains valid data. |
| 54 | +
|
| 55 | + Returns: |
| 56 | + True if the batch contains no valid data. |
| 57 | + """ |
| 58 | + items = getattr(self._data_pb, self.items_attr, []) |
| 59 | + if not items: |
| 60 | + return True |
| 61 | + for item in items: |
| 62 | + if not getattr(item, "metric_samples", []) and not getattr( |
| 63 | + item, "states", [] |
| 64 | + ): |
| 65 | + return True |
| 66 | + return False |
| 67 | + |
| 68 | + def __iter__(self) -> Iterator[MetricSample]: |
| 69 | + """Get generator that iterates over all values in the batch. |
| 70 | +
|
| 71 | + Note: So far only `SimpleMetricSample` in the `MetricSampleVariant` |
| 72 | + message is supported. |
| 73 | +
|
| 74 | +
|
| 75 | + Yields: |
| 76 | + A named tuple with the following fields: |
| 77 | + * timestamp: The timestamp of the metric sample. |
| 78 | + * microgrid_id: The microgrid ID. |
| 79 | + * component_id: The component ID. |
| 80 | + * metric: The metric name. |
| 81 | + * value: The metric value. |
| 82 | + """ |
| 83 | + mid = self._data_pb.microgrid_id |
| 84 | + items = getattr(self._data_pb, self.items_attr) |
| 85 | + |
| 86 | + for item in items: |
| 87 | + cid = getattr(item, self.id_attr) |
| 88 | + for sample in getattr(item, "metric_samples", []): |
| 89 | + ts = sample.sampled_at.ToDatetime().replace(tzinfo=timezone.utc) |
| 90 | + met = Metric.from_proto(sample.metric).name |
| 91 | + value = ( |
| 92 | + sample.value.simple_metric.value |
| 93 | + if sample.value.HasField("simple_metric") |
| 94 | + else None |
| 95 | + ) |
| 96 | + yield MetricSample(ts, mid, cid, met, value) |
| 97 | + |
| 98 | + if self.has_bounds: |
| 99 | + for i, bound in enumerate(sample.bounds): |
| 100 | + if bound.lower: |
| 101 | + yield MetricSample( |
| 102 | + ts, mid, cid, f"{met}_bound_{i}_lower", bound.lower |
| 103 | + ) |
| 104 | + if bound.upper: |
| 105 | + yield MetricSample( |
| 106 | + ts, mid, cid, f"{met}_bound_{i}_upper", bound.upper |
| 107 | + ) |
| 108 | + |
| 109 | + for state in getattr(item, "states", []): |
| 110 | + ts = state.sampled_at.ToDatetime().replace(tzinfo=timezone.utc) |
| 111 | + for name, category in { |
| 112 | + "state": getattr(state, "states", []), |
| 113 | + "warning": getattr(state, "warnings", []), |
| 114 | + "error": getattr(state, "errors", []), |
| 115 | + }.items(): |
| 116 | + if not isinstance(category, Iterable): |
| 117 | + continue |
| 118 | + for s in category: |
| 119 | + yield MetricSample(ts, mid, cid, name, s) |
| 120 | + |
| 121 | + |
| 122 | +@dataclass(frozen=True) |
| 123 | +class ComponentsDataBatch(GenericDataBatch): |
| 124 | + """Batch of microgrid components data.""" |
| 125 | + |
| 126 | + def __init__(self, data_pb: PBReceiveMicrogridComponentsDataStreamResponse): |
| 127 | + """Initialize the ComponentsDataBatch. |
| 128 | +
|
| 129 | + Args: |
| 130 | + data_pb: The underlying protobuf message. |
| 131 | + """ |
| 132 | + super().__init__( |
| 133 | + data_pb, id_attr="component_id", items_attr="components", has_bounds=True |
| 134 | + ) |
| 135 | + |
| 136 | + |
| 137 | +@dataclass(frozen=True) |
| 138 | +class SensorsDataBatch(GenericDataBatch): |
| 139 | + """Batch of microgrid sensors data.""" |
| 140 | + |
| 141 | + def __init__(self, data_pb: PBReceiveMicrogridSensorsDataStreamResponse): |
| 142 | + """Initialize the SensorsDataBatch. |
| 143 | +
|
| 144 | + Args: |
| 145 | + data_pb: The underlying protobuf message. |
| 146 | + """ |
| 147 | + super().__init__(data_pb, id_attr="sensor_id", items_attr="sensors") |
| 148 | + |
| 149 | + |
| 150 | +@dataclass(frozen=True) |
| 151 | +class AggregatedMetric: |
| 152 | + """An aggregated metric sample returned by the Reporting service.""" |
| 153 | + |
| 154 | + _data_pb: PBAggregatedStreamResponse |
| 155 | + """The underlying protobuf message.""" |
| 156 | + |
| 157 | + def sample(self) -> MetricSample: |
| 158 | + """Return the aggregated metric sample.""" |
| 159 | + return MetricSample( |
| 160 | + timestamp=self._data_pb.sample.sampled_at.ToDatetime().replace( |
| 161 | + tzinfo=timezone.utc |
| 162 | + ), |
| 163 | + microgrid_id=self._data_pb.aggregation_config.microgrid_id, |
| 164 | + component_id=self._data_pb.aggregation_config.aggregation_formula, |
| 165 | + metric=self._data_pb.aggregation_config.metric, |
| 166 | + value=self._data_pb.sample.sample.value, |
| 167 | + ) |
0 commit comments