v1alpha8

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8

Conversion of electrical component enums from/to protobuf v1alpha8.

Attributes

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.AbstractTypedTypes module-attribute

AbstractTypedTypes: TypeAlias = (
    Battery | EvCharger | Inverter
)

Type alias for all abstract electrical component classes that have a type enum.

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.ConcreteTypedTypes module-attribute

ConcreteTypedTypes: TypeAlias = (
    LiIonBattery
    | NaIonBattery
    | UnspecifiedBattery
    | AcEvCharger
    | DcEvCharger
    | HybridEvCharger
    | UnspecifiedEvCharger
    | BatteryInverter
    | PvInverter
    | HybridInverter
    | UnspecifiedInverter
)

Type alias for all concrete electrical component classes that have a type enum.

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.ConcreteTypelessTypes module-attribute

ConcreteTypelessTypes: TypeAlias = (
    SpecifiedConcreteTypelessTypes
    | UnspecifiedElectricalComponent
)

Type alias for all concrete electrical component classes that don't have a type enum.

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.ConvertibleElectricalComponentTypes module-attribute

ConvertibleElectricalComponentTypes: TypeAlias = (
    ConcreteTypedTypes
    | AbstractTypedTypes
    | ConcreteTypelessTypes
)

Type alias for all classes that can be converted to protobuf category/subtype pairs.

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.ProtoTypeEnums module-attribute

ProtoTypeEnums: TypeAlias = (
    electrical_components_pb2.BatteryType.ValueType
    | electrical_components_pb2.EvChargerType.ValueType
    | electrical_components_pb2.InverterType.ValueType
)

Type alias for all protobuf type enums for electrical components.

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.SpecifiedConcreteTypelessTypes module-attribute

SpecifiedConcreteTypelessTypes: TypeAlias = (
    Breaker
    | CapacitorBank
    | Chp
    | Converter
    | CryptoMiner
    | Electrolyzer
    | GridConnectionPoint
    | Hvac
    | Meter
    | Plc
    | PowerTransformer
    | Precharger
    | StaticTransferSwitch
    | SteamBoiler
    | UninterruptiblePowerSupply
    | WindTurbine
)

Type alias for all specified concrete electrical component classes without a type enum.

Functions:

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_category_from_proto

electrical_component_category_from_proto(
    message: ValueType,
) -> ElectricalComponentCategory | int

Convert a protobuf ElectricalComponentCategory value to an enum member.

PARAMETER	DESCRIPTION
message	The protobuf message to convert. TYPE: ValueType

RETURNS	DESCRIPTION
ElectricalComponentCategory | int	The corresponding ElectricalComponentCategory enum member, or the raw int if the protobuf value is not recognized.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_category.py

@typing_extensions.deprecated(
    "electrical_component_category_from_proto() is deprecated; use "
    "electrical_component_class_from_proto() instead."
)
def electrical_component_category_from_proto(
    message: electrical_components_pb2.ElectricalComponentCategory.ValueType,
) -> ElectricalComponentCategory | int:
    """Convert a protobuf `ElectricalComponentCategory` value to an enum member.

    Args:
        message: The protobuf message to convert.

    Returns:
        The corresponding
            [`ElectricalComponentCategory`][....ElectricalComponentCategory] enum
            member, or the raw [`int`][] if the protobuf value is not recognized.
    """
    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        return enum_from_proto(message, ElectricalComponentCategory)

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_category_to_proto

electrical_component_category_to_proto(
    category: ElectricalComponentCategory,
) -> ValueType

Convert an ElectricalComponentCategory enum member to a protobuf value.

PARAMETER	DESCRIPTION
category	The ElectricalComponentCategory enum member to convert. TYPE: ElectricalComponentCategory

RETURNS	DESCRIPTION
ValueType	The corresponding protobuf ElectricalComponentCategory value.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_category.py

@typing_extensions.deprecated(
    "electrical_component_category_to_proto() is deprecated; use "
    "electrical_component_class_to_proto() instead."
)
def electrical_component_category_to_proto(
    category: ElectricalComponentCategory,
) -> electrical_components_pb2.ElectricalComponentCategory.ValueType:
    """Convert an `ElectricalComponentCategory` enum member to a protobuf value.

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

    Returns:
        The corresponding protobuf `ElectricalComponentCategory` value.
    """
    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        return electrical_components_pb2.ElectricalComponentCategory.ValueType(
            category.value
        )

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_class_from_proto

electrical_component_class_from_proto(
    category: ValueType,
    subtype: ProtoTypeEnums | None = None,
) -> type[
    AbstractTypedTypes
    | ConcreteTypedTypes
    | ConcreteTypelessTypes
    | UnrecognizedBattery
    | UnrecognizedEvCharger
    | UnrecognizedInverter
    | UnrecognizedElectricalComponent
]

Convert a protobuf (category, subtype) pair to an electrical component class.

This is the inverse of electrical_component_class_to_proto: every input it can produce round-trips back to the matching class here. Returns the class only — never an instance — because the protobuf identity pair does not carry the rest of the component state.

Conversion rules:

• (BATTERY, None) → Battery (abstract).
• (BATTERY, BATTERY_TYPE_UNSPECIFIED) → UnspecifiedBattery.
• (BATTERY, BATTERY_TYPE_LI_ION) → LiIonBattery.
• (BATTERY, BATTERY_TYPE_NA_ION) → NaIonBattery.
• (BATTERY, <unknown subtype int>) → UnrecognizedBattery.
• (EV_CHARGER, None) → EvCharger (abstract).
• (EV_CHARGER, EV_CHARGER_TYPE_UNSPECIFIED) → UnspecifiedEvCharger.
• (EV_CHARGER, EV_CHARGER_TYPE_AC) → AcEvCharger.
• (EV_CHARGER, EV_CHARGER_TYPE_DC) → DcEvCharger.
• (EV_CHARGER, EV_CHARGER_TYPE_HYBRID) → HybridEvCharger.
• (EV_CHARGER, <unknown subtype int>) → UnrecognizedEvCharger.
• (INVERTER, None) → Inverter (abstract).
• (INVERTER, INVERTER_TYPE_UNSPECIFIED) → UnspecifiedInverter.
• (INVERTER, INVERTER_TYPE_BATTERY) → BatteryInverter.
• (INVERTER, INVERTER_TYPE_PV) → PvInverter.
• (INVERTER, INVERTER_TYPE_HYBRID) → HybridInverter.
• (INVERTER, <unknown subtype int>) → UnrecognizedInverter.
• (UNSPECIFIED, None) → UnspecifiedElectricalComponent.
• (<any other typeless category>, None) → its concrete typeless class (Breaker, Meter, ... one per category).
• (<any known typeless category>, <non-None subtype>) → raises ValueError.
• (<unknown category int>, <any subtype>) → UnrecognizedElectricalComponent (subtype silently dropped).

Notes

• For typed categories the abstract base (Battery/EvCharger/Inverter) is returned only when subtype is None; passing the concrete TYPE_UNSPECIFIED int returns the corresponding Unspecified* class instead. This is the same distinction electrical_component_class_to_proto makes on the way out.
• For known typeless categories any non-None subtype is an error because the protobuf wire format has no such combination.
• For unknown categories the subtype is silently dropped — the integer category alone is enough to mark the component as unrecognized, and the caller passed the subtype in so they already have it.

PARAMETER	DESCRIPTION
category	A protobuf electrical component category value. TYPE: ValueType
subtype	A protobuf subtype value (BatteryType, EvChargerType or InverterType .ValueType), or None for typeless categories and abstract typed bases. TYPE: ProtoTypeEnums | None DEFAULT: None

RETURNS	DESCRIPTION
type[AbstractTypedTypes | ConcreteTypedTypes | ConcreteTypelessTypes | UnrecognizedBattery | UnrecognizedEvCharger | UnrecognizedInverter | UnrecognizedElectricalComponent]	The corresponding electrical component class.

RAISES	DESCRIPTION
ValueError	If subtype is not None for a known typeless category — that combination has no representation in the protobuf wire format.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_electrical_component.py

def electrical_component_class_from_proto(
    category: electrical_components_pb2.ElectricalComponentCategory.ValueType,
    subtype: ProtoTypeEnums | None = None,
) -> type[
    AbstractTypedTypes
    | ConcreteTypedTypes
    | ConcreteTypelessTypes
    | UnrecognizedBattery
    | UnrecognizedEvCharger
    | UnrecognizedInverter
    | UnrecognizedElectricalComponent
]:
    """Convert a protobuf `(category, subtype)` pair to an electrical component class.

    This is the inverse of
    [`electrical_component_class_to_proto`][..electrical_component_class_to_proto]:
    every input it can produce round-trips back to the matching class here.
    Returns the class only — never an instance — because the protobuf identity
    pair does not carry the rest of the component state.

    Conversion rules:

    * `(BATTERY, None)` → `Battery` (abstract).
    * `(BATTERY, BATTERY_TYPE_UNSPECIFIED)` → `UnspecifiedBattery`.
    * `(BATTERY, BATTERY_TYPE_LI_ION)` → `LiIonBattery`.
    * `(BATTERY, BATTERY_TYPE_NA_ION)` → `NaIonBattery`.
    * `(BATTERY, <unknown subtype int>)` → `UnrecognizedBattery`.
    * `(EV_CHARGER, None)` → `EvCharger` (abstract).
    * `(EV_CHARGER, EV_CHARGER_TYPE_UNSPECIFIED)` → `UnspecifiedEvCharger`.
    * `(EV_CHARGER, EV_CHARGER_TYPE_AC)` → `AcEvCharger`.
    * `(EV_CHARGER, EV_CHARGER_TYPE_DC)` → `DcEvCharger`.
    * `(EV_CHARGER, EV_CHARGER_TYPE_HYBRID)` → `HybridEvCharger`.
    * `(EV_CHARGER, <unknown subtype int>)` → `UnrecognizedEvCharger`.
    * `(INVERTER, None)` → `Inverter` (abstract).
    * `(INVERTER, INVERTER_TYPE_UNSPECIFIED)` → `UnspecifiedInverter`.
    * `(INVERTER, INVERTER_TYPE_BATTERY)` → `BatteryInverter`.
    * `(INVERTER, INVERTER_TYPE_PV)` → `PvInverter`.
    * `(INVERTER, INVERTER_TYPE_HYBRID)` → `HybridInverter`.
    * `(INVERTER, <unknown subtype int>)` → `UnrecognizedInverter`.
    * `(UNSPECIFIED, None)` → `UnspecifiedElectricalComponent`.
    * `(<any other typeless category>, None)` → its concrete typeless class
      (`Breaker`, `Meter`, ... one per category).
    * `(<any known typeless category>, <non-None subtype>)` → raises
      [`ValueError`][].
    * `(<unknown category int>, <any subtype>)` → `UnrecognizedElectricalComponent`
      (subtype silently dropped).

    Notes:
        * For typed categories the abstract base
          (`Battery`/`EvCharger`/`Inverter`) is returned only when
          `subtype is None`; passing the concrete `TYPE_UNSPECIFIED`
          int returns the corresponding `Unspecified*` class instead. This is
          the same distinction `electrical_component_class_to_proto` makes on
          the way out.
        * For known typeless categories any non-`None` subtype is an error
          because the protobuf wire format has no such combination.
        * For unknown categories the subtype is silently dropped — the integer
          category alone is enough to mark the component as unrecognized, and
          the caller passed the subtype in so they already have it.

    Args:
        category: A protobuf electrical component category value.
        subtype: A protobuf subtype value (`BatteryType`, `EvChargerType`
            or `InverterType` `.ValueType`), or `None` for typeless
            categories and abstract typed bases.

    Returns:
        The corresponding electrical component class.

    Raises:
        ValueError: If `subtype` is not `None` for a known typeless category —
            that combination has no representation in the protobuf wire format.
    """
    abstract_base = _ABSTRACT_CLASS_BY_TYPED_PROTO_CATEGORY.get(category)
    if abstract_base is not None:
        if subtype is None:
            return abstract_base
        typed_class = _TYPED_CLASS_BY_PROTO.get((category, subtype))
        if typed_class is not None:
            return typed_class
        return _UNRECOGNIZED_CLASS_BY_TYPED_PROTO_CATEGORY[category]

    typeless_class = _TYPELESS_CLASS_BY_PROTO_CATEGORY.get(category)
    if typeless_class is not None:
        if subtype is not None:
            raise ValueError(
                f"protobuf subtype {int(subtype)!r} is not valid for typeless "
                f"category {int(category)!r}"
            )
        return typeless_class

    return UnrecognizedElectricalComponent

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_class_to_proto

electrical_component_class_to_proto(
    component: (
        LiIonBattery
        | NaIonBattery
        | UnspecifiedBattery
        | type[
            LiIonBattery | NaIonBattery | UnspecifiedBattery
        ]
    ),
) -> tuple[ValueType, ValueType]

electrical_component_class_to_proto(
    component: UnrecognizedBattery,
) -> tuple[ValueType, int]

electrical_component_class_to_proto(
    component: type[Battery],
) -> tuple[ValueType, ValueType | None]

electrical_component_class_to_proto(
    component: (
        AcEvCharger
        | DcEvCharger
        | HybridEvCharger
        | UnspecifiedEvCharger
        | type[
            AcEvCharger
            | DcEvCharger
            | HybridEvCharger
            | UnspecifiedEvCharger
        ]
    ),
) -> tuple[ValueType, ValueType]

electrical_component_class_to_proto(
    component: UnrecognizedEvCharger,
) -> tuple[ValueType, int]

electrical_component_class_to_proto(
    component: type[EvCharger],
) -> tuple[ValueType, ValueType | None]

electrical_component_class_to_proto(
    component: (
        BatteryInverter
        | PvInverter
        | HybridInverter
        | UnspecifiedInverter
        | type[
            BatteryInverter
            | PvInverter
            | HybridInverter
            | UnspecifiedInverter
        ]
    ),
) -> tuple[ValueType, ValueType]

electrical_component_class_to_proto(
    component: UnrecognizedInverter,
) -> tuple[ValueType, int]

electrical_component_class_to_proto(
    component: type[Inverter],
) -> tuple[ValueType, ValueType | None]

electrical_component_class_to_proto(
    component: (
        ConcreteTypelessTypes | type[ConcreteTypelessTypes]
    ),
) -> tuple[ValueType, None]

electrical_component_class_to_proto(
    component: UnrecognizedElectricalComponent,
) -> tuple[int, None]

electrical_component_class_to_proto(
    component: MismatchedCategoryElectricalComponent,
) -> tuple[int, None]

electrical_component_class_to_proto(
    component: (
        ElectricalComponentTypes
        | type[ConvertibleElectricalComponentTypes]
    ),
) -> tuple[ValueType | int, ProtoTypeEnums | int | None]

Convert an electrical component class or instance to its protobuf identity.

Returns the (category, subtype) pair the protobuf wire format uses for the given component. This is the inverse of electrical_component_class_from_proto for the classes and abstract bases it knows about.

Conversion rules (C = class, I = instance):

• LiIonBattery / NaIonBattery / UnspecifiedBattery (C or I) → (BATTERY, <matching BATTERY_TYPE_*>).
• UnrecognizedBattery instance → (BATTERY, instance.type) — preserves the raw int.
• AcEvCharger / DcEvCharger / HybridEvCharger / UnspecifiedEvCharger (C or I) → (EV_CHARGER, <matching EV_CHARGER_TYPE_*>).
• UnrecognizedEvCharger instance → (EV_CHARGER, instance.type).
• BatteryInverter / PvInverter / HybridInverter / UnspecifiedInverter (C or I) → (INVERTER, <matching INVERTER_TYPE_*>).
• UnrecognizedInverter instance → (INVERTER, instance.type).
• The abstract bases Battery / EvCharger / Inverter (class only) → ( <that category>, None).
• Any concrete typeless class — Breaker, CapacitorBank, ..., WindTurbine, GridConnectionPoint, PowerTransformer — (C or I) → ( <that category>, None).
• UnspecifiedElectricalComponent (C or I) → (UNSPECIFIED, None).
• UnrecognizedElectricalComponent instance → (instance.category, None) — preserves the raw int.
• MismatchedCategoryElectricalComponent instance → (instance.category, None).
• The per-family UnrecognizedBattery / UnrecognizedEvCharger / UnrecognizedInverter (class only) → ( <that family's category>, None) (the raw int is unavailable).

Key invariants:

• The abstract typed bases Battery, EvCharger, Inverter are distinct from their Unspecified* counterparts on the wire: abstract bases emit subtype=None, the Unspecified* classes emit subtype=<...TYPE_UNSPECIFIED> (the concrete protobuf 0 value). This mirrors how electrical_component_class_from_proto reads them back.
• Unrecognized* and MismatchedCategoryElectricalComponent are only meaningful as instances because the raw, possibly out-of-range category or subtype int lives on the instance. Passing the per-family UnrecognizedBattery/UnrecognizedEvCharger/UnrecognizedInverter as classes still succeeds (returning (category, None)), but the raw int is unavailable. Passing the top-level UnrecognizedElectricalComponent or MismatchedCategoryElectricalComponent as classes raises TypeError because no category is recoverable.

Note

Due to the way mypy resolves overloads, passing one of the abstract typed bases (e.g. Battery) returns the static type tuple[category, <subtype-enum> | None]: at runtime the subtype is always None. Callers that already know they are passing an abstract base usually just discard the subtype.

PARAMETER	DESCRIPTION
component	An electrical component class or instance to encode. TYPE: ElectricalComponentTypes | type[ConvertibleElectricalComponentTypes]

RETURNS	DESCRIPTION
tuple[ValueType | int, ProtoTypeEnums | int | None]	The (category, subtype) pair encoding component. The subtype is None for typeless categories and for the abstract typed bases.

RAISES	DESCRIPTION
TypeError	If component is a class this converter does not know how to encode (e.g. ElectricalComponent, ProblematicElectricalComponent, UnrecognizedElectricalComponent or MismatchedCategoryElectricalComponent passed as classes — for the latter two the raw category int lives on the instance and is unrecoverable from the class alone).

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_electrical_component.py

def electrical_component_class_to_proto(
    component: ElectricalComponentTypes | type[ConvertibleElectricalComponentTypes],
) -> tuple[
    electrical_components_pb2.ElectricalComponentCategory.ValueType | int,
    ProtoTypeEnums | int | None,
]:
    """Convert an electrical component class or instance to its protobuf identity.

    Returns the `(category, subtype)` pair the protobuf wire format uses for
    the given component. This is the inverse of
    [`electrical_component_class_from_proto`][..electrical_component_class_from_proto]
    for the classes and abstract bases it knows about.

    Conversion rules (`C` = class, `I` = instance):

    * `LiIonBattery` / `NaIonBattery` / `UnspecifiedBattery` (`C` or `I`)
      → `(BATTERY, <matching BATTERY_TYPE_*>)`.
    * `UnrecognizedBattery` **instance**
      → `(BATTERY, instance.type)` — preserves the raw int.
    * `AcEvCharger` / `DcEvCharger` / `HybridEvCharger` / `UnspecifiedEvCharger`
      (`C` or `I`) → `(EV_CHARGER, <matching EV_CHARGER_TYPE_*>)`.
    * `UnrecognizedEvCharger` **instance**
      → `(EV_CHARGER, instance.type)`.
    * `BatteryInverter` / `PvInverter` / `HybridInverter` / `UnspecifiedInverter`
      (`C` or `I`) → `(INVERTER, <matching INVERTER_TYPE_*>)`.
    * `UnrecognizedInverter` **instance**
      → `(INVERTER, instance.type)`.
    * The abstract bases `Battery` / `EvCharger` / `Inverter` (class only)
      → `( <that category>, None)`.
    * Any concrete typeless class — `Breaker`, `CapacitorBank`, ...,
      `WindTurbine`, `GridConnectionPoint`, `PowerTransformer` — (`C` or `I`)
      → `( <that category>, None)`.
    * `UnspecifiedElectricalComponent` (`C` or `I`)
      → `(UNSPECIFIED, None)`.
    * `UnrecognizedElectricalComponent` **instance**
      → `(instance.category, None)` — preserves the raw int.
    * `MismatchedCategoryElectricalComponent` **instance**
      → `(instance.category, None)`.
    * The per-family `UnrecognizedBattery` / `UnrecognizedEvCharger` /
      `UnrecognizedInverter` (class only) → `( <that family's category>, None)`
      (the raw int is unavailable).

    Key invariants:

    * The abstract typed bases `Battery`, `EvCharger`, `Inverter` are
      *distinct* from their `Unspecified*` counterparts on the wire: abstract
      bases emit `subtype=None`, the `Unspecified*` classes emit
      `subtype=<...TYPE_UNSPECIFIED>` (the concrete protobuf 0 value). This
      mirrors how
      [`electrical_component_class_from_proto`][..electrical_component_class_from_proto]
      reads them back.
    * `Unrecognized*` and `MismatchedCategoryElectricalComponent` are only
      meaningful as **instances** because the raw, possibly out-of-range
      category or subtype int lives on the instance. Passing the per-family
      `UnrecognizedBattery`/`UnrecognizedEvCharger`/`UnrecognizedInverter` as
      classes still succeeds (returning `(category, None)`), but the raw int
      is unavailable. Passing the top-level
      `UnrecognizedElectricalComponent` or `MismatchedCategoryElectricalComponent`
      as classes raises `TypeError` because no category is recoverable.

    Note:
        Due to the way `mypy` resolves overloads, passing one of the abstract
        typed bases (e.g. `Battery`) returns the static type
        `tuple[category, <subtype-enum> | None]`: at runtime the subtype is
        always `None`. Callers that already know they are passing an abstract
        base usually just discard the subtype.

    Args:
        component: An electrical component class or instance to encode.

    Returns:
        The `(category, subtype)` pair encoding `component`. The subtype is
            `None` for typeless categories and for the abstract typed bases.

    Raises:
        TypeError: If `component` is a class this converter does not know how
            to encode (e.g. `ElectricalComponent`, `ProblematicElectricalComponent`,
            `UnrecognizedElectricalComponent` or
            `MismatchedCategoryElectricalComponent` passed as classes — for
            the latter two the raw category int lives on the instance and is
            unrecoverable from the class alone).
    """
    unrecognized_subtype: int | None = None
    component_class: type[
        ConcreteTypedTypes
        | AbstractTypedTypes
        | ConcreteTypelessTypes
        | UnrecognizedBattery
        | UnrecognizedEvCharger
        | UnrecognizedInverter
    ]

    match component:
        case UnrecognizedElectricalComponent(category=category):
            return (category, None)
        case MismatchedCategoryElectricalComponent(category=category):
            return (category, None)
        case (
            UnrecognizedBattery(type=raw_subtype)
            | UnrecognizedEvCharger(type=raw_subtype)
            | UnrecognizedInverter(type=raw_subtype)
        ):
            component_class = type(component)
            unrecognized_subtype = raw_subtype
        case ElectricalComponent():
            component_class = type(component)
        case type() as klass:
            component_class = klass
        case unexpected_component:
            assert_never(unexpected_component)

    try:
        category, subtype = _PROTO_BY_CLASS[component_class]
    except KeyError as exc:
        raise TypeError(
            f"unsupported electrical component class: {component_class.__name__}"
        ) from exc

    return (category, unrecognized_subtype if subtype is None else subtype)

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_connection_from_proto

electrical_component_connection_from_proto(
    message: ElectricalComponentConnection,
) -> ElectricalComponentConnectionTypes

Create an electrical component connection from a protobuf message.

A self-referencing connection (same source and destination component) is returned as a SelfReferencingElectricalComponentConnection, which surfaces that malformed state at the type level.

PARAMETER	DESCRIPTION
message	The protobuf message to convert. TYPE: ElectricalComponentConnection

RETURNS	DESCRIPTION
ElectricalComponentConnectionTypes	One of the concrete connection types.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_electrical_component_connection.py

def electrical_component_connection_from_proto(
    message: electrical_components_pb2.ElectricalComponentConnection,
) -> ElectricalComponentConnectionTypes:
    """Create an electrical component connection from a protobuf message.

    A self-referencing connection (same source and destination component) is
    returned as a `SelfReferencingElectricalComponentConnection`, which surfaces
    that malformed state at the type level.

    Args:
        message: The protobuf message to convert.

    Returns:
        One of the concrete connection types.
    """
    source_component_id = ElectricalComponentId(message.source_electrical_component_id)
    destination_component_id = ElectricalComponentId(
        message.destination_electrical_component_id
    )
    lifetime = _get_operational_lifetime_from_proto(message)

    if source_component_id == destination_component_id:
        return SelfReferencingElectricalComponentConnection(
            source_id=source_component_id,
            destination_id=destination_component_id,
            operational_lifetime=lifetime,
        )

    return ElectricalComponentConnection(
        source_id=source_component_id,
        destination_id=destination_component_id,
        operational_lifetime=lifetime,
    )

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_diagnostic_code_from_proto

electrical_component_diagnostic_code_from_proto(
    message: ValueType,
) -> ElectricalComponentDiagnosticCode | int

Convert a protobuf ElectricalComponentDiagnosticCode value to an enum member.

PARAMETER	DESCRIPTION
message	The protobuf message to convert. TYPE: ValueType

RETURNS	DESCRIPTION
ElectricalComponentDiagnosticCode | int	The corresponding ElectricalComponentDiagnosticCode enum member, or the raw int if the protobuf value is not recognized.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_diagnostic_code.py

def electrical_component_diagnostic_code_from_proto(
    message: electrical_components_pb2.ElectricalComponentDiagnosticCode.ValueType,
) -> ElectricalComponentDiagnosticCode | int:
    """Convert a protobuf `ElectricalComponentDiagnosticCode` value to an enum member.

    Args:
        message: The protobuf message to convert.

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

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_diagnostic_code_to_proto

electrical_component_diagnostic_code_to_proto(
    diagnostic_code: ElectricalComponentDiagnosticCode,
) -> ValueType

Convert an ElectricalComponentDiagnosticCode enum member to a protobuf value.

PARAMETER	DESCRIPTION
diagnostic_code	The ElectricalComponentDiagnosticCode enum member to convert. TYPE: ElectricalComponentDiagnosticCode

RETURNS	DESCRIPTION
ValueType	The corresponding protobuf ElectricalComponentDiagnosticCode value.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_diagnostic_code.py

def electrical_component_diagnostic_code_to_proto(
    diagnostic_code: ElectricalComponentDiagnosticCode,
) -> electrical_components_pb2.ElectricalComponentDiagnosticCode.ValueType:
    """Convert an `ElectricalComponentDiagnosticCode` enum member to a protobuf value.

    Args:
        diagnostic_code: The
            [`ElectricalComponentDiagnosticCode`][....ElectricalComponentDiagnosticCode]
            enum member to convert.

    Returns:
        The corresponding protobuf `ElectricalComponentDiagnosticCode` value.
    """
    return electrical_components_pb2.ElectricalComponentDiagnosticCode.ValueType(
        diagnostic_code.value
    )

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_from_proto

electrical_component_from_proto(
    message: ElectricalComponent,
) -> ElectricalComponentTypes

Convert a protobuf message to an electrical component instance.

Malformed or forward-incompatible input is surfaced through the returned type rather than a side channel: an unspecified category yields an UnspecifiedElectricalComponent, an unrecognized one an UnrecognizedElectricalComponent, a category that disagrees with its carried info a MismatchedCategoryElectricalComponent, and an unspecified or unrecognized battery, EV charger or inverter type the matching Unrecognized* class (which preserves the raw wire type).

PARAMETER	DESCRIPTION
message	The protobuf message. TYPE: ElectricalComponent

RETURNS	DESCRIPTION
ElectricalComponentTypes	The resulting electrical component instance.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_electrical_component.py

def electrical_component_from_proto(
    message: electrical_components_pb2.ElectricalComponent,
) -> ElectricalComponentTypes:
    """Convert a protobuf message to an electrical component instance.

    Malformed or forward-incompatible input is surfaced through the returned
    type rather than a side channel: an unspecified category yields an
    `UnspecifiedElectricalComponent`, an unrecognized one an
    `UnrecognizedElectricalComponent`, a category that disagrees with its
    carried info a `MismatchedCategoryElectricalComponent`, and an unspecified
    or unrecognized battery, EV charger or inverter type the matching
    `Unrecognized*` class (which preserves the raw wire `type`).

    Args:
        message: The protobuf message.

    Returns:
        The resulting electrical component instance.
    """
    with warnings.catch_warnings():
        warnings.filterwarnings("ignore", category=DeprecationWarning)
        base_data = _electrical_component_base_from_proto(message)

        if base_data.category_mismatched:
            return MismatchedCategoryElectricalComponent(
                id=base_data.component_id,
                microgrid_id=base_data.microgrid_id,
                name=base_data.name,
                model=base_data.model,
                category=message.category,
                category_name=_category_name(message.category),
                operational_lifetime=base_data.lifetime,
                _provides_telemetry=base_data.provides_telemetry,
                _accepts_control=base_data.accepts_control,
                _allow_construction=True,
                category_specific_info=base_data.category_specific_info,
                metric_config_bounds=base_data.metric_config_bounds,
            )
        match base_data.category:
            case int():
                return UnrecognizedElectricalComponent(
                    id=base_data.component_id,
                    microgrid_id=base_data.microgrid_id,
                    name=base_data.name,
                    model=base_data.model,
                    category=message.category,
                    operational_lifetime=base_data.lifetime,
                    _provides_telemetry=base_data.provides_telemetry,
                    _accepts_control=base_data.accepts_control,
                    _allow_construction=True,
                    category_specific_info=base_data.category_specific_info,
                    metric_config_bounds=base_data.metric_config_bounds,
                )
            case (
                ElectricalComponentCategory.UNSPECIFIED
                | ElectricalComponentCategory.CHP
                | ElectricalComponentCategory.CONVERTER
                | ElectricalComponentCategory.CRYPTO_MINER
                | ElectricalComponentCategory.ELECTROLYZER
                | ElectricalComponentCategory.HVAC
                | ElectricalComponentCategory.METER
                | ElectricalComponentCategory.PRECHARGER
                | ElectricalComponentCategory.BREAKER
                | ElectricalComponentCategory.STEAM_BOILER
                | ElectricalComponentCategory.WIND_TURBINE
                | ElectricalComponentCategory.PLC
                | ElectricalComponentCategory.STATIC_TRANSFER_SWITCH
                | ElectricalComponentCategory.UNINTERRUPTIBLE_POWER_SUPPLY
                | ElectricalComponentCategory.CAPACITOR_BANK
            ):
                return _TRIVIAL_TYPELESS_CLASS_BY_PROTO_CATEGORY[
                    base_data.category.value
                ](
                    id=base_data.component_id,
                    microgrid_id=base_data.microgrid_id,
                    name=base_data.name,
                    model=base_data.model,
                    operational_lifetime=base_data.lifetime,
                    _provides_telemetry=base_data.provides_telemetry,
                    _accepts_control=base_data.accepts_control,
                    _allow_construction=True,
                    metric_config_bounds=base_data.metric_config_bounds,
                )
            case ElectricalComponentCategory.BATTERY:
                battery_info = _leftover_info(base_data.category_specific_info, "type")
                raw_battery_type = message.category_specific_info.battery.type
                battery_class = _BATTERY_CLASS_BY_PROTO_TYPE.get(raw_battery_type)
                if battery_class is None:
                    return UnrecognizedBattery(
                        id=base_data.component_id,
                        microgrid_id=base_data.microgrid_id,
                        name=base_data.name,
                        model=base_data.model,
                        operational_lifetime=base_data.lifetime,
                        _provides_telemetry=base_data.provides_telemetry,
                        _accepts_control=base_data.accepts_control,
                        _allow_construction=True,
                        category_specific_info=battery_info,
                        metric_config_bounds=base_data.metric_config_bounds,
                        type=raw_battery_type,
                    )
                return battery_class(
                    id=base_data.component_id,
                    microgrid_id=base_data.microgrid_id,
                    name=base_data.name,
                    model=base_data.model,
                    operational_lifetime=base_data.lifetime,
                    _provides_telemetry=base_data.provides_telemetry,
                    _accepts_control=base_data.accepts_control,
                    _allow_construction=True,
                    category_specific_info=battery_info,
                    metric_config_bounds=base_data.metric_config_bounds,
                )
            case ElectricalComponentCategory.EV_CHARGER:
                ev_charger_info = _leftover_info(
                    base_data.category_specific_info, "type"
                )
                raw_ev_charger_type = message.category_specific_info.ev_charger.type
                ev_charger_class = _EV_CHARGER_CLASS_BY_PROTO_TYPE.get(
                    raw_ev_charger_type
                )
                if ev_charger_class is None:
                    return UnrecognizedEvCharger(
                        id=base_data.component_id,
                        microgrid_id=base_data.microgrid_id,
                        name=base_data.name,
                        model=base_data.model,
                        operational_lifetime=base_data.lifetime,
                        _provides_telemetry=base_data.provides_telemetry,
                        _accepts_control=base_data.accepts_control,
                        _allow_construction=True,
                        category_specific_info=ev_charger_info,
                        metric_config_bounds=base_data.metric_config_bounds,
                        type=raw_ev_charger_type,
                    )
                return ev_charger_class(
                    id=base_data.component_id,
                    microgrid_id=base_data.microgrid_id,
                    name=base_data.name,
                    model=base_data.model,
                    operational_lifetime=base_data.lifetime,
                    _provides_telemetry=base_data.provides_telemetry,
                    _accepts_control=base_data.accepts_control,
                    _allow_construction=True,
                    category_specific_info=ev_charger_info,
                    metric_config_bounds=base_data.metric_config_bounds,
                )
            case ElectricalComponentCategory.GRID_CONNECTION_POINT:
                grid_info = _leftover_info(
                    base_data.category_specific_info, "rated_fuse_current"
                )
                rated_fuse_current = (
                    message.category_specific_info.grid_connection_point.rated_fuse_current
                )
                # No need to check for negatives because the protobuf type is uint32.
                return GridConnectionPoint(
                    id=base_data.component_id,
                    microgrid_id=base_data.microgrid_id,
                    name=base_data.name,
                    model=base_data.model,
                    operational_lifetime=base_data.lifetime,
                    _provides_telemetry=base_data.provides_telemetry,
                    _accepts_control=base_data.accepts_control,
                    _allow_construction=True,
                    category_specific_info=grid_info,
                    metric_config_bounds=base_data.metric_config_bounds,
                    rated_fuse_current=rated_fuse_current,
                )
            case ElectricalComponentCategory.INVERTER:
                inverter_info = _leftover_info(base_data.category_specific_info, "type")
                raw_inverter_type = message.category_specific_info.inverter.type
                inverter_class = _INVERTER_CLASS_BY_PROTO_TYPE.get(raw_inverter_type)
                if inverter_class is None:
                    return UnrecognizedInverter(
                        id=base_data.component_id,
                        microgrid_id=base_data.microgrid_id,
                        name=base_data.name,
                        model=base_data.model,
                        operational_lifetime=base_data.lifetime,
                        _provides_telemetry=base_data.provides_telemetry,
                        _accepts_control=base_data.accepts_control,
                        _allow_construction=True,
                        category_specific_info=inverter_info,
                        metric_config_bounds=base_data.metric_config_bounds,
                        type=raw_inverter_type,
                    )
                return inverter_class(
                    id=base_data.component_id,
                    microgrid_id=base_data.microgrid_id,
                    name=base_data.name,
                    model=base_data.model,
                    operational_lifetime=base_data.lifetime,
                    _provides_telemetry=base_data.provides_telemetry,
                    _accepts_control=base_data.accepts_control,
                    _allow_construction=True,
                    category_specific_info=inverter_info,
                    metric_config_bounds=base_data.metric_config_bounds,
                )
            case ElectricalComponentCategory.POWER_TRANSFORMER:
                power_transformer_info = _leftover_info(
                    base_data.category_specific_info, "primary", "secondary"
                )
                return PowerTransformer(
                    id=base_data.component_id,
                    microgrid_id=base_data.microgrid_id,
                    name=base_data.name,
                    model=base_data.model,
                    operational_lifetime=base_data.lifetime,
                    _provides_telemetry=base_data.provides_telemetry,
                    _accepts_control=base_data.accepts_control,
                    _allow_construction=True,
                    category_specific_info=power_transformer_info,
                    metric_config_bounds=base_data.metric_config_bounds,
                    primary_voltage=message.category_specific_info.power_transformer.primary,
                    secondary_voltage=message.category_specific_info.power_transformer.secondary,
                )
            case unexpected_category:
                assert_never(unexpected_category)

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_state_code_from_proto

electrical_component_state_code_from_proto(
    message: ValueType,
) -> ElectricalComponentStateCode | int

Convert a protobuf ElectricalComponentStateCode value to an enum member.

PARAMETER	DESCRIPTION
message	The protobuf message to convert. TYPE: ValueType

RETURNS	DESCRIPTION
ElectricalComponentStateCode | int	The corresponding ElectricalComponentStateCode enum member, or the raw int if the protobuf value is not recognized.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_state_code.py

def electrical_component_state_code_from_proto(
    message: electrical_components_pb2.ElectricalComponentStateCode.ValueType,
) -> ElectricalComponentStateCode | int:
    """Convert a protobuf `ElectricalComponentStateCode` value to an enum member.

    Args:
        message: The protobuf message to convert.

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

frequenz.client.common.microgrid.electrical_components.proto.v1alpha8.electrical_component_state_code_to_proto

electrical_component_state_code_to_proto(
    state_code: ElectricalComponentStateCode,
) -> ValueType

Convert an ElectricalComponentStateCode enum member to a protobuf value.

PARAMETER	DESCRIPTION
state_code	The ElectricalComponentStateCode enum member to convert. TYPE: ElectricalComponentStateCode

RETURNS	DESCRIPTION
ValueType	The corresponding protobuf ElectricalComponentStateCode value.

Source code in src/frequenz/client/common/microgrid/electrical_components/proto/v1alpha8/_state_code.py

def electrical_component_state_code_to_proto(
    state_code: ElectricalComponentStateCode,
) -> electrical_components_pb2.ElectricalComponentStateCode.ValueType:
    """Convert an `ElectricalComponentStateCode` enum member to a protobuf value.

    Args:
        state_code: The
            [`ElectricalComponentStateCode`][....ElectricalComponentStateCode] enum
            member to convert.

    Returns:
        The corresponding protobuf `ElectricalComponentStateCode` value.
    """
    return electrical_components_pb2.ElectricalComponentStateCode.ValueType(
        state_code.value
    )