Skip to content

v1alpha8

frequenz.client.common.grid.proto.v1alpha8 ¤

Conversion of grid objects from/to protobuf v1alpha8.

Functions:¤

frequenz.client.common.grid.proto.v1alpha8.delivery_area_from_proto ¤

delivery_area_from_proto(
    message: DeliveryArea,
) -> DeliveryArea

Convert a protobuf message to a DeliveryArea object.

Deprecated

Use delivery_area_from_proto2 instead. The new converter distinguishes well-formed from malformed data at the type level (DeliveryArea | InvalidDeliveryArea) rather than silently constructing a DeliveryArea with invalid content.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: DeliveryArea

RETURNS DESCRIPTION
DeliveryArea

The corresponding DeliveryArea object.
Source code in src/frequenz/client/common/grid/proto/v1alpha8/_delivery_area.py 
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 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
@deprecated(
    "`delivery_area_from_proto` is deprecated; use "
    "`delivery_area_from_proto2` (returns "
    "`DeliveryArea | InvalidDeliveryArea`) instead."
)
def delivery_area_from_proto(  # noqa: DOC502
    message: delivery_area_pb2.DeliveryArea,
) -> DeliveryArea:
    """Convert a protobuf message to a [`DeliveryArea`][....DeliveryArea] object.

    Warning: Deprecated
        Use [`delivery_area_from_proto2`][..delivery_area_from_proto2]
        instead. The new converter distinguishes well-formed from
        malformed data at the type level
        (`DeliveryArea | InvalidDeliveryArea`) rather than silently
        constructing a `DeliveryArea` with invalid content.

    Args:
        message: The protobuf message to convert.

    Returns:
        The corresponding [`DeliveryArea`][....DeliveryArea] object.
    """
    issues: list[str] = []

    code = message.code or None
    if code is None:
        issues.append("code is empty")

    raw_code_type = message.code_type
    code_type: EnergyMarketCodeType | int = (
        raw_code_type
        if raw_code_type == 0
        else energy_market_code_type_from_proto(raw_code_type)
    )
    if raw_code_type == 0:
        issues.append("code_type is unspecified")
    elif isinstance(code_type, int):
        issues.append("code_type is unrecognized")

    if issues:
        _logger.warning(
            "Found issues in delivery area: %s | Protobuf message:\n%s",
            ", ".join(issues),
            message,
        )

    # `DeliveryArea` emits a `DeprecationWarning` when constructed with
    # invalid data. This function is `@deprecated` itself, callers will see the
    # outer notice pointing to `delivery_area_from_proto2`. Suppress the inner
    # warning here so we don't double-warn.
    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        return DeliveryArea(code=code, code_type=code_type)

frequenz.client.common.grid.proto.v1alpha8.delivery_area_from_proto2 ¤

delivery_area_from_proto2(
    message: DeliveryArea,
) -> DeliveryArea | InvalidDeliveryArea

Convert a protobuf message to a delivery area object.

A well-formed message becomes a DeliveryArea; a message that fails the DeliveryArea invariant becomes an InvalidDeliveryArea carrying the raw wire data so callers can inspect or report it.

Unknown int code_type values are treated as valid to preserve forward compatibility with new protobuf enum values.

code_type of 0 will be considered invalid in the future

A 0 value for code_type means it is UNSPECIFIED, which should not be a valid value, but currently this field is not always being set, and we normally fall back to a well-known default, so considering it a validation failure at the moment is not practical.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: DeliveryArea

RETURNS DESCRIPTION
DeliveryArea | InvalidDeliveryArea

A DeliveryArea when the wire data is well-formed, an InvalidDeliveryArea otherwise.
Source code in src/frequenz/client/common/grid/proto/v1alpha8/_delivery_area.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
139
140
141
142
def delivery_area_from_proto2(
    message: delivery_area_pb2.DeliveryArea,
) -> DeliveryArea | InvalidDeliveryArea:
    """Convert a protobuf message to a delivery area object.

    A well-formed message becomes a [`DeliveryArea`][....DeliveryArea]; a
    message that fails the `DeliveryArea` invariant becomes an
    [`InvalidDeliveryArea`][....InvalidDeliveryArea] carrying the raw wire
    data so callers can inspect or report it.

    Unknown `int` `code_type` values are treated as valid to
    preserve forward compatibility with new protobuf enum values.

    Warning: `code_type` of `0` will be considered invalid in the future
        A `0` value for `code_type` means it is `UNSPECIFIED`, which should not
        be a valid value, but currently this field is not always being set, and
        we normally fall back to a well-known default, so considering it a
        validation failure at the moment is not practical.

    Args:
        message: The protobuf message to convert.

    Returns:
        A [`DeliveryArea`][....DeliveryArea] when the wire data is
            well-formed, an [`InvalidDeliveryArea`][....InvalidDeliveryArea]
            otherwise.
    """
    raw_code_type = message.code_type
    code_type: EnergyMarketCodeType | int = (
        raw_code_type
        if raw_code_type == 0
        else energy_market_code_type_from_proto(raw_code_type)
    )
    try:
        return DeliveryArea(
            code=message.code, code_type=code_type, _raise_on_invalid=True
        )
    except ValueError:
        pass
    return InvalidDeliveryArea(code=message.code, code_type=code_type)

frequenz.client.common.grid.proto.v1alpha8.energy_market_code_type_from_proto ¤

energy_market_code_type_from_proto(
    message: ValueType,
) -> EnergyMarketCodeType | int

Convert a protobuf EnergyMarketCodeType value to an enum member.

PARAMETER DESCRIPTION
message

The protobuf message to convert.

TYPE: ValueType

RETURNS DESCRIPTION
EnergyMarketCodeType | int

The corresponding EnergyMarketCodeType enum member, or the raw int if the protobuf value is not recognized.
Source code in src/frequenz/client/common/grid/proto/v1alpha8/_delivery_area.py 
18
19
20
21
22
23
24
25
26
27
28
29
30
def energy_market_code_type_from_proto(
    message: delivery_area_pb2.EnergyMarketCodeType.ValueType,
) -> EnergyMarketCodeType | int:
    """Convert a protobuf `EnergyMarketCodeType` value to an enum member.

    Args:
        message: The protobuf message to convert.

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

frequenz.client.common.grid.proto.v1alpha8.energy_market_code_type_to_proto ¤

energy_market_code_type_to_proto(
    code_type: EnergyMarketCodeType,
) -> ValueType

Convert a EnergyMarketCodeType enum member to a protobuf value.

PARAMETER DESCRIPTION
code_type

The enum member to convert.

TYPE: EnergyMarketCodeType

RETURNS DESCRIPTION
ValueType

The corresponding protobuf EnergyMarketCodeType value.
Source code in src/frequenz/client/common/grid/proto/v1alpha8/_delivery_area.py 
33
34
35
36
37
38
39
40
41
42
43
44
def energy_market_code_type_to_proto(
    code_type: EnergyMarketCodeType,
) -> delivery_area_pb2.EnergyMarketCodeType.ValueType:
    """Convert a [`EnergyMarketCodeType`][....EnergyMarketCodeType] enum member to a protobuf value.

    Args:
        code_type: The enum member to convert.

    Returns:
        The corresponding protobuf `EnergyMarketCodeType` value.
    """
    return delivery_area_pb2.EnergyMarketCodeType.ValueType(code_type.value)