Skip to content

Add event_filter to @event_trigger; make filter-required events subscribable#853

Open
3735943886 wants to merge 1 commit into
custom-components:masterfrom
3735943886:event-trigger-event-filter
Open

Add event_filter to @event_trigger; make filter-required events subscribable#853
3735943886 wants to merge 1 commit into
custom-components:masterfrom
3735943886:event-trigger-event-filter

Conversation

@3735943886

Copy link
Copy Markdown
Contributor

Adds an optional event_filter keyword to @event_trigger, compiled and evaluated natively/synchronously at the HA event bus so events are filtered before reaching the trigger callback.

Makes events that mandate a bus filter (e.g. EVENT_STATE_REPORTED) subscribable. With no event_filter, the bus filter is omitted so HA rejects such events.

Docs also updated.

…ribable

Add an optional `event_filter` keyword to @event_trigger that is compiled
and evaluated natively/synchronously at the HA event bus, so events are
filtered before reaching the (async) trigger callback.

This also makes events that mandate a bus filter (e.g. EVENT_STATE_REPORTED)
subscribable. When no event_filter is given the bus filter is omitted, so HA
rejects such filter-mandatory events instead of firehosing every event of
that type; pass event_filter="True" to opt into receiving them all.

A failing subscription is now caught and logged, leaving sibling triggers on
the same function intact instead of tearing the whole function down.
@dmamelin

dmamelin commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

I do not fully understand why event_filter is needed for event handling, but if you look at homeassistant/core.py, the error happens only in one case: when subscribing to EVENT_STATE_REPORTED.

        if event_type == EVENT_STATE_REPORTED:
            if not event_filter:
                raise HomeAssistantError(
                    f"Event filter is required for event {event_type}"
                )

This looks like a very rare case to add such functionality to pyscript. If I am missing something, please let me know.

For advanced use cases, hass.bus.async_listen can be used directly.

@3735943886

3735943886 commented Jun 9, 2026

Copy link
Copy Markdown
Contributor Author

Thank you for looking closely into PR and sharing this insight.

You are entirely right. Currently, EVENT_STATE_REPORTED is indeed the only event type that enforces an event_filter. Given that this is a specific case, it might seem like a rare edge case to support in pyscript—especially since advanced users can always fall back on hass.bus.async_listen directly.

To provide a bit of context, the reasoning behind handling this in pyscript comes down to a couple of practical considerations:

  • Preventing Broken Event Triggers: If a user happens to trigger EVENT_STATE_REPORTED, Home Assistant will raise a HomeAssistantError. Without a guard or proper filter handling in place, this unhandled exception can cause the pyscript event trigger to fail permanently, meaning the @event_trigger decorator stops working entirely and will never trigger again unless the affected script is restarted.
  • Future-Proofing for Core Changes: While EVENT_STATE_REPORTED is the only event requiring this today, there is a possibility that the Home Assistant core team might extend this filtering mechanism to other high-frequency events in the future.

Your analysis is spot on regarding the current state of the codebase. If you feel that implementing a full event_filter is unnecessary or overkill at this stage, we should at least add a try/except guard around the self.dm.hass.bus.async_listen call to ensure the runner doesn't fail permanently when this error is encountered.

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