notebook: Re-export viewer event types

Source-Ref: 3965e4a969b97f9d96b824b8827f606e2385a8cb

Author: oxkitsune

rerun_py/docs/gen_common_index.py

@@ -508,6 +508,23 @@ def __post_init__(self) -> None:
         show_tables=True,
         mod_path=["rerun.notebook"],
         show_submodules=True,
+        func_list=[
+            "set_default_size",
+        ],
+        class_list=[
+            "Viewer",
+            "ViewerEvent",
+            "PlayEvent",
+            "PauseEvent",
+            "TimeUpdateEvent",
+            "TimelineChangeEvent",
+            "SelectionChangeEvent",
+            "RecordingOpenEvent",
+            "SelectionItem",
+            "EntitySelectionItem",
+            "ViewSelectionItem",
+            "ContainerSelectionItem",
+        ],
     ),
     Section(
         title="Script Helpers",

rerun_py/rerun_sdk/rerun/_event.py

@@ -11,110 +11,154 @@
 #       and the serialization code, which is in `viewer_event_from_json`.
 
 
-# Base class for all viewer events
 @dataclass
 class ViewerEventBase:
+    """Base class for all viewer events."""
+
     application_id: str
+    """The application ID of the recording that triggered the event."""
+
     recording_id: str
+    """The recording ID of the recording that triggered the event."""
+
     segment_id: str | None
+    """The segment ID of the recording that triggered the event, if any."""
 
     @property
     @deprecated("Use `segment_id` instead.")
     def partition_id(self) -> str | None:
         return self.segment_id
 
 
-# Selection item types with proper type discrimination
 @dataclass
 class EntitySelectionItem:
+    """An entity selection item, representing a selected entity in the viewer."""
+
     @property
     def type(self) -> Literal["entity"]:
         return "entity"
 
     entity_path: str
+    """The entity path of the selected entity."""
+
     instance_id: int | None = None
+    """The instance ID of the selected entity, if any."""
+
     view_name: str | None = None
+    """The name of the view containing the selected entity, if any."""
+
     position: list[float] | None = None
+    """The 3D position of the selection, if any."""
 
 
 @dataclass
 class ViewSelectionItem:
+    """A view selection item, representing a selected view in the viewer."""
+
     @property
     def type(self) -> Literal["view"]:
         return "view"
 
     view_id: str
+    """The ID of the selected view."""
+
     view_name: str
+    """The name of the selected view."""
 
 
 @dataclass
 class ContainerSelectionItem:
+    """A container selection item, representing a selected container in the viewer."""
+
     @property
     def type(self) -> Literal["container"]:
         return "container"
 
     container_id: str
+    """The ID of the selected container."""
+
     container_name: str
+    """The name of the selected container."""
 
 
 SelectionItem = EntitySelectionItem | ViewSelectionItem | ContainerSelectionItem
+"""Union type for all possible selection item types."""
 
 
-# Concrete event classes
 @dataclass
 class PlayEvent(ViewerEventBase):
+    """Event triggered when the viewer starts playing."""
+
     @property
     def type(self) -> Literal["play"]:
         return "play"
 
 
 @dataclass
 class PauseEvent(ViewerEventBase):
+    """Event triggered when the viewer pauses playback."""
+
     @property
     def type(self) -> Literal["pause"]:
         return "pause"
 
 
 @dataclass
 class TimeUpdateEvent(ViewerEventBase):
+    """Event triggered when the current time changes in the viewer."""
+
     @property
     def type(self) -> Literal["time_update"]:
         return "time_update"
 
     time: float
+    """The new time value."""
 
 
 @dataclass
 class TimelineChangeEvent(ViewerEventBase):
+    """Event triggered when the active timeline changes in the viewer."""
+
     @property
     def type(self) -> Literal["timeline_change"]:
         return "timeline_change"
 
     timeline: str
+    """The name of the new active timeline."""
+
     time: float
+    """The current time value on the new timeline."""
 
 
 @dataclass
 class SelectionChangeEvent(ViewerEventBase):
+    """Event triggered when the selection changes in the viewer."""
+
     @property
     def type(self) -> Literal["selection_change"]:
         return "selection_change"
 
     items: list[SelectionItem]
+    """The list of currently selected items."""
 
 
 @dataclass
 class RecordingOpenEvent(ViewerEventBase):
+    """Event triggered when a recording is opened in the viewer."""
+
     @property
     def type(self) -> Literal["recording_open"]:
         return "recording_open"
 
     source: str
+    """The source of the recording (e.g. a URL or file path)."""
+
     version: str | None
+    """The version of the recording, if available."""
 
 
-# Union type for all possible event types
 ViewerEvent = PlayEvent | PauseEvent | TimeUpdateEvent | TimelineChangeEvent | SelectionChangeEvent | RecordingOpenEvent
+"""Union type for all possible viewer event types."""
 
 
 def _viewer_event_from_json_str(json_str: str) -> ViewerEvent:

rerun_py/rerun_sdk/rerun/notebook.py

@@ -24,7 +24,17 @@
 from rerun.error_utils import RerunMissingDependencyError
 
 from ._event import (
-    ViewerEvent,
+    ContainerSelectionItem as ContainerSelectionItem,
+    EntitySelectionItem as EntitySelectionItem,
+    PauseEvent as PauseEvent,
+    PlayEvent as PlayEvent,
+    RecordingOpenEvent as RecordingOpenEvent,
+    SelectionChangeEvent as SelectionChangeEvent,
+    SelectionItem as SelectionItem,
+    TimelineChangeEvent as TimelineChangeEvent,
+    TimeUpdateEvent as TimeUpdateEvent,
+    ViewerEvent as ViewerEvent,
+    ViewSelectionItem as ViewSelectionItem,
     _viewer_event_from_json_str,
 )
 from .recording_stream import RecordingStream, get_data_recording
@@ -477,6 +487,20 @@ def set_time_ctrl(
         self._viewer.set_time_ctrl(timeline, time, play)
 
     def on_event(self, callback: Callable[[ViewerEvent], None]) -> None:
+        """
+        Register a callback to be called when a viewer event occurs.
+
+        The callback will receive a [`ViewerEvent`][rerun.notebook.ViewerEvent], which is one of:
+        [`PlayEvent`][rerun.notebook.PlayEvent], [`PauseEvent`][rerun.notebook.PauseEvent],
+        [`TimeUpdateEvent`][rerun.notebook.TimeUpdateEvent], [`TimelineChangeEvent`][rerun.notebook.TimelineChangeEvent],
+        [`SelectionChangeEvent`][rerun.notebook.SelectionChangeEvent], or [`RecordingOpenEvent`][rerun.notebook.RecordingOpenEvent].
+
+        Parameters
+        ----------
+        callback:
+            A function that takes a [`ViewerEvent`][rerun.notebook.ViewerEvent] as its only argument.
+
+        """
         self._event_callbacks.append(callback)
 
     def set_credentials(self, access_token: str, email: str) -> None: