Add postfix number to ZHA entities

[Markus98]

This is a PR created based on the discussion in home-assistant/core#151434

Proposed change

This PR implements a feature from the ZHA backlog. It adds an optional postfix attribute to ZHA entities. It is used to differentiate between entities that have the same type and name on the same device. The attribute is needed for proper numbered naming in the UI.

Additional information

• Scroll all the way down for the relevant code files diff. Code files changed:
  • zha/application/platforms/__init__.py
  • zha/zigbee/device.py
• This PR is a part of closing issue: [ZHA] Properly name repeated entities backlog#7
• I will update the hass-core PR with the required changes to use the postfix attribute Add counter to ZHA entity names when a device has multiple of the same type home-assistant/core#151434
• I did not write explicit unit tests for this, but regressions should be covered in testing since I added the postfix attribute to BaseEntityInfo.

Checklist

• The code change is tested and works locally.
• Local tests pass. Your PR cannot be merged unless tests pass
• There is no commented out code in this PR.
• I have followed the development checklist
• I have followed the perfect PR recommendations
• The code has been formatted using Ruff
• Tests have been added to verify that the new code works.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 96.91%. Comparing base (ebc3cbf) to head (bfc417b).

Additional details and impacted files

@@           Coverage Diff           @@
##              dev     #525   +/-   ##
=======================================
  Coverage   96.91%   96.91%           
=======================================
  Files          63       63           
  Lines       10498    10515   +17     
=======================================
+ Hits        10174    10191   +17     
  Misses        324      324           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[TheJulianJES]

Awesome, this looks pretty good!
I'll take a closer final look in the next few days, maybe adjust one of the comments, but I think this and the HA implementation are good otherwise.

One note for possible future PRs: it's a bit nicer to commit the regenerated diagnostics separately, since the GitHub diff viewer gets a bit laggy with all the changed files. We squash all PRs when merging them anyway, so it'll still be one commit in the repo.

[TheJulianJES]

The Matter integration in Home Assistant has a similar feature. However, it uses the endpoint ID for the postfix. For reference, see: https://github.com/home-assistant/core/blob/180f898bfa8b4bc3a1a5a97f64866c64fe1f551e/homeassistant/components/matter/entity.py#L111

I would not do this in the Zigbee integration, as quite a few Zigbee devices start with endpoint 11 or some other number. This would be confusing if there's "Voltage (11)" and "Voltage (12)", for example.
Counting upwards from 1 (if there are duplicate entities) is a better approach, at least for Zigbee.
Directly creating entities (per device, not per endpoint, e.g. quirks v2 entities) also play a role here.

Minor side note:
The Matter implementation also sets its postfix before all entities "are discovered", just by looking at duplicate clusters. The reason for this might be that this was a good option which doesn't require checking other entities, or endpoint IDs are generally used more sensible with Matter.

For us, I think the approach in this PR is already the best.

[epenet]

Have translation_placeholders been considered?

Similar to what I added to Tuya:

• Use translation_placeholders in tuya cover descriptions home-assistant/core#149248
• Use translation_placeholders in tuya light descriptions home-assistant/core#149249
• Use translation_placeholders in tuya number descriptions home-assistant/core#149250
• Use translation_placeholders in tuya select descriptions home-assistant/core#149251
• Use translation_placeholders in tuya switch descriptions home-assistant/core#149664

[TheJulianJES]

Thanks for linking this!

I'm not sure that approach would work for us here, since we can potentially have almost every entity twice, needing a postfix. Or just once, not needing one.

In that case, we'd need two translation key/value pairs per current one, from what I can see, as we'd have a trailing space otherwise.

We could make use of it for some quirks v2 defined entities though, where e.g. left/right would be used instead. For these, the entities are defined/fixed per device, so we always know exactly which ones exist.
Translation placeholders could be useful here, though the postfix approach from this PR can be, too.

[Markus98]

Thank you for taking a look and I'm glad that it seems good!

One note for possible future PRs: it's a bit nicer to commit the regenerated diagnostics separately, since the GitHub diff viewer gets a bit laggy with all the changed files. We squash all PRs when merging them anyway, so it'll still be one commit in the repo.

Good point, thanks for the note. I'm used to working with atomic commits that do not break tests but I don't need to do that here if we squash anyways.

I would not do this in the Zigbee integration, as quite a few Zigbee devices start with endpoint 11 or some other number. This would be confusing if there's "Voltage (11)" and "Voltage (12)", for example.
Counting upwards from 1 (if there are duplicate entities) is a better approach, at least for Zigbee.

I made the same observation and agree.

Have translation_placeholders been considered?

I also considered implementing it this way, but decided against it for the same reasons @TheJulianJES outlined.

[epenet]

I don't know if you have thought of this:

• 3 "production" (kWh) sensors (total / A / B)
• 3 "power" (W) sensors (total / A / B)
• only 2 "current" (A) sensors (A / B)

With the automatic suffix, you end up with misalignment of the suffix (current B would end up with same suffix 2 as power A)

Is it really that bad to use the cluster ID?
If we don't want to start number from say 11, we would use a hex string of the cluster ID so that we at least keep the "grouping" of the cluster entities.