Consolidate string aliases to streamdeck.types

Author: strohganoff

streamdeck/actions.py

@@ -11,17 +11,12 @@
     from collections.abc import Callable, Generator
     from typing import Protocol
 
-    from typing_extensions import ParamSpec, TypeAlias, TypeVar  # noqa: UP035
+    from typing_extensions import ParamSpec, TypeVar
 
     from streamdeck.models.events import EventBase
+    from streamdeck.types import ActionUUIDStr, EventNameStr
 
 
-    EventNameStr: TypeAlias = str  # noqa: UP040
-    """Type alias for the event name string.
-
-    We don't define literal string values here, as the list of available event names can be added to dynamically.
-    """
-
 
     EventModel_contra = TypeVar("EventModel_contra", bound=EventBase, default=EventBase, contravariant=True)
     InjectableParams = ParamSpec("InjectableParams", default=...)
@@ -39,11 +34,7 @@ class ActionBase(ABC):
     """Base class for all actions."""
 
     def __init__(self) -> None:
-        """Initialize an Action instance.
-
-        Args:
-            uuid (str): The unique identifier for the action.
-        """
+        """Initialize an Action instance."""
         self._events: dict[EventNameStr, set[EventHandlerFunc]] = defaultdict(set)
 
     def on(self, event_name: EventNameStr, /) -> Callable[[EventHandlerFunc[EventModel_contra, InjectableParams]], EventHandlerFunc[EventModel_contra, InjectableParams]]:
@@ -98,7 +89,7 @@ class GlobalAction(ActionBase):
 class Action(ActionBase):
     """Represents an action that can be performed for a specific action, with event handlers for specific event types."""
 
-    def __init__(self, uuid: str) -> None:
+    def __init__(self, uuid: ActionUUIDStr) -> None:
         """Initialize an Action instance.
 
         Args:
@@ -128,7 +119,7 @@ def register(self, action: ActionBase) -> None:
         """
         self._plugin_actions.append(action)
 
-    def get_action_handlers(self, event_name: EventNameStr, event_action_uuid: str | None = None) -> Generator[EventHandlerFunc, None, None]:
+    def get_action_handlers(self, event_name: EventNameStr, event_action_uuid: ActionUUIDStr | None = None) -> Generator[EventHandlerFunc, None, None]:
         """Get all event handlers for a specific event from all registered actions.
 
         Args:

streamdeck/command_sender.py

@@ -7,6 +7,13 @@
 if TYPE_CHECKING:
     from typing import Any, Literal
 
+    from streamdeck.types import (
+        ActionInstanceUUIDStr,
+        ActionUUIDStr,
+        DeviceUUIDStr,
+        EventNameStr,
+        PluginDefinedData,
+    )
     from streamdeck.websocket import WebSocketClient
 
 
@@ -16,30 +23,31 @@
 
 class StreamDeckCommandSender:
     """Class for sending command event messages to the Stream Deck software through a WebSocket client."""
+
     def __init__(self, client: WebSocketClient, plugin_registration_uuid: str):
         self._client = client
         self._plugin_registration_uuid = plugin_registration_uuid
 
-    def _send_event(self, event: str, **kwargs: Any) -> None:
+    def _send_event(self, event: EventNameStr, **kwargs: Any) -> None:
         self._client.send_event({
             "event": event,
             **kwargs,
         })
 
-    def set_settings(self, context: str, payload: dict[str, Any]) -> None:
+    def set_settings(self, context: ActionInstanceUUIDStr, payload: PluginDefinedData) -> None:
         self._send_event(
             event="setSettings",
             context=context,
             payload=payload,
         )
 
-    def get_settings(self, context: str) -> None:
+    def get_settings(self, context: ActionInstanceUUIDStr) -> None:
         self._send_event(
             event="getSettings",
             context=context,
         )
 
-    def set_global_settings(self, payload: dict[str, Any]) -> None:
+    def set_global_settings(self, payload: PluginDefinedData) -> None:
         self._send_event(
             event="setGlobalSettings",
             context=self._plugin_registration_uuid,
@@ -52,14 +60,14 @@ def get_global_settings(self) -> None:
             context=self._plugin_registration_uuid,
         )
 
-    def open_url(self, context: str, url: str) -> None:
+    def open_url(self, context: ActionInstanceUUIDStr, url: str) -> None:
         self._send_event(
             event="openUrl",
             context=context,
             payload={"url": url},
         )
 
-    def log_message(self, context: str, message: str) -> None:
+    def log_message(self, context: ActionInstanceUUIDStr, message: str) -> None:
         self._send_event(
             event="logMessage",
             context=context,
@@ -68,10 +76,10 @@ def log_message(self, context: str, message: str) -> None:
 
     def set_title(
         self,
-        context: str,
+        context: ActionInstanceUUIDStr,
         state: int | None = None,
-        target: str | None = None,
-        title: str | None = None
+        target: Literal["hardware", "software", "both"] | None = None,
+        title: str | None = None,
     ) -> None:
         payload = {}
 
@@ -90,10 +98,10 @@ def set_title(
 
     def set_image(
         self,
-        context: str,
-        image: str,                                         # base64 encoded image,
-        target: Literal["hardware", "software", "both"],    # software, hardware, or both,
-        state: int,                                         # 0-based integer
+        context: ActionInstanceUUIDStr,
+        image: str,  # base64 encoded image,
+        target: Literal["hardware", "software", "both"],
+        state: int,
     ) -> None:
         """...
 
@@ -117,14 +125,26 @@ def set_image(
             },
         )
 
-    def set_feedback(self, context: str, payload: dict[str, Any]) -> None:
+    def set_feedback(self, context: ActionInstanceUUIDStr, payload: PluginDefinedData) -> None:
+        """Set's the feedback of an existing layout associated with an action instance.
+
+        Args:
+          context (str): Defines the context of the command, e.g. which action instance the command is intended for.
+          payload (PluginDefinedData): Additional information supplied as part of the command.
+        """
         self._send_event(
             event="setFeedback",
             context=context,
             payload=payload,
         )
 
-    def set_feedback_layout(self, context: str, layout: str) -> None:
+    def set_feedback_layout(self, context: ActionInstanceUUIDStr, layout: str) -> None:
+        """Sets the layout associated with an action instance.
+
+        Args:
+          context (str): Defines the context of the command, e.g. which action instance the command is intended for.
+          layout (str): Name of a pre-defined layout, or relative path to a custom one.
+        """
         self._send_event(
             event="setFeedbackLayout",
             context=context,
@@ -133,7 +153,7 @@ def set_feedback_layout(self, context: str, layout: str) -> None:
 
     def set_trigger_description(
         self,
-        context: str,
+        context: ActionInstanceUUIDStr,
         rotate: str | None = None,
         push: str | None = None,
         touch: str | None = None,
@@ -170,21 +190,21 @@ def set_trigger_description(
             },
         )
 
-    def show_alert(self, context: str) -> None:
+    def show_alert(self, context: ActionInstanceUUIDStr) -> None:
         """Temporarily show an alert icon on the image displayed by an instance of an action."""
         self._send_event(
             event="showAlert",
             context=context,
         )
 
-    def show_ok(self, context: str) -> None:
+    def show_ok(self, context: ActionInstanceUUIDStr) -> None:
         """Temporarily show an OK checkmark icon on the image displayed by an instance of an action."""
         self._send_event(
             event="showOk",
             context=context,
         )
 
-    def set_state(self, context: str, state: int) -> None:
+    def set_state(self, context: ActionInstanceUUIDStr, state: int) -> None:
         self._send_event(
             event="setState",
             context=context,
@@ -193,8 +213,8 @@ def set_state(self, context: str, state: int) -> None:
 
     def switch_to_profile(
         self,
-        context: str,
-        device: str,
+        context: ActionInstanceUUIDStr,
+        device: DeviceUUIDStr,
         profile: str | None = None,
         page: int = 0,
     ) -> None:
@@ -211,7 +231,7 @@ def switch_to_profile(
             page (int):  Page to show when switching to the profile; indexed from 0.
         """
         # TODO: Should validation happen that ensures the specified profile is declared in manifest.yaml?
-        payload = {}
+        payload: dict[str, str | int | None] = {}
 
         if profile is not None:
             payload = {
@@ -226,18 +246,17 @@ def switch_to_profile(
             payload=payload,
         )
 
-    def send_to_property_inspector(self, context: str, payload: dict[str, Any]) -> None:
+    def send_to_property_inspector(
+        self, context: ActionInstanceUUIDStr, payload: PluginDefinedData
+    ) -> None:
         self._send_event(
             event="sendToPropertyInspector",
             context=context,
             payload=payload,
         )
 
     def send_to_plugin(
-        self,
-        context: str,
-        action: str,
-        payload: dict[str, Any]
+        self, context: ActionInstanceUUIDStr, action: ActionUUIDStr, payload: PluginDefinedData
     ) -> None:
         """Send a payload to another plugin.
 

streamdeck/models/events/__init__.py

@@ -31,6 +31,9 @@
 if TYPE_CHECKING:
     from typing import Final
 
+    from streamdeck.types import EventNameStr
+
+
 
 DEFAULT_EVENT_MODELS: Final[list[type[EventBase]]] = [
     ApplicationDidLaunch,
@@ -56,16 +59,16 @@
 ]
 
 
-def _get_default_event_names() -> set[str]:
-    default_event_names: set[str] = set()
+def _get_default_event_names() -> set[EventNameStr]:
+    default_event_names: set[EventNameStr] = set()
 
     for event_model in DEFAULT_EVENT_MODELS:
         default_event_names.update(event_model.get_model_event_names())
 
     return default_event_names
 
 
-DEFAULT_EVENT_NAMES: Final[set[str]] = _get_default_event_names()
+DEFAULT_EVENT_NAMES: Final[set[EventNameStr]] = _get_default_event_names()
 
 
 

streamdeck/models/events/adapter.py

@@ -8,7 +8,10 @@
 
 
 if TYPE_CHECKING:
+    from typing_extensions import TypeIs
+
     from streamdeck.models.events.base import EventBase
+    from streamdeck.types import EventNameStr
 
 
 class EventAdapter:
@@ -17,7 +20,7 @@ def __init__(self) -> None:
         self._models: list[type[EventBase]] = []
         self._type_adapter: TypeAdapter[EventBase] | None = None
 
-        self._event_names: set[str] = set()
+        self._event_names: set[EventNameStr] = set()
         """A set of all event names that have been registered with the adapter.
         This set starts out containing the default event models defined by the library.
         """
@@ -32,7 +35,7 @@ def add_model(self, model: type[EventBase]) -> None:
         # so `get_model_event_names()` returns a tuple of all event names, even if there is only one.
         self._event_names.update(model.get_model_event_names())
 
-    def event_name_exists(self, event_name: str) -> bool:
+    def event_name_exists(self, event_name: str) -> TypeIs[EventNameStr]:
         """Check if an event name has been registered with the adapter."""
         return event_name in self._event_names
 

streamdeck/models/events/base.py

@@ -55,6 +55,8 @@ class EventMetadataDict(TypedDict):
 
     from pydantic._internal._model_construction import ModelMetaclass  # type: ignore[import]
 
+    from streamdeck.types import EventNameStr
+
     class EventMeta(ModelMetaclass):
         """Metaclass for EventBase stub to satisfy static type checkers."""
         @classmethod
@@ -78,7 +80,7 @@ class TestEvent(EventBase["test", "testing"]):
 
         ```
         """
-        event: LiteralString
+        event: EventNameStr
         """Name of the event used to identify what occurred.
 
         Subclass models must define this field as a Literal type with the event name string that the model represents.
@@ -89,7 +91,7 @@ class TestEvent(EventBase["test", "testing"]):
         """Return the event type for the event model."""
 
         @classmethod
-        def get_model_event_names(cls) -> tuple[str, ...]:
+        def get_model_event_names(cls) -> tuple[EventNameStr, ...]:
             """Return the event names for the event model."""
             ...
 

streamdeck/models/events/common.py

@@ -3,36 +3,38 @@
 from abc import ABC
 from typing import Annotated, Generic, Literal, NamedTuple, Optional, Union
 
-from pydantic import Field, JsonValue
+from pydantic import Field
 from typing_extensions import TypedDict, TypeVar
 
 from streamdeck.models.events.base import ConfiguredBaseModel
+from streamdeck.types import (  # noqa: TC001
+    ActionInstanceUUIDStr,
+    DeviceUUIDStr,
+    EventNameStr,
+    PluginDefinedData,
+)
 
 
 ## Mixin classes for common event model fields.
 
 class ContextualEventMixin:
     """Mixin class for event models that have action and context fields."""
-    action: str
+    action: EventNameStr
     """Unique identifier of the action"""
-    context: str
+    context: ActionInstanceUUIDStr
     """Identifies the instance of an action that caused the event, i.e. the specific key or dial."""
 
 
 class DeviceSpecificEventMixin:
     """Mixin class for event models that have a device field."""
-    device: str
+    device: DeviceUUIDStr
     """Unique identifier of the Stream Deck device that this event is associated with."""
 
 
 ## Payload models and metadata used by multiple event models.
 
 
-PluginDefinedData = dict[str, JsonValue]
-"""Data of arbitrary structure that is defined in and relevant to the plugin.
 
-The root of the data structure will always be a dict of string keys, while the values can be any JSON-compatible type.
-"""
 
 
 EncoderControllerType = Literal["Encoder"]

streamdeck/models/events/property_inspector.py

@@ -4,8 +4,8 @@
 from streamdeck.models.events.common import (
     ContextualEventMixin,
     DeviceSpecificEventMixin,
-    PluginDefinedData,
 )
+from streamdeck.types import PluginDefinedData  # noqa: TC001
 
 
 class DidReceivePropertyInspectorMessage(EventBase["sendToPlugin"], ContextualEventMixin):