pywry.widget_protocol

Widget protocol interfaces and native window handle.

---

pywry.widget_protocol.BaseWidget

Bases: Protocol

Protocol that all PyWry widgets must implement.

This enables a unified API across different rendering backends: - InlineWidget: FastAPI server + IFrame (notebook fallback) - PyWryWidget: anywidget with traitlet sync (best notebook performance) - Native windows: Desktop application rendering

Examples:

>>> widget = create_widget(...)  # Returns any BaseWidget implementation
>>> widget.on("click", lambda data, event_type, label: print(data))
>>> widget.emit("update", {"value": 42})
>>> widget.display()

Functions

on

on(event_type: str, callback: Callable[[dict[str, Any], str, str], Any]) -> BaseWidget

Register a callback for events from JavaScript.

Parameters:

Name	Type	Description	Default
event_type	str	Event name (e.g., 'plotly:click', 'toggle', 'grid:cell-click').	required
callback	Callable[[dict, str, str], Any]	Handler function receiving (data, event_type, label). - data: Event payload from JavaScript - event_type: Same as event_type parameter - label: Widget identifier	required

Returns:

Type	Description
BaseWidget	Self for method chaining.

Examples:

>>> widget.on("plotly:click", lambda d, t, l: print(f"Clicked: {d}"))
>>> widget.on("custom-event", my_handler).on("another", other_handler)

emit

emit(event_type: str, data: dict[str, Any]) -> None

Send an event from Python to JavaScript.

Parameters:

Name	Type	Description	Default
event_type	str	Event name that JS listeners can subscribe to.	required
data	dict	JSON-serializable payload to send to JavaScript.	required

Examples:

>>> widget.emit("update_chart", {"x": [1, 2, 3], "y": [4, 5, 6]})
>>> widget.emit("set_theme", {"theme": "dark"})

update

update(html: str) -> None

Update the widget's HTML content.

Parameters:

Name	Type	Description	Default
html	str	New HTML content to render. Should include necessary