Method add_handler

py/private/_script_handlers.py:451–485

Register a handler and subscribe to ``log.entryAdded`` if needed. Args: callback: User callback invoked with the shaped payload. category: ``console`` or ``error``. legacy: When ``True`` the callback receives the generated ``ConsoleLogEntr

(self, callback: Callable, category: str, legacy: bool = False)

        self._categories: dict[int, str] = {}

    def add_handler(self, callback: Callable, category: str, legacy: bool = False) -> int:
        """Register a handler and subscribe to ``log.entryAdded`` if needed.

        Args:
            callback: User callback invoked with the shaped payload.
            category: ``console`` or ``error``.
            legacy: When ``True`` the callback receives the generated
                ``ConsoleLogEntry`` / ``JavascriptLogEntry`` dataclasses;
                otherwise it receives :class:`ConsoleMessage` /
                :class:`ScriptError`.
        """
        entry_type = self._CATEGORY_ENTRY_TYPES[category]

        def _dispatch(params: Any) -> None:
            if not isinstance(params, dict) or params.get("type") != entry_type:
                return
            if legacy:
                payload = _legacy_log_entry(params)
            elif category == self.CONSOLE:
                payload = console_message_from_log_entry(params)
            else:
                payload = script_error_from_log_entry(params)
            callback(payload)

        conn = self._script._conn
        with self._lock:
            callback_id = conn.add_callback(_EventRef(self.EVENT), _dispatch)
            if not self._categories:
                try:
                    self._subscription_id = _subscribe_to_event(conn, self.EVENT)
                except Exception:
                    conn.remove_callback(_EventRef(self.EVENT), callback_id)
                    raise
            self._categories[callback_id] = category
        return callback_id

    def remove_handler(self, callback_id: int) -> None:
        """Remove a handler; drops the session subscription with the last one."""