Skip to content

v1alpha8

frequenz.client.common.metrics.proto.v1alpha8 ¤

Conversion of metrics enums from/to protobuf v1alpha8.

Functions:¤

frequenz.client.common.metrics.proto.v1alpha8.aggregated_metric_sample_from_proto ¤

aggregated_metric_sample_from_proto(
    message: AggregatedMetricValue,
) -> AggregatedMetricValue

Convert a protobuf message to an AggregatedMetricValue object.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: AggregatedMetricValue

RETURNS DESCRIPTION
AggregatedMetricValue

The resulting AggregatedMetricValue object.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_sample.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def aggregated_metric_sample_from_proto(
    message: metrics_pb2.AggregatedMetricValue,
) -> AggregatedMetricValue:
    """Convert a protobuf message to an [`AggregatedMetricValue`][....AggregatedMetricValue] object.

    Args:
        message: The protobuf message to convert.

    Returns:
        The resulting [`AggregatedMetricValue`][....AggregatedMetricValue] object.
    """
    return AggregatedMetricValue(
        avg=message.avg_value,
        min=message.min_value if message.HasField("min_value") else None,
        max=message.max_value if message.HasField("max_value") else None,
        raw=message.raw_values,
    )

frequenz.client.common.metrics.proto.v1alpha8.bounds_from_proto ¤

bounds_from_proto(message: Bounds) -> Bounds

Create a Bounds object from a protobuf message.

Deprecated

Use bounds_from_proto2 instead. The new converter distinguishes well-formed from malformed data at the type level (Bounds | InvalidBounds) rather than raising a ValueError when the invariant fires.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: Bounds

RETURNS DESCRIPTION
Bounds

The corresponding Bounds object.
RAISES DESCRIPTION
ValueError

If the message is not valid.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_bounds.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
@deprecated(
    "`bounds_from_proto` is deprecated; use "
    "`bounds_from_proto2` (returns `Bounds | InvalidBounds`) instead."
)
def bounds_from_proto(message: bounds_pb2.Bounds) -> Bounds:  # noqa: DOC502
    """Create a [`Bounds`][....Bounds] object from a protobuf message.

    Warning: Deprecated
        Use [`bounds_from_proto2`][..bounds_from_proto2] instead. The new
        converter distinguishes well-formed from malformed data at the
        type level (`Bounds | InvalidBounds`) rather than raising a
        `ValueError` when the invariant fires.

    Args:
        message: The protobuf message to convert.

    Returns:
        The corresponding [`Bounds`][....Bounds] object.

    Raises:
        ValueError: If the message is not valid.
    """
    return Bounds(
        lower=message.lower if message.HasField("lower") else None,
        upper=message.upper if message.HasField("upper") else None,
    )

frequenz.client.common.metrics.proto.v1alpha8.bounds_from_proto2 ¤

bounds_from_proto2(
    message: Bounds,
) -> Bounds | InvalidBounds

Create bounds from a protobuf message, preserving malformed data.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: Bounds

RETURNS DESCRIPTION
Bounds | InvalidBounds

A Bounds when the values form a valid range, or an InvalidBounds preserving values that violate lower <= upper. A present but empty protobuf message becomes an unbounded Bounds().
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_bounds.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
def bounds_from_proto2(
    message: bounds_pb2.Bounds,
) -> Bounds | InvalidBounds:
    """Create bounds from a protobuf message, preserving malformed data.

    Args:
        message: The protobuf message to convert.

    Returns:
        A [`Bounds`][....Bounds] when the values form a valid range, or an
            [`InvalidBounds`][....InvalidBounds] preserving values that
            violate `lower <= upper`. A present but empty protobuf message
            becomes an unbounded `Bounds()`.
    """
    lower = message.lower if message.HasField("lower") else None
    upper = message.upper if message.HasField("upper") else None
    try:
        return Bounds(lower=lower, upper=upper)
    except ValueError:
        pass
    return InvalidBounds(lower=lower, upper=upper)

frequenz.client.common.metrics.proto.v1alpha8.bounds_from_proto_with_issues ¤

bounds_from_proto_with_issues(
    message: Bounds,
    *,
    major_issues: list[str],
    minor_issues: list[str]
) -> Bounds | None

Create a Bounds object from a protobuf message, collecting issues.

Deprecated

Use bounds_from_proto2 instead and inspect the returned type. The new converter distinguishes well-formed from malformed data at the type level (Bounds | InvalidBounds) rather than routing invalid data through a side-channel string list.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: Bounds

major_issues

A list to append major issues to.

TYPE: list[str]

minor_issues

A list to append minor issues to.

TYPE: list[str]

RETURNS DESCRIPTION
Bounds | None

The corresponding Bounds object.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_bounds.py 
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
@deprecated(
    "`bounds_from_proto_with_issues` is deprecated; use "
    "`bounds_from_proto2` (returns `Bounds | InvalidBounds`) and inspect "
    "the returned type instead."
)
def bounds_from_proto_with_issues(
    message: bounds_pb2.Bounds,
    *,
    major_issues: list[str],
    minor_issues: list[str],  # pylint: disable=unused-argument
) -> Bounds | None:  # noqa: DOC502
    """Create a [`Bounds`][....Bounds] object from a protobuf message, collecting issues.

    Warning: Deprecated
        Use [`bounds_from_proto2`][..bounds_from_proto2] instead and
        inspect the returned type. The new converter distinguishes
        well-formed from malformed data at the type level
        (`Bounds | InvalidBounds`) rather than routing invalid data
        through a side-channel string list.

    Args:
        message: The protobuf message to convert.
        major_issues: A list to append major issues to.
        minor_issues: A list to append minor issues to.

    Returns:
        The corresponding [`Bounds`][....Bounds] object.
    """
    try:
        return Bounds(
            lower=message.lower if message.HasField("lower") else None,
            upper=message.upper if message.HasField("upper") else None,
        )
    except ValueError as exc:
        major_issues.append(str(exc))
        return None

frequenz.client.common.metrics.proto.v1alpha8.bounds_set_from_proto ¤

bounds_set_from_proto(
    messages: Sequence[Bounds],
) -> BoundsSet | InvalidBoundsSet

Convert a sequence of bounds messages into a single bounds set.

This is the multi-bound counterpart of bounds_from_proto2: it converts each message and combines the results.

PARAMETER DESCRIPTION
messages

The bounds messages to convert.

TYPE: Sequence[Bounds]

RETURNS DESCRIPTION
BoundsSet | InvalidBoundsSet

A BoundsSet (the union of the bounds) when every message is well-formed, or an InvalidBoundsSet preserving all the raw bounds in order when any message is malformed.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_bounds.py 
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def bounds_set_from_proto(
    messages: Sequence[bounds_pb2.Bounds],
) -> BoundsSet | InvalidBoundsSet:
    """Convert a sequence of bounds messages into a single bounds set.

    This is the multi-bound counterpart of
    [`bounds_from_proto2`][..bounds_from_proto2]: it converts each message and
    combines the results.

    Args:
        messages: The bounds messages to convert.

    Returns:
        A [`BoundsSet`][....BoundsSet] (the union of the bounds) when every
            message is well-formed, or an
            [`InvalidBoundsSet`][....InvalidBoundsSet] preserving all the raw
            bounds in order when any message is malformed.
    """
    valid: list[Bounds] = []
    raw: list[Bounds | InvalidBounds] = []
    has_invalid = False
    for pb_bound in messages:
        match bounds_from_proto2(pb_bound):
            case Bounds() as bound:
                valid.append(bound)
                raw.append(bound)
            case InvalidBounds() as bound:
                has_invalid = True
                raw.append(bound)
            case unknown:
                assert_never(unknown)

    if has_invalid:
        return InvalidBoundsSet(bounds=tuple(raw))
    return BoundsSet(bounds=tuple(valid))

frequenz.client.common.metrics.proto.v1alpha8.metric_connection_category_from_proto ¤

metric_connection_category_from_proto(
    message: ValueType,
) -> MetricConnectionCategory | int

Convert a protobuf MetricConnectionCategory value to an enum member.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: ValueType

RETURNS DESCRIPTION
MetricConnectionCategory | int

The corresponding MetricConnectionCategory enum member, or the raw int if the protobuf value is not recognized.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_metric_connection_category.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
def metric_connection_category_from_proto(
    message: metrics_pb2.MetricConnectionCategory.ValueType,
) -> MetricConnectionCategory | int:
    """Convert a protobuf `MetricConnectionCategory` value to an enum member.

    Args:
        message: The protobuf message to convert.

    Returns:
        The corresponding
            [`MetricConnectionCategory`][....MetricConnectionCategory] enum
            member, or the raw [`int`][] if the protobuf value is not recognized.
    """
    return enum_from_proto(message, MetricConnectionCategory)

frequenz.client.common.metrics.proto.v1alpha8.metric_connection_category_to_proto ¤

metric_connection_category_to_proto(
    category: MetricConnectionCategory,
) -> ValueType

Convert a MetricConnectionCategory enum member to a protobuf value.

PARAMETER DESCRIPTION
category

The MetricConnectionCategory enum member to convert.

TYPE: MetricConnectionCategory

RETURNS DESCRIPTION
ValueType

The corresponding protobuf MetricConnectionCategory value.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_metric_connection_category.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
def metric_connection_category_to_proto(
    category: MetricConnectionCategory,
) -> metrics_pb2.MetricConnectionCategory.ValueType:
    """Convert a `MetricConnectionCategory` enum member to a protobuf value.

    Args:
        category: The [`MetricConnectionCategory`][....MetricConnectionCategory]
            enum member to convert.

    Returns:
        The corresponding protobuf `MetricConnectionCategory` value.
    """
    return metrics_pb2.MetricConnectionCategory.ValueType(category.value)

frequenz.client.common.metrics.proto.v1alpha8.metric_connection_from_proto ¤

metric_connection_from_proto(
    message: MetricConnection,
) -> MetricConnection

Convert a protobuf message to a MetricConnection object.

An unspecified category is preserved as the raw integer 0 and an unrecognized one as its raw integer value in the category field (typed MetricConnectionCategory | int), so malformed input is surfaced through the returned type rather than a side channel.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: MetricConnection

RETURNS DESCRIPTION
MetricConnection

The resulting MetricConnection object.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_sample.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def metric_connection_from_proto(
    message: metrics_pb2.MetricConnection,
) -> MetricConnection:
    """Convert a protobuf message to a [`MetricConnection`][....MetricConnection] object.

    An unspecified category is preserved as the raw integer `0` and an
    unrecognized one as its raw integer value in the `category` field (typed
    `MetricConnectionCategory | int`), so malformed input is surfaced through
    the returned type rather than a side channel.

    Args:
        message: The protobuf message to convert.

    Returns:
        The resulting [`MetricConnection`][....MetricConnection] object.
    """
    raw = message.category
    category: MetricConnectionCategory | int = (
        raw if raw == 0 else metric_connection_category_from_proto(raw)
    )

    return MetricConnection(
        category=category,
        name=message.name,
    )

frequenz.client.common.metrics.proto.v1alpha8.metric_connection_from_proto_with_issues ¤

metric_connection_from_proto_with_issues(
    message: MetricConnection,
    *,
    major_issues: list[str],
    minor_issues: list[str]
) -> MetricConnection

Convert a protobuf message to a MetricConnection object.

Deprecated

Use metric_connection_from_proto instead and inspect the returned type. The new converter encodes an unspecified or unrecognized category in the returned MetricConnection.category field (MetricConnectionCategory | int) rather than routing it through a side-channel string list.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: MetricConnection

major_issues

A list to append major issues to.

TYPE: list[str]

minor_issues

A list to append minor issues to.

TYPE: list[str]

RETURNS DESCRIPTION
MetricConnection

The resulting MetricConnection object.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_sample.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
@deprecated(
    "`metric_connection_from_proto_with_issues` is deprecated; use "
    "`metric_connection_from_proto` and inspect the returned type instead."
)
def metric_connection_from_proto_with_issues(
    message: metrics_pb2.MetricConnection,
    *,
    major_issues: list[str],
    minor_issues: list[str],
) -> MetricConnection:
    """Convert a protobuf message to a [`MetricConnection`][....MetricConnection] object.

    Warning: Deprecated
        Use [`metric_connection_from_proto`][..metric_connection_from_proto]
        instead and inspect the returned type. The new converter encodes an
        unspecified or unrecognized category in the returned
        `MetricConnection.category` field (`MetricConnectionCategory | int`)
        rather than routing it through a side-channel string list.

    Args:
        message: The protobuf message to convert.
        major_issues: A list to append major issues to.
        minor_issues: A list to append minor issues to.

    Returns:
        The resulting [`MetricConnection`][....MetricConnection] object.
    """
    raw = message.category
    category: MetricConnectionCategory | int = (
        raw if raw == 0 else metric_connection_category_from_proto(raw)
    )

    if raw == 0:
        major_issues.append("unspecified category")
    elif isinstance(category, int):
        minor_issues.append(f"unrecognized category {category}")

    return MetricConnection(
        category=category,
        name=message.name,
    )

frequenz.client.common.metrics.proto.v1alpha8.metric_from_proto ¤

metric_from_proto(message: ValueType) -> Metric | int

Convert a protobuf Metric message to a Metric enum member.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: ValueType

RETURNS DESCRIPTION
Metric | int

The corresponding Metric enum member, or the raw int if the protobuf value is not recognized.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_metric.py 
12
13
14
15
16
17
18
19
20
21
22
def metric_from_proto(message: metrics_pb2.Metric.ValueType) -> Metric | int:
    """Convert a protobuf `Metric` message to a [`Metric`][....Metric] enum member.

    Args:
        message: The protobuf message to convert.

    Returns:
        The corresponding [`Metric`][....Metric] enum member, or the raw [`int`][]
            if the protobuf value is not recognized.
    """
    return enum_from_proto(message, Metric)

frequenz.client.common.metrics.proto.v1alpha8.metric_sample_from_proto ¤

metric_sample_from_proto(
    message: MetricSample,
) -> MetricSample

Convert a protobuf message to a MetricSample object.

Malformed or forward-incompatible input is surfaced through the returned type rather than a side channel: an unspecified metric is preserved as the raw integer 0 and an unrecognized one as its raw integer value in the metric field (typed Metric | int), and malformed bounds as an InvalidBoundsSet in bounds_set.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: MetricSample

RETURNS DESCRIPTION
MetricSample

The resulting MetricSample object.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_sample.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
def metric_sample_from_proto(
    message: metrics_pb2.MetricSample,
) -> MetricSample:
    """Convert a protobuf message to a [`MetricSample`][....MetricSample] object.

    Malformed or forward-incompatible input is surfaced through the returned
    type rather than a side channel: an unspecified metric is preserved as the
    raw integer `0` and an unrecognized one as its raw integer value in the
    `metric` field (typed `Metric | int`), and malformed bounds as an
    `InvalidBoundsSet` in `bounds_set`.

    Args:
        message: The protobuf message to convert.

    Returns:
        The resulting [`MetricSample`][....MetricSample] object.
    """
    sample_time = datetime_from_proto(message.sample_time)

    raw_metric = message.metric
    metric: Metric | int = (
        raw_metric if raw_metric == 0 else metric_from_proto(raw_metric)
    )

    value: float | AggregatedMetricValue | None = None
    if message.HasField("value"):
        match message.value.WhichOneof("metric_value_variant"):
            case "simple_metric":
                value = message.value.simple_metric.value
            case "aggregated_metric":
                value = aggregated_metric_sample_from_proto(
                    message.value.aggregated_metric
                )

    bounds_set = bounds_set_from_proto(message.bounds)

    connection = None
    if message.HasField("connection"):
        connection = metric_connection_from_proto(message.connection)

    return MetricSample(
        sample_time=sample_time,
        metric=metric,
        value=value,
        bounds_set=bounds_set,
        connection=connection,
    )

frequenz.client.common.metrics.proto.v1alpha8.metric_sample_from_proto_with_issues ¤

metric_sample_from_proto_with_issues(
    message: MetricSample,
    *,
    major_issues: list[str],
    minor_issues: list[str]
) -> MetricSample

Convert a protobuf message to a MetricSample object.

Deprecated

Use metric_sample_from_proto instead and inspect the returned type. The new converter encodes an unspecified or unrecognized metric (Metric | int) and malformed bounds (InvalidBoundsSet) in the returned MetricSample rather than routing them through a side-channel string list.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: MetricSample

major_issues

A list to append major issues to.

TYPE: list[str]

minor_issues

A list to append minor issues to.

TYPE: list[str]

RETURNS DESCRIPTION
MetricSample

The resulting MetricSample object.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_sample.py 
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
@deprecated(
    "`metric_sample_from_proto_with_issues` is deprecated; use "
    "`metric_sample_from_proto` and inspect the returned type instead."
)
def metric_sample_from_proto_with_issues(
    message: metrics_pb2.MetricSample,
    *,
    major_issues: list[str],
    minor_issues: list[str],
) -> MetricSample:
    """Convert a protobuf message to a [`MetricSample`][....MetricSample] object.

    Warning: Deprecated
        Use [`metric_sample_from_proto`][..metric_sample_from_proto] instead
        and inspect the returned type. The new converter encodes an
        unspecified or unrecognized `metric` (`Metric | int`) and malformed
        bounds (`InvalidBoundsSet`) in the returned `MetricSample` rather than
        routing them through a side-channel string list.

    Args:
        message: The protobuf message to convert.
        major_issues: A list to append major issues to.
        minor_issues: A list to append minor issues to.

    Returns:
        The resulting [`MetricSample`][....MetricSample] object.
    """
    sample_time = datetime_from_proto(message.sample_time)

    raw_metric = message.metric
    metric: Metric | int = (
        raw_metric if raw_metric == 0 else metric_from_proto(raw_metric)
    )

    value: float | AggregatedMetricValue | None = None
    if message.HasField("value"):
        match message.value.WhichOneof("metric_value_variant"):
            case "simple_metric":
                value = message.value.simple_metric.value
            case "aggregated_metric":
                value = aggregated_metric_sample_from_proto(
                    message.value.aggregated_metric
                )

    bounds_set = bounds_set_from_proto(message.bounds)

    connection = None
    if message.HasField("connection"):
        with warnings.catch_warnings():
            warnings.filterwarnings("ignore", category=DeprecationWarning)
            connection = metric_connection_from_proto_with_issues(
                message.connection, major_issues=major_issues, minor_issues=minor_issues
            )

    return MetricSample(
        sample_time=sample_time,
        metric=metric,
        value=value,
        bounds_set=bounds_set,
        connection=connection,
    )

frequenz.client.common.metrics.proto.v1alpha8.metric_to_proto ¤

metric_to_proto(metric: Metric) -> ValueType

Convert a Metric enum member to a protobuf Metric value.

PARAMETER DESCRIPTION
metric

The enum member to convert.

TYPE: Metric

RETURNS DESCRIPTION
ValueType

The corresponding protobuf Metric value.
Source code in src/frequenz/client/common/metrics/proto/v1alpha8/_metric.py 
25
26
27
28
29
30
31
32
33
34
def metric_to_proto(metric: Metric) -> metrics_pb2.Metric.ValueType:
    """Convert a [`Metric`][....Metric] enum member to a protobuf `Metric` value.

    Args:
        metric: The enum member to convert.

    Returns:
        The corresponding protobuf `Metric` value.
    """
    return metrics_pb2.Metric.ValueType(metric.value)