Improve docstring formatting in event_recorder.py

Refactor docstrings for clarity and consistency in event recorder classes.

Author: AdityaGupta716

fury/ui/event_recorder.py

@@ -1,18 +1,10 @@
-"""
-fury/ui/event_recorder.py
+"""Fury UI event recorder, counter, and player.
 
 UI Event Recorder, Counter, and Player for FURY v2.
 
 Attaches to ``show_manager.renderer`` (a rendercanvas ``EventEmitter``-backed
-``Renderer``) and observes dict-based events dispatched through it.  No VTK
+``Renderer``) and observes dict-based events dispatched through it. No VTK
 dependency; works with the pygfx/rendercanvas/wgpu stack used by FURY v2.
-
-Classes
--------
-RecordedEvent   – Immutable snapshot of a single rendercanvas event.
-EventRecorder   – Hooks into ShowManager.renderer and records events to JSON.
-EventCounter    – Subclass that tallies events by type for test assertions.
-EventPlayer     – Replays a saved session into a ShowManager.renderer.
 """
 
 from __future__ import annotations
@@ -44,11 +36,12 @@
 # RecordedEvent
 # ---------------------------------------------------------------------------
 
+
 @dataclass(frozen=True)
 class RecordedEvent:
     """Immutable snapshot of a single rendercanvas UI event.
 
-    Attributes
+    Parameters
     ----------
     event_type : str
         rendercanvas event type string, e.g. ``"pointer_down"``.
@@ -91,14 +84,31 @@ class RecordedEvent:
     # ------------------------------------------------------------------
 
     def to_dict(self) -> Dict[str, Any]:
-        """Return a JSON-serialisable representation."""
+        """Return a JSON-serialisable representation.
+
+        Returns
+        -------
+        dict
+            JSON-serialisable representation of this event.
+        """
         d = asdict(self)
         d["modifiers"] = list(d["modifiers"])
         return d
 
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "RecordedEvent":
-        """Reconstruct from a plain dict (e.g. loaded from JSON)."""
+        """Reconstruct from a plain dict (e.g. loaded from JSON).
+
+        Parameters
+        ----------
+        data : dict
+            Plain dict with event fields.
+
+        Returns
+        -------
+        RecordedEvent
+            Reconstructed event instance.
+        """
         return cls(
             event_type=data["event_type"],
             timestamp=data.get("timestamp", 0.0),
@@ -123,24 +133,33 @@ def from_rendercanvas_event(cls, event: Any) -> "RecordedEvent":
 
         Parameters
         ----------
-        event :
+        event : Any
             A rendercanvas event dict or event object.
 
         Returns
         -------
         RecordedEvent
+            Snapshot of the given event.
         """
         if isinstance(event, dict):
+
             def _get(key: str, default: Any = None) -> Any:
                 return event.get(key, default)
+
             raw = dict(event)
         else:
+
             def _get(key: str, default: Any = None) -> Any:  # type: ignore[misc]
                 return getattr(event, key, default)
+
             # Serialise object to a dict so raw is always JSON-safe.
             try:
                 raw = {
-                    "event_type": getattr(event, "event_type", getattr(event, "type", "")),
+                    "event_type": getattr(
+                        event,
+                        "event_type",
+                        getattr(event, "type", ""),
+                    ),
                     "x": float(getattr(event, "x", 0)),
                     "y": float(getattr(event, "y", 0)),
                     "button": int(getattr(event, "button", 0)),
@@ -149,7 +168,9 @@ def _get(key: str, default: Any = None) -> Any:  # type: ignore[misc]
                     "modifiers": list(getattr(event, "modifiers", [])),
                     "dx": float(getattr(event, "dx", 0)),
                     "dy": float(getattr(event, "dy", 0)),
-                    "time_stamp": float(getattr(event, "time_stamp", time.perf_counter())),
+                    "time_stamp": float(
+                        getattr(event, "time_stamp", time.perf_counter())
+                    ),
                 }
             except Exception:
                 raw = {}
@@ -158,9 +179,10 @@ def _get(key: str, default: Any = None) -> Any:  # type: ignore[misc]
         # attribute (some pygfx event objects).
         et = _get("event_type") or _get("type") or ""
 
+        ts = _get("time_stamp")
         return cls(
             event_type=str(et),
-            timestamp=float(ts if (ts := _get("time_stamp")) is not None else time.perf_counter()),
+            timestamp=float(ts if ts is not None else time.perf_counter()),
             x=float(_get("x") or 0),
             y=float(_get("y") or 0),
             button=int(_get("button") or 0),
@@ -181,6 +203,7 @@ def to_rendercanvas_event(self) -> Dict[str, Any]:
         Returns
         -------
         dict
+            Rendercanvas-compatible event dict.
         """
         if self.raw:
             evt = dict(self.raw)
@@ -205,12 +228,13 @@ def to_rendercanvas_event(self) -> Dict[str, Any]:
 # EventRecorder
 # ---------------------------------------------------------------------------
 
+
 class EventRecorder:
     """Records UI events from a FURY v2 ShowManager.
 
     Hooks into ``show_manager.renderer`` (the rendercanvas Renderer /
     EventEmitter) and registers an observer for every event type in
-    :attr:`DEFAULT_OBSERVED_EVENTS`.  Each incoming event is packaged into a
+    :attr:`DEFAULT_OBSERVED_EVENTS`. Each incoming event is packaged into a
     :class:`RecordedEvent` and appended to an internal log.
 
     Parameters
@@ -222,7 +246,7 @@ class EventRecorder:
     --------
     >>> recorder = EventRecorder()
     >>> recorder.attach(show_manager)
-    >>> # … user interacts …
+    >>> # ... user interacts ...
     >>> recorder.detach()
     >>> recorder.save("session.json")
     """
@@ -240,9 +264,7 @@ def __init__(
         self._renderer: Any = None
         self._recording: bool = False
         # Store a stable reference to the bound method so that add/remove
-        # handler identity checks (``cb is not callback``) work correctly.
-        # Python bound methods are not singletons — ``self._on_event is
-        # self._on_event`` can be False.
+        # handler identity checks work correctly.
         self._callback_ref: Callable = self._on_event
 
     # ------------------------------------------------------------------
@@ -251,12 +273,24 @@ def __init__(
 
     @property
     def events(self) -> List[RecordedEvent]:
-        """A copy of the captured event log (read-only)."""
+        """A copy of the captured event log (read-only).
+
+        Returns
+        -------
+        list[RecordedEvent]
+            Copy of the internal event log.
+        """
         return list(self._events)
 
     @property
     def is_recording(self) -> bool:
-        """``True`` while actively recording."""
+        """``True`` while actively recording.
+
+        Returns
+        -------
+        bool
+            Whether the recorder is currently attached and recording.
+        """
         return self._recording
 
     # ------------------------------------------------------------------
@@ -268,7 +302,7 @@ def attach(self, show_manager: Any) -> None:
 
         Parameters
         ----------
-        show_manager :
+        show_manager : Any
             A FURY v2 :class:`~fury.window.ShowManager`.
 
         Raises
@@ -284,7 +318,8 @@ def attach(self, show_manager: Any) -> None:
             )
         renderer = self._resolve_renderer(show_manager)
         self._renderer = renderer
-        # rendercanvas Renderer exposes add_event_handler (wraps EventEmitter.add_handler)
+        # rendercanvas Renderer exposes add_event_handler (wraps
+        # EventEmitter.add_handler)
         renderer.add_event_handler(self._callback_ref, *self._observed)
         self._recording = True
 
@@ -298,7 +333,9 @@ def detach(self) -> None:
             if hasattr(self._renderer, "remove_handler"):
                 self._renderer.remove_handler(self._callback_ref, *self._observed)
             elif hasattr(self._renderer, "remove_event_handler"):
-                self._renderer.remove_event_handler(self._callback_ref, *self._observed)
+                self._renderer.remove_event_handler(
+                    self._callback_ref, *self._observed
+                )
         except Exception:
             pass  # best-effort cleanup
         self._renderer = None
@@ -346,7 +383,13 @@ def load(self, filepath: str) -> None:
     # ------------------------------------------------------------------
 
     def _on_event(self, event: Any) -> None:
-        """Observer callback — called for each registered event."""
+        """Observer callback — called for each registered event.
+
+        Parameters
+        ----------
+        event : Any
+            A rendercanvas event dict or event object.
+        """
         self._events.append(RecordedEvent.from_rendercanvas_event(event))
 
     @staticmethod
@@ -355,12 +398,12 @@ def _resolve_renderer(show_manager: Any) -> Any:
 
         Parameters
         ----------
-        show_manager :
+        show_manager : Any
             Any object exposing a ``renderer`` attribute.
 
         Returns
         -------
-        renderer
+        Any
             The renderer / EventEmitter instance.
 
         Raises
@@ -380,17 +423,23 @@ def _resolve_renderer(show_manager: Any) -> Any:
 # EventCounter
 # ---------------------------------------------------------------------------
 
+
 class EventCounter(EventRecorder):
     """Records events *and* maintains per-type counts.
 
     Useful when a test only needs to assert how many times a certain event
     type fired, without replaying the whole interaction.
 
+    Parameters
+    ----------
+    **kwargs : Any
+        Keyword arguments forwarded to :class:`EventRecorder`.
+
     Examples
     --------
     >>> counter = EventCounter()
     >>> counter.attach(show_manager)
-    >>> # … run test interaction …
+    >>> # ... run test interaction ...
     >>> counter.detach()
     >>> assert counter.get_count("pointer_down") == 3
     >>> assert counter.total() == 10
@@ -410,16 +459,33 @@ def get_count(self, event_type: str) -> int:
         Parameters
         ----------
         event_type : str
-            rendercanvas event type string, e.g. ``"pointer_down"``.
+            Rendercanvas event type string, e.g. ``"pointer_down"``.
+
+        Returns
+        -------
+        int
+            Number of times the event type was observed.
         """
         return self._counts.get(event_type, 0)
 
     def total(self) -> int:
-        """Total number of events captured across all types."""
+        """Total number of events captured across all types.
+
+        Returns
+        -------
+        int
+            Sum of all event counts.
+        """
         return sum(self._counts.values())
 
     def counts(self) -> Dict[str, int]:
-        """Copy of the full ``{event_type: count}`` mapping."""
+        """Copy of the full ``{event_type: count}`` mapping.
+
+        Returns
+        -------
+        dict
+            Copy of the internal counts dict.
+        """
         return dict(self._counts)
 
     def clear(self) -> None:
@@ -432,9 +498,21 @@ def clear(self) -> None:
     # ------------------------------------------------------------------
 
     def _on_event(self, event: Any) -> None:
-        et = event.get("event_type", "unknown") if isinstance(event, dict) else (
-            getattr(event, "event_type", None) or getattr(event, "type", "unknown")
-        )
+        """Observer callback that also increments per-type counts.
+
+        Parameters
+        ----------
+        event : Any
+            A rendercanvas event dict or event object.
+        """
+        if isinstance(event, dict):
+            et: str = event.get("event_type", "unknown") or "unknown"
+        else:
+            et = (
+                getattr(event, "event_type", None)
+                or getattr(event, "type", "unknown")
+                or "unknown"
+            )
         self._counts[et] = self._counts.get(et, 0) + 1
         super()._on_event(event)
 
@@ -443,6 +521,7 @@ def _on_event(self, event: Any) -> None:
 # EventPlayer
 # ---------------------------------------------------------------------------
 
+
 class EventPlayer:
     """Replays a sequence of :class:`RecordedEvent` objects into a ShowManager.
 
@@ -452,14 +531,14 @@ class EventPlayer:
     Parameters
     ----------
     recorder : EventRecorder, optional
-        Source of events to replay.  Pass ``None`` and call :meth:`load`
+        Source of events to replay. Pass ``None`` and call :meth:`load`
         before :meth:`play`.
     speed_factor : float
         Multiplier applied to inter-event delays.
-        ``1.0`` → real-time; ``0.0`` → instant (best for unit tests).
+        ``1.0`` -> real-time; ``0.0`` -> instant (best for unit tests).
     on_event : callable, optional
         Hook called with ``(RecordedEvent, index)`` *before* each event is
-        injected.  Use for inline assertions during replay.
+        injected. Use for inline assertions during replay.
 
     Examples
     --------
@@ -499,7 +578,7 @@ def play(self, show_manager: Any) -> None:
 
         Parameters
         ----------
-        show_manager :
+        show_manager : Any
             A FURY v2 ShowManager whose window has been initialised.
 
         Raises
@@ -520,11 +599,13 @@ def play(self, show_manager: Any) -> None:
 
         # Dispatch priority:
         # 1. renderer.emit — synchronous dict-based (works in tests with mocks)
-        # 2. show_manager.window._events.emit — raw EventEmitter on real FURY renderer
-        # 3. renderer.dispatch_event — last resort (expects Event object, not dict)
+        # 2. show_manager.window._events.emit — raw EventEmitter on real FURY
+        # 3. renderer.dispatch_event — last resort
         if hasattr(renderer, "emit"):
             _dispatch = renderer.emit
-        elif hasattr(show_manager, "window") and hasattr(show_manager.window, "_events"):
+        elif hasattr(show_manager, "window") and hasattr(
+            show_manager.window, "_events"
+        ):
             _dispatch = show_manager.window._events.emit
         elif hasattr(renderer, "dispatch_event"):
             _dispatch = renderer.dispatch_event