Deprecate `ElectricalComponentCategory` and `XxxType` enums#222

Merged

llucax merged 11 commits into

frequenz-floss:v0.x.xfrom

llucax:no-unspecified-phase-c

Jul 2, 2026

llucax commented Jun 25, 2026 •

edited

Loading

Contributor

This PR removes the electrical component category and type enums and leaves the ElectricalComponent class hierarchy as the canonical representation of electrical components and single source of truth for electrical component types.

It basically:

Deprecates the ElectricalComponentCategory and ElectricalComponentType wrapper enums.
Deprecates the BatteryType, EvChargerType and InverterType wrapper enums.
Deprecates the category of the ElectricalComponent class.
Deprecates the type for Battery, EvCharger and Inverter classes.
Adds electrical_component_class_from_proto() and electrical_component_class_to_proto() functions to convert between the ElectricalComponent class hierarchy and the protobuf enum representation of electrical component categiries and types so client implementers have an easy way to replace the deprecated wrapper enums with the new class hierarchy.

It also adds some missing electrical component classes so they are not wrapped as unrecognized electrical components.

Part of #223.

llucax requested a review from a team as a code owner

June 25, 2026 14:03

llucax requested review from ela-kotulska-frequenz and removed request for a team

June 25, 2026 14:03

llucax marked this pull request as draft

June 25, 2026 14:03

llucax commented Jun 25, 2026

Contributor Author

Converting to draft as it is based on #221.

github-actions Bot added part:docs part:tests part:tooling part:grid part:metrics part:microgrid labels

llucax self-assigned this

llucax added this to the v0.4.1 milestone

llucax added the status:blocked label

llucax mentioned this pull request

Remove unnecessary enums #220

Merged

llucax commented Jun 25, 2026

Contributor Author

The electrical_component_class_from/to_proto() are pretty convoluted. Opus choked a bit on it, and even when it did most of the structure, I needed to do the real implementation myself to get the type-hinting right (there is only one gap I could not solve).

But well, is a one time thing, adding more components should be easy even if the code is scary.

llucax force-pushed the no-unspecified-phase-c branch 5 times, most recently from 71ce484 to 5bac2c1 Compare

June 26, 2026 11:05

This was referenced Jun 26, 2026

Remove all UNSPECIFIED enum values and low-level enums #223

Open

Deprecate remaining UNSPECIFIED enum members #225

Merged

llucax changed the title ~~Remove ElectricalComponentCategory and XxxType enums~~ Deprecate ElectricalComponentCategory and XxxType enums

ela-kotulska-frequenz reviewed

View reviewed changes

ela-kotulska-frequenz left a comment •

edited

Loading

LGTM , however I am not familiar with this code at all.

llucax force-pushed the no-unspecified-phase-c branch 3 times, most recently from 0cde2f6 to f3c89a7 Compare

June 30, 2026 11:51

llucax added 2 commits

July 1, 2026 10:31


          Remove ElectricalComponentOperationalMode enum

92ad682

This enum and file should have been removed by frequenz-floss#220 but it was
forgotten.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Add missing electrical component classes

a2fc6db

Add these four concrete leaf electrical components: `Plc`,
`StaticTransferSwitch`, `UninterruptiblePowerSupply` and
`CapacitorBank`. Follow the same shape as the other simple leaves (e.g.
`Chp`, `Hvac`): each one only fixes its `category` default and adds no
extra fields. They are exported from the package and added to the
`ElectricalComponentTypes` union, so they become part of the public type
surface.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax added 6 commits

July 1, 2026 10:31


          Fix __all__ order

9eb0515

This got unordered when `SolarInverter` was renamed to `PvInverter`.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Support conversion for the new component classes

a63b712

The proto dispatcher now maps the PLC, static transfer switch,
uninterruptible power supply and capacitor bank categories to their
dedicated `Plc`, `StaticTransferSwitch`, `UninterruptiblePowerSupply`
and `CapacitorBank` classes.

Until now these four categories were added to the enum but were
converted to `UnrecognizedElectricalComponent` as the classes were never
added.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Improve UnrecognizedElectricalComponent docstring

1fc8912

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Add electrical component class to/from protobuf enum converters

0a85a71

These converters allow mapping the `ElectricalComponent` class hierarchy
to protobuf `(category, type)` enum tuples, to be able to send the
protobuf enum values to the protocol without the need to expose the
enums themselves, avoiding having two ways to express the same on the
high-level wrappers.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Use non-overlapping types in ElectricalComponentTypes

cab8348

The type alias was using `ProblematicElectricalComponentTypes` but that
also includes problematic batteries, EV chargers and inverters, which
are included by BatteryTypes, EvChargerTypes and InverterTypes too.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Deprecate category and type attributes

89bcb62

The next commit will deprecate the enums, so we need to deprecate the
attributes using them.

To do this we rename attributes to make them private and to represent
them with raw `int`s, and add a deprecated property to access them
returning the deprecated enum, so we can silence the internal
deprecation message when we do the conversion.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax force-pushed the no-unspecified-phase-c branch from f3c89a7 to 8f1320d Compare

July 1, 2026 09:50

llucax added 3 commits

July 1, 2026 11:55


          Deprecate the electrical component category and type enums

0789c9b

`ElectricalComponentCategory`, `BatteryType`, `InverterType` and
`EvChargerType` are all replaced by the electrical component class
hierarchy plus the typed `electrical_component_class_to_proto()` /
`electrical_component_class_from_proto()` converters added earlier in
this phase. Callers should use `isinstance` checks on concrete classes
(e.g. `LiIonBattery`, `PvInverter`, `AcEvCharger`) instead of comparing
to a category/type enum member.

Mark each enum and its members as deprecated:

* Each class switches from `enum.Enum` to `frequenz.core.enum.Enum`
  and gains `@typing_extensions.deprecated(...)` so calling
  `XxxType(value)` or `XxxType['NAME']` warns.
* Every member is wrapped in `core_enum.deprecated_member(value, msg)`
  so attribute and subscript lookups warn too. Iteration is left
  warning-free (a verified property of `frequenz.core.enum`) so the
  parity tests can list all member names without spurious noise.

Mark the matching `*_from_proto` / `*_to_proto` converter pairs as
deprecated too. Their bodies wrap the inner enum lookup or
`enum_from_proto()` call in `warnings.catch_warnings()` with a
`DeprecationWarning` filter so the converter itself only emits the
function-level warning the caller sees; the internal enum-member access
stays silent.

The parity test subclasses pin
`deprecated_members = frozenset(m.name for m in <Enum>)`, which makes
`EnumParityTest._maybe_ignore_deprecation` silence the parity checks
while `test_deprecated_members_warn` keeps asserting each member still
warns. A new `test_enum_deprecation.py` locks in the public contract:
member access warns, the deprecated converters warn, and
`electrical_component_class_to_proto()` (the replacement) stays
warning-clean.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Reuse new mappings for electrical_component_from_proto_with_issues()

c4136ac

The previous commit introduced some mappings that were useful not only
for the new class converters but are also useful for the existing
message converters. We reuse them and remove the old similar mapping
we had for the message converter.

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>


          Update release notes

559a364

Signed-off-by: Leandro Lucarella <luca-frequenz@llucax.com>

llucax force-pushed the no-unspecified-phase-c branch from 8f1320d to 559a364 Compare

July 1, 2026 09:55

llucax marked this pull request as ready for review

July 1, 2026 09:58

llucax enabled auto-merge

July 1, 2026 09:58

llucax commented Jul 1, 2026

Contributor Author

Ready for review.

llucax removed the status:blocked label

llucax requested review from Marenz, cwasicki, eduardiazf, shsms and tiyash-basu-frequenz

July 1, 2026 09:58

llucax commented Jul 1, 2026

Contributor Author

Maybe it is a good idea to look at the release notes changes first to have a better idea of where this is going.

Marenz approved these changes

View reviewed changes

Marenz left a comment

Contributor

Clean deprecation with thorough tests, proper warning hygiene, and a clear migration path. The class-hierarchy approach is a better fit for the domain than enum switches. The 11 @overload signatures are verbose but necessary for mypy — worth the type safety.

llucax added this pull request to the merge queue

Merged via the queue into frequenz-floss:v0.x.x with commit 9a5d248

13 checks passed

llucax deleted the no-unspecified-phase-c branch

July 2, 2026 13:22

llucax mentioned this pull request

Remove unreleased electrical component category/type wrappers #233

Merged

llucax linked an issue

that may be closed by this pull request

Remove all UNSPECIFIED enum values and low-level enums #223

Open

12 tasks

llucax added a commit to llucax/frequenz-client-common-python that referenced this pull request


          Remove unreleased electrical component category/type wrappers (freque…

436141f

…nz-floss#233)

The earlier deprecation PR frequenz-floss#222 deprecated `ElectricalComponentCategory`
and the `XxxType` enums and `.category` and `.type` attributes, but most
of those symbols were yet unreleased, so deprecating them makes no
sense.

This PR remove the unreleased deprecated symbols:

- `ElectricalComponent.category` and `(Battery|Inverter|EvCharger).type`
attributes, except for `Unrecognized*` classes and
`MismatchesCategoryElectricalComponent`, as they carry the raw protobuf
value that could be used for forward compatibility.
- `BatteryType`, `InverterType`, `EvChargerType` enums, and their
protobuf conversion functions.

`ElectricalComponentCategory` and its proto converters are kept as
deprecated because they were already released and still present in
v0.4.0.

Part of frequenz-floss#223.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Labels

part:docs part:grid part:metrics part:microgrid part:tests part:tooling