Add counter to ZHA entity names when a device has multiple of the same type

[Markus98]

Proposed change

This PR implements a feature from the ZHA backlog. It improves the readability of entities on ZHA devices which have multiple entities of the same type by adding a counter to the names of repeated entities.

Type of change

• Dependency upgrade
• Bugfix (non-breaking change which fixes an issue)
• New integration (thank you!)
• New feature (which adds functionality to an existing integration)
• Deprecation (breaking change to happen in the future)
• Breaking change (fix/feature causing existing functionality to break)
• Code quality improvements to existing code or addition of tests

Additional information

• This PR closes issue: [ZHA] Properly name repeated entities zigpy/backlog#7
• Entity names are numbered based on their order in the platform_entities attribute. This attribute, located in the zha.zigbee.device.Device class, matches the order in which entities appear in the UI.
• There is an additional check before adding the counter to the entity name. It checks that the entity being named can be found inside the list of entities of the device. This check should never fail, but in case it should, an error would be avoided and the naming behavior would remain like it was before this change.

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 (ruff format homeassistant tests)
• Tests have been added to verify that the new code works.

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated for www.home-assistant.io

If the code communicates with devices, web services, or third-party tools:

• The manifest file has all fields filled out correctly.
  Updated and included derived files by running: python3 -m script.hassfest.
• New or updated dependencies have been added to requirements_all.txt.
  Updated by running python3 -m script.gen_requirements_all.
• For the updated dependencies - a link to the changelog, or at minimum a diff between library versions is added to the PR description.

To help with the load of incoming pull requests:

• I have reviewed two other open pull requests in this repository.

[home-assistant]

Hey there @dmulcahey, @Adminiuga, @puddly, @TheJulianJES, mind taking a look at this pull request as it has been labeled with an integration (zha) you are listed as a code owner for? Thanks!

Code owner commands

Code owners of zha can trigger bot actions by commenting:

• @home-assistant close Closes the pull request.
• @home-assistant rename Awesome new title Renames the pull request.
• @home-assistant reopen Reopen the pull request.
• @home-assistant unassign zha Removes the current integration label and assignees on the pull request, add the integration domain after the command.
• @home-assistant add-label needs-more-information Add a label (needs-more-information, problem in dependency, problem in custom component) to the pull request.
• @home-assistant remove-label needs-more-information Remove a label (needs-more-information, problem in dependency, problem in custom component) on the pull request.

[puddly]

Let's move this feature to https://github.com/zigpy/zha instead

[TheJulianJES]

Just to clarify, due to the usage of translation keys, we'll still require changes to Home Assistant Core itself.

I'm in favor of adding something like a "postfix" attribute to ZHA entities, which we can then access from HA Core here. But ZHA will then decide if and what postfix number should be used. We can likely set that just once after entity discovery is done.

[Markus98]

Hey, thanks for the feedback. I'll work on implementing the logic on the zha library side. I'll also update this PR with the changes required for it to work with the new version of zha once I have that PR in.

I'll try implementing it like @TheJulianJES's suggested.

[Markus98]

I've now created a PR in the zha repository zigpy/zha#525 which implements the same feature on the zha library side. It implements the postfix property as suggested by @TheJulianJES.

I've also pushed the required changes to this PR. I have assumed that my changes would be in zha==0.0.71, but that can be changed if the version number turns out to be wrong.

[TheJulianJES]

Nice work! Two things regarding the HA part of this implementation:

1. Let's remove the dependency bump from this PR.
   Since the dependency bump doesn't need this feature to be included, we should do the bump separately. Then merge this afterwards.

2. Ideally, we would have at least one test or snapshot (for entities) checking the postfix implementation. We have that on the ZHA side, but not on the HA side.

   We might be able to just add that to existing sensor tests in test_sensor or possibly even generate a snapshot (similar to how it's done in test_diagnostics.py) for a mocked device with two identical clusters (and thus identical sensors) on different endpoints, and for one with no identical clusters, so no postfix.

   If you wanna have a go at that, feel free to do so. Otherwise, I should be able to do this soon.

[Markus98]

Thanks for the feedback!

I might be a bit low on free time in the coming days but I will leave a comment here if I find the time to do it. If I don't comment, feel free to assume I haven't started work and go ahead and modify the PR. I agree on the feedback given and the suggested changes / additions seem good to me.

[Markus98]

@TheJulianJES I went ahead and implemented your feedback. I also had a go at creating a unit test that checks that the postfix is in the name of the entity. If there are more than two identical clusters, there should be one, and if there is only one cluster, there should be no postfix. I implemented it int he test_entity.py file rather than test_sensor.py, since it applies to all entities in general. Let me know if there is still something that needs to be adjusted.

[TheJulianJES]

Putting this in draft until the ZHA PR is merged. I'll come back to this before then though.

I'll also try to get to your ZHA PR as soon as possible and check if there are any real devices that would cause the issues epenet mentioned there, or if we can maybe internally count using the cluster id first, but just replace all digits to start from 1, potentially skipping one digit in the case epenet mentioned.

EDIT: Described that with an example in the ZHA PR: zigpy/zha#525 (comment)

This is definitely something we want included soon, so thanks for the time you spent on this already!