Typed events

[almarklein]

Would be helpful if users can see the fields in an event. See discussion in fastplotlib/fastplotlib#852

Two options:

• TypedDict
• Dataclasses

[almarklein]

I experimented a bit, here's a proof of concept for both TypedDict and dataclass:

from typing import TypedDict, Literal
from dataclasses import dataclass

MODIFIER_KEYS = Literal["Shift", "Control", "Command", "Alt", "Meta"]

SPECIAL_KEYS = Literal["ArowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "Escape"]


# ----- dict


class BaseEventDict(TypedDict):
    type: str  # ALL_EVENT_TYPES  #: The type of the event.
    timestamp: float  #: The time of this event.
    stop_propagation: bool


class PointerEventDict(BaseEventDict):
    type: Literal[
        "pointer_down",
        "pointer_up",
        "pointer_move",
        "pointer_click",
        "pointer_double_click",
    ]
    x: float  #: The x-position in logical pixels.
    y: float  #: The y-position in logical pixels.
    button: int  #: The button being pressed, 1 for left, 2 for right, etc. 0 means no button.
    buttons: tuple[int, ...]  #: The buttons held down at the time of the event.
    modifiers: tuple[MODIFIER_KEYS, ...]


class KeyEventDict(BaseEventDict):
    type: Literal["key_down", "key_up"]
    key: SPECIAL_KEYS | str
    down: bool
    modifiers: tuple[MODIFIER_KEYS, ...]


AnyEventDict = PointerEventDict | KeyEventDict

# ----- dataclass


@dataclass
class BaseEvent:
    type: str  # ALL_EVENT_TYPES  #: The type of the event.
    timestamp: float  #: The time of this event.
    stop_propagation: bool


class PointerEvent(BaseEvent):
    type: Literal[
        "pointer_down",
        "pointer_up",
        "pointer_move",
        "pointer_click",
        "pointer_double_click",
    ]
    x: float  #: The x-position in logical pixels.
    y: float  #: The y-position in logical pixels.
    button: int  #: The button being pressed, 1 for left, 2 for right, etc. 0 means no button.
    buttons: tuple[int, ...]  #: The buttons held down at the time of the event.
    modifiers: tuple[MODIFIER_KEYS, ...]


class KeyEvent(BaseEvent):
    type: Literal["key_down", "key_up"]
    key: SPECIAL_KEYS | str
    modifiers: tuple[MODIFIER_KEYS, ...]


AnyEvent = PointerEvent | KeyEvent

# -------------------------------------------

# ----- user code for dicts -----

def on_key1(event: AnyEventDict):
    if event["type"] == "key_down":
        # within this block, the type checker (and IDE) know this is a key event
        if event["key"] == "ArowLeft":
            pass

# ----- user code for dataclass -----

def on_key2(event: AnyEvent):
    if event.type == "key_down":
        # within this block, the type checker (and IDE) know this is a key event
        if event.key == "ArowLeft":
            pass

The type resolving actually works quite the same. In both cases, testing on event.type allows the type checker to refine the type, which is great in handlers that handle multiple types of events. The "key_down" and "ArrowLeft" are also autocompleted.

The difference from the user perspective is that with dicts it feels a bit more 'clumsy'. E.g. if you select the text in a key, the autocompletion does not kick in automatically.

The TypedDict does 'feel' lighter though.

As for static checking (which would be a great improvement to guarantee backends are consistent) we can do that easiest where the backends produce the events, and use mypy. BTW if backends create untyped dicts that are later converted to dataclasses, we'd miss out on the type checks.