Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[RFC] Explicit entity object discovery, lifetimes, and registration #365

Open
wants to merge 33 commits into
base: dev
Choose a base branch
from

Conversation

puddly
Copy link
Contributor

@puddly puddly commented Jan 28, 2025

PlatformEntity objects, among others, rely on implicit "registration" inside of __init__ by mutating a global dictionary that ZHA flushes when creating new devices. This is a bit difficult to work with, in my opinion, and is somewhat preventing zigpy/zigpy#1535 from being implemented.

This PR:

  1. Construct entity objects early.
  2. Implement an on_add interface to mirror on_remove and allow for entity object creation to not rely on any sort of global state.
  3. Allow entities to explicitly indicate if they are not supported by the current device via Entity.is_supported (this is mostly a copy/paste of the create_platform_entity logic).
  4. Funnel all device entity discovery explicitly via gateway.py.

@puddly
Copy link
Contributor Author

puddly commented Jan 28, 2025

This PR is "done" architecturally, for the most part.

Main changes:

  • All entities must compute capability bitmasks and other feature flags in Entity.recompute_capabilities().
    This is required because we effectively perform multiple passes when setting up entities: an initial pass to discover entities and claim cluster handlers, a second pass to initialize the cluster handlers and possibly populate the attribute cache, and a third pass to actually validate whether or not the discovered entities are applicable to the device. In the future, it would be nice to consolidate this functionality entirely into the Entity subclass.
  • Entities indicate device applicability via Entity._is_supported().
    For the same reason as above, since entity objects are created at runtime, we need a way to signal applicability to a device independent of creation. I've also added a new _attr_is_always_supported to allow entities that do not abide by these rules to be easily flagged (quirks v2, group, RSSI/LQI, and device counters).
  • All entity objects' listeners, callbacks, and tasks must be registered in Entity.on_add() and deregistered with Entity.on_remove().
    For simplicity, there is also a Entity._on_remove_callbacks list that will be iterated over by the default Entity.on_remove() callback.

That about covers everything. This is a very, very rough first pass PR and is in not in a state for review beyond architecture changes.

@puddly puddly force-pushed the puddly/explicit-entity-registry branch from 0f4faef to fb3dfd6 Compare January 30, 2025 21:51
Copy link

codecov bot commented Jan 31, 2025

Codecov Report

Attention: Patch coverage is 99.35484% with 2 lines in your changes missing coverage. Please review.

Project coverage is 96.40%. Comparing base (c23285f) to head (c0becd5).

Files with missing lines Patch % Lines
zha/application/gateway.py 90.00% 1 Missing ⚠️
zha/application/platforms/light/__init__.py 97.05% 1 Missing ⚠️
Additional details and impacted files
@@            Coverage Diff             @@
##              dev     #365      +/-   ##
==========================================
- Coverage   96.58%   96.40%   -0.19%     
==========================================
  Files          61       61              
  Lines        9526     9594      +68     
==========================================
+ Hits         9201     9249      +48     
- Misses        325      345      +20     

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

@puddly puddly marked this pull request as ready for review February 3, 2025 19:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants