Rename class; add doc

homeassistant/components/zwave_js/triggers/event.py

@@ -22,11 +22,7 @@ from homeassistant.core import CALLBACK_TYPE, HomeAssistant, callback
 from homeassistant.helpers import config_validation as cv, device_registry as dr
 from homeassistant.helpers.automation import move_top_level_schema_fields_to_options
 from homeassistant.helpers.dispatcher import async_dispatcher_connect
-from homeassistant.helpers.trigger import (
+from homeassistant.helpers.trigger import Trigger, TriggerActionRunner, TriggerConfig
-    Trigger,
-    TriggerActionRunnerCallback,
-    TriggerConfig,
-)
 from homeassistant.helpers.typing import ConfigType
 
 from ..const import (
@@ -131,7 +127,7 @@ class EventTrigger(Trigger):
     _event_name: str
     _event_data_filter: dict
     _unsubs: list[Callable]
-    _action_runner: TriggerActionRunnerCallback
+    _action_runner: TriggerActionRunner
 
     @classmethod
     async def async_validate_complete_config(
@@ -175,7 +171,7 @@ class EventTrigger(Trigger):
         self._options = config.options
 
     async def async_attach_runner(
-        self, run_action: TriggerActionRunnerCallback
+        self, run_action: TriggerActionRunner
     ) -> CALLBACK_TYPE:
         """Attach a trigger."""
         dev_reg = dr.async_get(self._hass)

homeassistant/components/zwave_js/triggers/value_updated.py

@@ -16,11 +16,7 @@ from homeassistant.core import CALLBACK_TYPE, HomeAssistant, callback
 from homeassistant.helpers import config_validation as cv, device_registry as dr
 from homeassistant.helpers.automation import move_top_level_schema_fields_to_options
 from homeassistant.helpers.dispatcher import async_dispatcher_connect
-from homeassistant.helpers.trigger import (
+from homeassistant.helpers.trigger import Trigger, TriggerActionRunner, TriggerConfig
-    Trigger,
-    TriggerActionRunnerCallback,
-    TriggerConfig,
-)
 from homeassistant.helpers.typing import ConfigType
 
 from ..config_validation import VALUE_SCHEMA
@@ -93,7 +89,7 @@ async def async_validate_trigger_config(
 
 
 async def async_attach_trigger(
-    hass: HomeAssistant, options: ConfigType, run_action: TriggerActionRunnerCallback
+    hass: HomeAssistant, options: ConfigType, run_action: TriggerActionRunner
 ) -> CALLBACK_TYPE:
     """Listen for state changes based on configuration."""
     dev_reg = dr.async_get(hass)
@@ -232,7 +228,7 @@ class ValueUpdatedTrigger(Trigger):
         self._options = config.options
 
     async def async_attach_runner(
-        self, run_action: TriggerActionRunnerCallback
+        self, run_action: TriggerActionRunner
     ) -> CALLBACK_TYPE:
         """Attach a trigger."""
         return await async_attach_trigger(self._hass, self._options, run_action)

homeassistant/helpers/trigger.py

@@ -237,7 +237,7 @@ class Trigger(abc.ABC):
 
     @abc.abstractmethod
     async def async_attach_runner(
-        self, run_action: TriggerActionRunnerCallback
+        self, run_action: TriggerActionRunner
     ) -> CALLBACK_TYPE:
         """Attach the trigger to an action runner."""
 
@@ -277,7 +277,7 @@ class TriggerConfig:
     options: dict[str, Any] | None = None
 
 
-class TriggerActionRunnerCallback(Protocol):
+class TriggerActionRunner(Protocol):
     """Protocol type for the trigger action runner helper callback."""
 
     @callback
@@ -287,7 +287,11 @@ class TriggerActionRunnerCallback(Protocol):
         extra_trigger_payload: dict[str, Any],
         context: Context | None = None,
     ) -> asyncio.Future[Any] | None:
-        """Define trigger action runner type."""
+        """Define trigger action runner type.
+
+        :return: A future that allows awaiting for the action to finish if it is a
+        coroutine, or None if it is a callback.
+        """
 
 
 class TriggerActionPayloadBuilder(Protocol):

tests/helpers/test_trigger.py

@@ -24,7 +24,7 @@ from homeassistant.helpers.trigger import (
     DATA_PLUGGABLE_ACTIONS,
     PluggableAction,
     Trigger,
-    TriggerActionRunnerCallback,
+    TriggerActionRunner,
     _async_get_trigger_platform,
     async_initialize_triggers,
     async_validate_trigger_config,
@@ -464,7 +464,7 @@ async def test_platform_multiple_triggers(hass: HomeAssistant) -> None:
         """Mock trigger 1."""
 
         async def async_attach_runner(
-            self, run_action: TriggerActionRunnerCallback
+            self, run_action: TriggerActionRunner
         ) -> CALLBACK_TYPE:
             """Attach a trigger."""
             run_action("trigger 1 desc", {"extra": "test_trigger_1"})
@@ -473,7 +473,7 @@ async def test_platform_multiple_triggers(hass: HomeAssistant) -> None:
         """Mock trigger 2."""
 
         async def async_attach_runner(
-            self, run_action: TriggerActionRunnerCallback
+            self, run_action: TriggerActionRunner
         ) -> CALLBACK_TYPE:
             """Attach a trigger."""
             run_action("trigger 2 desc", {"extra": "test_trigger_2"})