Create Controller type TypeAliases, and generic base classes to define which controller type is used by a payload model

Author: strohganoff

streamdeck/models/events/common.py

@@ -1,6 +1,10 @@
 from __future__ import annotations
 
-from typing import Any, Literal, Optional
+from abc import ABC
+from typing import Annotated, Any, Generic, Literal, NamedTuple, Optional, Union
+
+from pydantic import Field
+from typing_extensions import TypedDict, TypeVar
 
 from streamdeck.models.events.base import ConfiguredBaseModel
 
@@ -23,6 +27,17 @@ class DeviceSpecificEventMixin:
 
 ## Payload models and metadata used by multiple event models.
 
+
+EncoderControllerType = Literal["Encoder"]
+"""The 'Encoder' controller type refers to a dial or touchscreen on a 'Stream Deck +' device."""
+KeypadControllerType = Literal["Keypad"]
+"""The 'Keypad' controller type refers to a standard action on a Stream Deck device, e.g. buttons or a pedal."""
+ControllerType = Literal[EncoderControllerType, KeypadControllerType]
+"""Defines the controller type the action is applicable to."""
+
+CT = TypeVar("CT", bound=ControllerType, default=ControllerType)
+
+
 PluginDefinedData = dict[str, Any]
 """Data of arbitrary structure that is defined in and relevant to the plugin."""
 
@@ -66,6 +81,28 @@ def coordinates(self) -> Coordinates:
         return Coordinates(**self.coordinates_obj)
 
 
+class BasePayload(ConfiguredBaseModel, Generic[CT], ABC):
+    """Base class for all complex payload models."""
+    controller: CT
+    """Defines the controller type the action is applicable to.
+
+    'Keypad' refers to a standard action on a Stream Deck device, e.g. buttons or a pedal.
+    'Encoder' refers to a dial / touchscreen on a 'Stream Deck +' device.
+    """
+    settings: PluginDefinedData
+    """Settings associated with the action instance."""
+
+
+class BaseActionPayload(BasePayload[CT], ABC):
+    """Base class for payloads of action events."""
+
+    state: Optional[int] = None  # noqa: UP007
+    """Current state of the action.
+
+    Only applicable to actions that have multiple states defined within the manifest.json file.
+    """
+
+
 class SingleActionPayloadMixin:
     """Mixin class for event models that have a single action payload."""
 
@@ -88,36 +125,3 @@ class MultiActionPayloadMixin:
     Field(discriminator="is_in_multi_action"),
 ]
 """Generic type for a payload that either subclasses SingleActionPayloadMixin or MultiActionPayloadMixin—meaning it can be either a single action or a multi-action."""
-
-
-class SingleActionPayload(ConfiguredBaseModel, CoordinatesPayloadMixin, SingleActionPayloadMixin):
-    """Contextualized information for a willAppear, willDisappear, and didReceiveSettings events that are not part of a multi-action."""
-    controller: Literal["Encoder", "Keypad"]
-    """Defines the controller type the action is applicable to.
-
-    'Keypad' refers to a standard action on a Stream Deck device, e.g. buttons or a pedal.
-    'Encoder' refers to a dial / touchscreen.
-    """
-    state: Optional[int] = None  # noqa: UP007
-    """Current state of the action; only applicable to actions that have multiple states defined within the manifest.json file."""
-    settings: PluginDefinedData
-    """Settings associated with the action instance."""
-
-
-class MultiActionPayload(ConfiguredBaseModel, MultiActionPayloadMixin):
-    """Contextualized information for a willAppear, willDisappear, and didReceiveSettings events that are part of a multi-action.
-
-    NOTE: Action instances that are part of a multi-action are only applicable to the 'Keypad' controller type.
-    """
-    controller: Literal["Keypad"]
-    """The 'Keypad' controller type refers to a standard action on a Stream Deck device, e.g. buttons or a pedal.
-
-    Action instances that are part of a multi-action are only applicable to the 'Keypad' controller type.
-    """
-    state: Optional[int] = None  # noqa: UP007
-    """Current state of the action; only applicable to actions that have multiple states defined within the manifest.json file."""
-    settings: PluginDefinedData
-    """Settings associated with the action instance."""
-
-
-

streamdeck/models/events/dials.py

@@ -2,34 +2,28 @@
 
 from typing import Literal
 
-from streamdeck.models.events.base import ConfiguredBaseModel, EventBase
+from streamdeck.models.events.base import EventBase
 from streamdeck.models.events.common import (
+    BasePayload,
     ContextualEventMixin,
     CoordinatesPayloadMixin,
     DeviceSpecificEventMixin,
-    PluginDefinedData,
+    EncoderControllerType,
 )
 
 
 ## Payload models used in the below DialDown, DialRotate, and DialUp events
 
-class EncoderPayload(ConfiguredBaseModel, CoordinatesPayloadMixin):
+class EncoderPayload(BasePayload[EncoderControllerType], CoordinatesPayloadMixin):
     """Contextualized information for a DialDown or DialUp event."""
-    controller: Literal["Encoder"]
-    """The 'Encoder' controller type refers to a dial or touchscreen on a 'Stream Deck +' device."""
-    settings: PluginDefinedData
 
 
-class DialRotatePayload(ConfiguredBaseModel, CoordinatesPayloadMixin):
+class DialRotatePayload(EncoderPayload):
     """Contextualized information for a DialRotate event."""
-    controller: Literal["Encoder"]
-    """The 'Encoder' controller type refers to a dial or touchscreen on a 'Stream Deck +' device."""
     pressed: bool
     """Determines whether the dial was pressed whilst the rotation occurred."""
     ticks: int
     """Number of ticks the dial was rotated; this can be a positive (clockwise) or negative (counter-clockwise) number."""
-    settings: PluginDefinedData
-    """Settings associated with the action instance."""
 
 
 ## Event models for DialDown, DialRotate, and DialUp events

streamdeck/models/events/keys.py

@@ -1,44 +1,39 @@
 from __future__ import annotations
 
-from typing import Annotated, Literal, Optional, Union
+from typing import Annotated, Literal
 
 from pydantic import Field
 
-from streamdeck.models.events.base import ConfiguredBaseModel, EventBase
+from streamdeck.models.events.base import EventBase
 from streamdeck.models.events.common import (
+    BaseActionPayload,
     CardinalityDiscriminated,
     ContextualEventMixin,
     CoordinatesPayloadMixin,
     DeviceSpecificEventMixin,
+    KeypadControllerType,
     MultiActionPayloadMixin,
     SingleActionPayloadMixin,
 )
 
 
 ## Payload models used in the below KeyDown and KeyUp events
 
-class SingleActionKeyGesturePayload(ConfiguredBaseModel, SingleActionPayloadMixin, CoordinatesPayloadMixin):
+# It seems like for keyDown and keyUp events, the "controller" field is probably always missing, despite being defined in the official documentation.
+OptionalKeyControllerTypeField = Annotated[KeypadControllerType, Field(default=None)]
+
+
+class SingleActionKeyGesturePayload(BaseActionPayload[OptionalKeyControllerTypeField], SingleActionPayloadMixin, CoordinatesPayloadMixin):
     """Contextualized information for a KeyDown or KeyUp event that is not part of a multi-action."""
-    controller: Optional[Literal["Keypad"]] = None  # noqa: UP007
-    """The 'Keypad' controller type refers to a standard action on a Stream Deck device, e.g. buttons or a pedal."""
-    state: Optional[int] = None  # noqa: UP007
-    """Current state of the action; only applicable to actions that have multiple states defined within the manifest.json file."""
-    settings: PluginDefinedData
-    """Settings associated with the action instance."""
 
 
-class MultiActionKeyGesturePayload(ConfiguredBaseModel, MultiActionPayloadMixin):
+class MultiActionKeyGesturePayload(BaseActionPayload[OptionalKeyControllerTypeField], MultiActionPayloadMixin):
     """Contextualized information for a KeyDown or KeyUp event that is part of a multi-action."""
-    controller: Optional[Literal["Keypad"]] = None  # noqa: UP007
-    """The 'Keypad' controller type refers to a standard action on a Stream Deck device, e.g. buttons or a pedal."""
-    state: Optional[int] = None  # noqa: UP007
-    """Current state of the action; only applicable to actions that have multiple states defined within the manifest.json file."""
     user_desired_state: Annotated[int, Field(alias="userDesiredState")]
     """Desired state as specified by the user.
 
     Only applicable to actions that have multiple states defined within the manifest.json file, and when this action instance is part of a multi-action.
     """
-    settings: PluginDefinedData
 
 
 ## Event models for KeyDown and KeyUp events

streamdeck/models/events/settings.py

@@ -1,24 +1,38 @@
 from __future__ import annotations
 
-from typing import Annotated, Literal, Union
-
-from pydantic import Field
+from typing import Literal
 
 from streamdeck.models.events.base import ConfiguredBaseModel, EventBase
 from streamdeck.models.events.common import (
+    BaseActionPayload,
     CardinalityDiscriminated,
     ContextualEventMixin,
+    CoordinatesPayloadMixin,
     DeviceSpecificEventMixin,
-    MultiActionPayload,
+    KeypadControllerType,
+    MultiActionPayloadMixin,
     PluginDefinedData,
-    SingleActionPayload,
+    SingleActionPayloadMixin,
 )
 
 
+## Models for didReceiveSettings event and its specific payloads.
+
+class SingleActionSettingsPayload(BaseActionPayload, SingleActionPayloadMixin, CoordinatesPayloadMixin):
+    """Contextualized information for a didReceiveSettings events that are not part of a multi-action."""
+
+
+class MultiActionSettingsPayload(BaseActionPayload[KeypadControllerType], MultiActionPayloadMixin):
+    """Contextualized information for a didReceiveSettings events that are part of a multi-action.
+
+    NOTE: Action instances that are part of a multi-action are only applicable to the 'Keypad' controller type.
+    """
+
+
 class DidReceiveSettings(EventBase, ContextualEventMixin, DeviceSpecificEventMixin):
     """Occurs when the settings associated with an action instance are requested, or when the the settings were updated by the property inspector."""
     event: Literal["didReceiveSettings"]  # type: ignore[override]
-    payload: CardinalityDiscriminated[SingleActionPayload, MultiActionPayload]
+    payload: CardinalityDiscriminated[SingleActionSettingsPayload, MultiActionSettingsPayload]
     """Contextualized information for this event."""
 
 

streamdeck/models/events/title_parameters.py

@@ -1,14 +1,14 @@
 from __future__ import annotations
 
-from typing import Annotated, Literal, Optional
+from typing import Annotated, Literal
 
 from pydantic import Field
 
 from streamdeck.models.events.base import ConfiguredBaseModel, EventBase
 from streamdeck.models.events.common import (
+    BaseActionPayload,
     CoordinatesPayloadMixin,
     DeviceSpecificEventMixin,
-    PluginDefinedData,
 )
 
 
@@ -34,17 +34,13 @@ class TitleParameters(ConfiguredBaseModel):
     """Color of the title, represented as a hexadecimal value."""
 
 
-class TitleParametersDidChangePayload(ConfiguredBaseModel, CoordinatesPayloadMixin):
+class TitleParametersDidChangePayload(BaseActionPayload, CoordinatesPayloadMixin):
     """Contextualized information for this event."""
-    controller: Literal["Keypad", "Encoder"]
-    """Defines the controller type the action is applicable to."""
     title: str
     """Title of the action, as specified by the user or dynamically by the plugin."""
     title_parameters: Annotated[TitleParameters, Field(alias="titleParameters")]
     """Defines aesthetic properties that determine how the title should be rendered."""
-    state: Optional[int]  # noqa: UP007
-    """Current state of the action; only applicable to actions that have multiple states defined within the manifest.json file."""
-    settings: PluginDefinedData
+
 
 class TitleParametersDidChange(EventBase, DeviceSpecificEventMixin):
     """Occurs when the user updates an action's title settings in the Stream Deck application."""

streamdeck/models/events/touch_tap.py

@@ -6,22 +6,21 @@
 
 from streamdeck.models.events.base import EventBase
 from streamdeck.models.events.common import (
+    BasePayload,
     ContextualEventMixin,
     CoordinatesPayloadMixin,
     DeviceSpecificEventMixin,
-    PluginDefinedData,
+    EncoderControllerType,
 )
 
 
-class TouchTapPayload(ConfiguredBaseModel, CoordinatesPayloadMixin):
+class TouchTapPayload(BasePayload[EncoderControllerType], CoordinatesPayloadMixin):
     """Contextualized information for a TouchTap event."""
-    controller: Literal["Encoder"]
-    """The 'Encoder' controller type refers to a dial or touchscreen on a 'Stream Deck +' device."""
     hold: bool
     """Determines whether the tap was considered 'held'."""
     tap_position: Annotated[tuple[int, int], Field(alias="tapPos")]
     """Coordinates of where the touchscreen tap occurred, relative to the canvas of the action."""
-    settings: PluginDefinedData
+
 
 class TouchTap(EventBase, ContextualEventMixin, DeviceSpecificEventMixin):
     """Occurs when the user taps the touchscreen (Stream Deck +)."""

streamdeck/models/events/visibility.py

@@ -1,19 +1,28 @@
 from __future__ import annotations
 
-from typing import Annotated, Literal, Union
-
-from pydantic import Field
+from typing import Literal
 
 from streamdeck.models.events.base import EventBase
 from streamdeck.models.events.common import (
+    BaseActionPayload,
     CardinalityDiscriminated,
     ContextualEventMixin,
+    CoordinatesPayloadMixin,
     DeviceSpecificEventMixin,
-    MultiActionPayload,
-    SingleActionPayload,
+    KeypadControllerType,
+    MultiActionPayloadMixin,
+    SingleActionPayloadMixin,
 )
 
 
+class SingleActionVisibilityPayload(BaseActionPayload, SingleActionPayloadMixin, CoordinatesPayloadMixin):
+    """Contextualized information for willAppear and willDisappear events that is not part of a multi-action."""
+
+
+class MultiActionVisibilityPayload(BaseActionPayload[KeypadControllerType], MultiActionPayloadMixin):
+    """Contextualized information for willAppear and willDisappear events that is part of a multi-action."""
+
+
 ## Event models for WillAppear and WillDisappear events
 
 class WillAppear(EventBase, ContextualEventMixin, DeviceSpecificEventMixin):
@@ -23,7 +32,7 @@ class WillAppear(EventBase, ContextualEventMixin, DeviceSpecificEventMixin):
     An action refers to all types of actions, e.g. keys, dials, touchscreens, pedals, etc.
     """
     event: Literal["willAppear"]  # type: ignore[override]
-    payload: CardinalityDiscriminated[SingleActionPayload, MultiActionPayload]
+    payload: CardinalityDiscriminated[SingleActionVisibilityPayload, MultiActionVisibilityPayload]
 
 
 class WillDisappear(EventBase, ContextualEventMixin, DeviceSpecificEventMixin):
@@ -32,4 +41,4 @@ class WillDisappear(EventBase, ContextualEventMixin, DeviceSpecificEventMixin):
     An action refers to all types of actions, e.g. keys, dials, touchscreens, pedals, etc.
     """
     event: Literal["willDisappear"]  # type: ignore[override]
-    payload: CardinalityDiscriminated[SingleActionPayload, MultiActionPayload]
+    payload: CardinalityDiscriminated[SingleActionVisibilityPayload, MultiActionVisibilityPayload]