feat: ElectricalComponent

[eduardiazf]

Summary

This PR introduces comprehensive support for electrical components in the Frequenz Assets API client, including new data types, enums, CLI commands, and enhanced serialization capabilities.

Changes Made

🆕 New Features

• Electrical Component Types: Added ElectricalComponent class with support for batteries, EV chargers, inverters, grid connection points, and power transformers
• Component Categories: Implemented category-specific information classes (Battery, EvCharger, Inverter, GridConnectionPoint, PowerTransformer)
• Metric System: Added Metric enum supporting various electrical measurements (DC voltage/current/power, AC frequency/voltage, phase-to-phase voltages)
• Operational Lifetime: Added Lifetime class for tracking component operational periods
• Configuration Bounds: Implemented MetricConfigBounds and Bound classes for component metric limits

🔧 Enhanced Functionality

• API Client: Added get_electrical_components() method to retrieve electrical components from a microgrid
• CLI Commands: New electrical-components command for querying component data
• Custom JSON Encoders: Implemented specialized serializers for both Microgrid and ElectricalComponent objects
• Type Consolidation: Consolidated battery, EV charger, and inverter enums into unified imports

📚 Documentation & CLI

• Enhanced CLI command documentation for retrieving electrical components
• Added comprehensive docstrings for all new classes and methods
• Improved error handling and user experience in CLI utilities

🔄 Dependencies

• Updated frequenz-client-common from >=0.3.2 to >=0.3.6

Examples

CLI Usage

Query electrical components for a specific microgrid:

assets-cli electrical-components 1

Sample Output

[
  {
    "id": 414,
    "microgrid_id": 226,
    "name": "battery1",
    "category": 5,
    "manufacturer": "Commeo",
    "model_name": "Commeo HV",
    "operational_lifetime": {
      "start": null,
      "end": null
    },
    "rated_bounds": {
      "102": {
        "lower": 9.0,
        "upper": 45.0
      },
      "101": {
        "lower": 5.0,
        "upper": 95.0
      }
    },
    "type": 1
  },
  {
    "id": 415,
    "microgrid_id": 226,
    "name": "Grid1",
    "category": 1,
    "manufacturer": null,
    "model_name": null,
    "operational_lifetime": {
      "start": null,
      "end": null
    },
    "rated_bounds": {},
    "rated_fuse_current": 10
  },
  {
    "id": 416,
    "microgrid_id": 226,
    "name": "Relay1",
    "category": 7,
    "manufacturer": null,
    "model_name": null,
    "operational_lifetime": {
      "start": null,
      "end": null
    },
    "rated_bounds": {}
  }
]

Testing

• All new functionality includes comprehensive type hints and documentation
• Maintains backward compatibility with existing microgrid functionality
• Follows established patterns for protobuf message handling and serialization

Breaking Changes

None - this is a purely additive feature that extends existing functionality.

[llucax]

Besides the comments, it LGTM in general although I didn't check in depth if there are more diversions compared to my base implementation of the dataclass wrappers.

[llucax]

OK, this looks good in general to me. I think most comments are FYI about ideas I have for the final version in client-common, but there are a few comments about a couple of small issues.

About the commit split, I think by now the split makes this PR (and the git history) harder to read, as not only there a lot of commits, but also commits are not very isolated, they look more like checkpoints while editing files, which makes it very hard to review and very easy to get lost among the unrelated changes.

I would strongly suggest to improve the commit splitting before merging. I don't think we need a lot of commits here, as 95% of the changes here is just creating new files, and all of that is probably fine to include in just one commit.

So splitting in 2 commits, one adding all the new files, and then a second commit adding the new client method, for me would be a huge improvement already.

Ideally I would split a bit more, also not a lot, but something like:

• First commit adding the new files verbatim as you copy them from the microgrid API client, using the old common version.
• Copy all the files in the current state overwriting those original files. With this we get one commit where we can clearly see all the changes that were necessary to go from common API pre-v0.8 to v0.8, which will be very useful when migrating the microgrid API client too.
• Unrelated fixes, like re-exporting the PermissionDenied exception (ideally one per unrelated change, but I'm also fine to do them all in one commit if it makes things easier).
• Add the new client method.
• Add the tests for the new client method.
• Add the get_microgrid_details method test, or even leave those for a separate PR, but not sure, maybe you need to include them here if you are removing old tests for that method). If splitting is complicated, also one commit with all test-related changes would be fine too.

[llucax]

I'm thinking about removing these enums in the final version for client-common. With the current approach we can easily specify battery/inverter/etc. types and different component categories using Python classes, so providing the enums too doesn't add any value and introduces more ways to do the same thing, which can be confusing for users.

We don't need to change anything else, but just FYI and to know your opinion, in case I'm missing something.

[llucax]

If/when we remove the enum, this field will be gone here, and only added to UnrecognizedBattery as just type: int.

Again, just FYI.

[llucax]

This encoder ended up being pretty generally useful! I think we should definitely move this encoder to frequenz-core/frequenz-client-common in the future.

[llucax]

• Add an improved JSON encoder that supports more types frequenz-core-python#99

[llucax]

nitpick:

Suggested change

	if isinstance(o, (list, tuple, set, frozenset)):
	elif isinstance(o, (list, tuple, set, frozenset)):

[llucax]

Oh, and BTW and just for the records, I didn't review much of the _from_proto() implementations or tests, I assumed they are more or less the same as the original files.

[llucax]

Awesome 🎉

Thanks for the patience! I will create a follow-up issues with pending comments where appropriate.

The merge-base changed after approval.