Targets can exclude entities
Targeting an area, floor, or label is handy, until you want all of it except one or two things. Until now, the only way out was listing every entity separately, which loses the point of targeting the area in the first place.
So a target can now have an exclude block. It uses the same keys as the target itself, and Home Assistant removes whatever it matches from the resolved target:
action: light.turn_on
target:
floor_id: ground_floor
exclude:
area_id: kitchen
label_id: night_lightExclusions are resolved like the target, so they stay up to date. A light added to the kitchen later is left out as well. An exclusion applies to the whole target, including entities listed in the target directly. An exclude block on its own is not a valid target, and it can't be nested or use all or none.
If Home Assistant resolves the target for you, your integration supports exclusions already:
- Entity actions registered with
async_register_platform_entity_serviceorasync_register_entity_service, includingentity_id: all - Triggers and conditions built on the entity helpers, like
make_entity_target_state_trigger - Code that uses
service.async_extract_entities,service.async_extract_entity_ids, ortarget.async_extract_referenced_entity_ids - Triggers that follow a target with
target.async_track_target_selector_state_change_eventorTargetEntityChangeTracker
cv.TARGET_FIELDS, cv.ENTITY_SERVICE_FIELDS, and cv.TARGET_SERVICE_FIELDS now accept exclude, and so does every schema built from them, like cv.make_entity_service_schema. If your code reads entity_id, device_id, or area_id from the target and resolves them on its own, it now accepts an exclude block and silently ignores it. That is worse than an error: the action or trigger then acts on exactly the entities the user asked to leave out.
Resolve the target with the target helpers instead. They apply the exclude block for you:
from homeassistant.helpers import target as target_helpers
selection = target_helpers.TargetSelection(call.data)
selected = target_helpers.async_extract_referenced_entity_ids(
hass, selection
)
entity_ids = selected.referenced | selected.indirectly_referencedIf your integration can't support exclusions, build its schema from cv.TARGET_ID_FIELDS. It has the target keys without exclude, so an exclude block fails validation instead of being ignored.
TargetSelection.exclude: the exclude block as aTargetSelection, orNone.TargetSelection.has_any_targetdoesn't look at it, so a target with only an exclude block targets nothing.target.async_extract_excluded_entity_ids(hass, target_selection): the entity IDs the exclude block matches.cv.TARGET_ID_KEYS: the keys that select what a target refers to. Use them instead of the keys ofcv.ENTITY_SERVICE_FIELDSwhen you require at least one target, likeprobatio.AtLeastOne(*cv.TARGET_ID_KEYS). That way a target with only an exclude block doesn't pass.cv.TARGET_ID_FIELDS: the target fields withoutexclude.
The details are in entity actions and triggers and conditions. The background is in core pull request #187290.