pywry¶

Main PyWry application class and top-level functions.

PyWry Class¶

pywry.app.PyWry ¶

PyWry(mode: WindowMode = NEW_WINDOW, theme: ThemeMode = DARK, title: str = 'PyWry', width: int = 800, height: int = 600, settings: PyWrySettings | None = None, hot_reload: bool = False)

Bases: GridStateMixin, PlotlyStateMixin, ToolbarStateMixin

Main PyWry application for displaying content in native windows.

Supports three window modes: - NEW_WINDOW: Creates a new window for each show() call - SINGLE_WINDOW: Reuses one window, replaces content - MULTI_WINDOW: Multiple independent windows

Examples:

>>> pywry = PyWry(mode=WindowMode.SINGLE_WINDOW)
>>> pywry.show("<h1>Hello World</h1>")

Initialize PyWry.

PARAMETER	DESCRIPTION
`mode`	Window mode to use. TYPE: `WindowMode` DEFAULT: `NEW_WINDOW`
`theme`	Default theme mode. TYPE: `ThemeMode` DEFAULT: `DARK`
`title`	Default window title. TYPE: `str` DEFAULT: `'PyWry'`
`width`	Default window width. TYPE: `int` DEFAULT: `800`
`height`	Default window height. TYPE: `int` DEFAULT: `600`
`settings`	Configuration settings. If None, loads from env/files. TYPE: `PyWrySettings or None` DEFAULT: `None`
`hot_reload`	Enable hot reload for CSS/JS files. TYPE: `bool` DEFAULT: `False`

Attributes¶

settings `property` ¶

settings: PyWrySettings

Get the current settings.

theme `property` `writable` ¶

theme: ThemeMode

Get the current theme mode.

is_authenticated `property` ¶

is_authenticated: bool

Check if the app has a successful authentication result.

default_config `property` ¶

default_config: WindowConfig

Return the mutable default WindowConfig.

Callers may set builder-level fields directly::

app.default_config.resizable = False
app.default_config.transparent = True

Functions¶

login ¶

login(provider: Any | None = None, **kwargs: Any) -> Any

Authenticate via OAuth2.

In native mode, opens a dedicated auth window pointing at the provider's authorize URL. Blocks until authentication completes.

In deploy mode, returns the login URL for the frontend.

PARAMETER	DESCRIPTION
`provider`	Override the default provider from settings. TYPE: `OAuthProvider` DEFAULT: `None`
`**kwargs`	Additional keyword arguments passed to `AuthFlowManager.run_native()`. TYPE: `Any` DEFAULT: `{}`

RETURNS	DESCRIPTION
`AuthFlowResult`	The result of the authentication flow.

RAISES	DESCRIPTION
`AuthenticationError`	If authentication fails.

logout ¶

logout() -> None

Log out and clear authentication state.

Clears stored tokens and cancels any background refresh.

set_initialization_script ¶

set_initialization_script(js: str) -> None

Set the default initialization_script for new windows.

This JavaScript is injected by WebviewWindowBuilder before the page loads and persists across navigations. Individual show() calls can override this via the initialization_script keyword argument.

PARAMETER	DESCRIPTION
`js`	JavaScript source code to inject. TYPE: `str`

create_menu ¶

create_menu(menu_id: str, items: list[Any] | None = None) -> Any

Create a native menu.

PARAMETER	DESCRIPTION
`menu_id`	Unique menu identifier. TYPE: `str`
`items`	Menu items. TYPE: `list of MenuItemKindConfig` DEFAULT: `None`

RETURNS	DESCRIPTION
`MenuProxy`	Proxy for the created menu.

create_tray ¶

create_tray(tray_id: str, tooltip: str | None = None, title: str | None = None, icon: bytes | None = None, icon_width: int = 32, icon_height: int = 32, menu: Any = None, menu_on_left_click: bool = True) -> Any

Create a system tray icon.

PARAMETER	DESCRIPTION
`tray_id`	Unique tray icon identifier. TYPE: `str`
`tooltip`	Hover tooltip text. TYPE: `str or None` DEFAULT: `None`
`title`	Tray title (macOS menu bar text). TYPE: `str or None` DEFAULT: `None`
`icon`	RGBA icon bytes. TYPE: `bytes or None` DEFAULT: `None`
`icon_width`	Icon width. TYPE: `int` DEFAULT: `32`
`icon_height`	Icon height. TYPE: `int` DEFAULT: `32`
`menu`	Menu to attach. TYPE: `MenuConfig or None` DEFAULT: `None`
`menu_on_left_click`	Whether left click opens the menu. TYPE: `bool` DEFAULT: `True`

RETURNS	DESCRIPTION
`TrayProxy`	Proxy for the created tray icon.

remove_tray ¶

remove_tray(tray_id: str) -> None

Remove a system tray icon.

Works for trays created via :meth:create_tray and those created directly via TrayProxy.from_config() or TrayProxy.create().

PARAMETER	DESCRIPTION
`tray_id`	The tray icon identifier. TYPE: `str`

show ¶

show(content: str | HtmlContent, title: str | None = None, width: int | str | None = None, height: int | None = None, callbacks: dict[str, CallbackFunc] | None = None, include_plotly: bool = False, include_aggrid: bool = False, aggrid_theme: Literal['quartz', 'alpine', 'balham', 'material'] = 'alpine', label: str | None = None, watch: bool | None = None, toolbars: list[dict[str, Any] | Toolbar] | None = None, modals: list[dict[str, Any] | Modal] | None = None, initialization_script: str | None = None, menu: MenuConfig | None = None) -> NativeWindowHandle | BaseWidget

Show content in a window.

In a notebook environment (Jupyter, IPython, Colab, etc.), this will automatically render content inline via IFrame instead of opening a native window.

PARAMETER	DESCRIPTION
`content`	HTML content or HtmlContent object. TYPE: `str or HtmlContent`
`title`	Window title (overrides default). TYPE: `str or None` DEFAULT: `None`
`width`	Window width - int for pixels, str for CSS value (e.g., "60%", "500px"). TYPE: `int or str or None` DEFAULT: `None`
`height`	Window height (overrides default). TYPE: `int or None` DEFAULT: `None`
`callbacks`	Event callbacks (event_type -> handler). TYPE: `dict[str, CallbackFunc] or None` DEFAULT: `None`
`include_plotly`	Include Plotly.js library. TYPE: `bool` DEFAULT: `False`
`include_aggrid`	Include AG Grid library. TYPE: `bool` DEFAULT: `False`
`aggrid_theme`	AG Grid theme name (default: 'alpine'). TYPE: `('quartz', 'alpine', 'balham', 'material')` DEFAULT: `'quartz'`
`label`	Window label (for MULTI_WINDOW mode updates). TYPE: `str or None` DEFAULT: `None`
`watch`	Enable hot reload for CSS/JS files (overrides HtmlContent.watch). TYPE: `bool or None` DEFAULT: `None`
`toolbars`	List of toolbar configs. Each toolbar has 'position' and 'items' keys. TYPE: `list[dict]` DEFAULT: `None`
`modals`	List of modal configs. Each modal has 'title' and 'items' keys. TYPE: `list[dict]` DEFAULT: `None`
`initialization_script`	JavaScript to inject via `WebviewWindowBuilder` before the page loads. Persists across navigations (unlike per-content `HtmlContent.init_script`). Overrides the default set via `set_initialization_script()` for this call only. TYPE: `str or None` DEFAULT: `None`
`menu`	Native menu bar configuration. Item handlers are automatically registered before the window is created so menus work from the moment the window appears. Pass a :class:`MenuConfig` with handler-bearing items (e.g. `MenuItemConfig(id="save", text="Save", handler=on_save)`). TYPE: `MenuConfig or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`NativeWindowHandle or PyWryWidget or InlineWidget`	A NativeWindowHandle (native window) or widget (notebook). All implement the BaseWidget protocol.

show_plotly ¶

show_plotly(figure: Any, title: str | None = None, width: int | None = None, height: int | None = None, callbacks: dict[str, CallbackFunc] | None = None, label: str | None = None, inline_css: str | None = None, on_click: Any = None, on_hover: Any = None, on_select: Any = None, toolbars: list[dict[str, Any] | Toolbar] | None = None, modals: list[dict[str, Any] | Modal] | None = None, config: Any = None) -> NativeWindowHandle | BaseWidget

Show a Plotly figure.

In a notebook environment, this will automatically render the figure inline via IFrame with full interactivity.

PARAMETER	DESCRIPTION
`figure`	Plotly figure object (must have to_html method) or dictionary spec. TYPE: `Any`
`title`	Window title. TYPE: `str or None` DEFAULT: `None`
`width`	Window/IFrame width (overrides default). TYPE: `int or None` DEFAULT: `None`
`height`	Window/IFrame height (overrides default). TYPE: `int or None` DEFAULT: `None`
`callbacks`	Event callbacks. TYPE: `dict[str, CallbackFunc] or None` DEFAULT: `None`
`label`	Window label (for MULTI_WINDOW mode). TYPE: `str or None` DEFAULT: `None`
`inline_css`	Custom CSS to inject (e.g., override window background). TYPE: `str or None` DEFAULT: `None`
`on_click`	Click callback for notebook mode. TYPE: `Callable or None` DEFAULT: `None`
`on_hover`	Hover callback for notebook mode. TYPE: `Callable or None` DEFAULT: `None`
`on_select`	Selection callback for notebook mode. TYPE: `Callable or None` DEFAULT: `None`
`toolbars`	List of toolbar configs. Each toolbar has 'position' and 'items' keys. TYPE: `list[dict]` DEFAULT: `None`
`modals`	List of modal configs. Each modal has 'title' and 'items' keys. TYPE: `list[dict]` DEFAULT: `None`
`config`	Plotly.js configuration (modebar, responsive, etc.). TYPE: `PlotlyConfig or dict` DEFAULT: `None`

RETURNS	DESCRIPTION
`NativeWindowHandle or BaseWidget`	A NativeWindowHandle (native window) or widget (notebook). All implement the BaseWidget protocol.

show_dataframe ¶

show_dataframe(data: Any, title: str | None = None, width: int | None = None, height: int | None = None, callbacks: dict[str, CallbackFunc] | None = None, label: str | None = None, column_defs: list[dict[str, Any]] | None = None, aggrid_theme: Literal['quartz', 'alpine', 'balham', 'material'] = 'alpine', grid_options: dict[str, Any] | None = None, toolbars: list[dict[str, Any] | Toolbar] | None = None, modals: list[dict[str, Any] | Modal] | None = None, inline_css: str | None = None, on_cell_click: Any = None, on_row_selected: Any = None, server_side: bool = False) -> NativeWindowHandle | BaseWidget

Show a DataFrame in an AG Grid table.

In a notebook environment, this will automatically render the table inline via IFrame with full interactivity.

PARAMETER	DESCRIPTION
`data`	DataFrame or list of dicts to display. TYPE: `Any`
`title`	Window title. TYPE: `str or None` DEFAULT: `None`
`width`	Window/IFrame width (overrides default). TYPE: `int or None` DEFAULT: `None`
`height`	Window/IFrame height (overrides default). TYPE: `int or None` DEFAULT: `None`
`callbacks`	Event callbacks. TYPE: `dict[str, CallbackFunc] or None` DEFAULT: `None`
`label`	Window label (for MULTI_WINDOW mode). TYPE: `str or None` DEFAULT: `None`
`column_defs`	AG Grid column definitions. TYPE: `list[dict[str, Any]] or None` DEFAULT: `None`
`aggrid_theme`	AG Grid theme. TYPE: `('quartz', 'alpine', 'balham', 'material')` DEFAULT: `'quartz'`
`grid_options`	Custom AG Grid options to merge with defaults. TYPE: `dict[str, Any] or None` DEFAULT: `None`
`toolbars`	List of toolbar configs. Each toolbar has 'position' and 'items' keys. TYPE: `list[dict]` DEFAULT: `None`
`inline_css`	Custom CSS to inject (e.g., override window background). TYPE: `str or None` DEFAULT: `None`
`on_cell_click`	Cell click callback for notebook mode. TYPE: `Callable or None` DEFAULT: `None`
`on_row_selected`	Row selection callback for notebook mode. TYPE: `Callable or None` DEFAULT: `None`
`server_side`	Enable server-side mode where data stays in Python memory. Useful for very large datasets (>100K rows) where you want to filter/sort the full data. Data is fetched via IPC on demand. Default is False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`NativeWindowHandle or BaseWidget`	A NativeWindowHandle (native window) or widget (notebook). All implement the BaseWidget protocol.

emit ¶

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

Emit an event to the JavaScript side.

PARAMETER	DESCRIPTION
`event_type`	Event name. TYPE: `str`
`data`	Event data. TYPE: `dict`
`label`	Window label. If None, targets all active windows. TYPE: `str` DEFAULT: `None`

alert ¶

alert(message: str, alert_type: Literal['info', 'success', 'warning', 'error', 'confirm'] = 'info', title: str | None = None, duration: int | None = None, callback_event: str | None = None, position: Literal['top-right', 'bottom-right', 'bottom-left', 'top-left'] = 'top-right', label: str | None = None) -> None

Show a toast notification.

PARAMETER	DESCRIPTION
`message`	The message to display. TYPE: `str`
`alert_type`	Alert type: 'info', 'success', 'warning', 'error', or 'confirm'. TYPE: `str` DEFAULT: `'info'`
`title`	Optional title for the toast. TYPE: `str` DEFAULT: `None`
`duration`	Auto-dismiss duration in ms. Defaults based on type. TYPE: `int` DEFAULT: `None`
`callback_event`	Event name to emit when confirm dialog is answered. TYPE: `str` DEFAULT: `None`
`position`	Toast position: 'top-right', 'top-left', 'bottom-right', 'bottom-left'. TYPE: `str` DEFAULT: `'top-right'`
`label`	Window label. If None, targets all active windows. TYPE: `str` DEFAULT: `None`

on ¶

on(event_type: str, handler: CallbackFunc, label: str | None = None, widget_id: str | None = None) -> bool

Register an event handler.

PARAMETER	DESCRIPTION
`event_type`	Event type (namespace:event-name or * for wildcard). TYPE: `str`
`handler`	Callback function. TYPE: `CallbackFunc`
`label`	Window label. If None, registers on all active windows. TYPE: `str` DEFAULT: `None`
`widget_id`	Widget ID to target specific component events. TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if registered successfully.

command ¶

command(name: str | None = None) -> Any

Register a custom IPC command callable from JavaScript.

The decorated function becomes available to the front-end via window.__TAURI__.pytauri.pyInvoke('name', body).

Must be called before show() / start() so the command is registered in the subprocess before the Tauri app builder runs.

PARAMETER	DESCRIPTION
`name`	Command name exposed to JS. Defaults to the function's `__name__`. TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`callable`	Decorator that registers the handler.

RAISES	DESCRIPTION
`TypeError`	If the handler is not callable.
`RuntimeError`	If the app is in a non-native mode (BROWSER, NOTEBOOK) where `pyInvoke` is not available, or if the subprocess has already started.

Examples:

>>> app = PyWry()
>>>
>>> @app.command()
... def get_user(data: dict) -> dict:
...     return {"name": "Alice", "id": 42}
>>>
>>> @app.command("fetch_data")
... async def _fetch(data: dict) -> dict:
...     rows = await load_from_db(data["query"])
...     return {"rows": rows}

on_grid ¶

on_grid(event_type: str, handler: CallbackFunc, label: str | None = None, grid_id: str = '*') -> bool

Register an event handler for grid events.

Convenience method that filters events to only AG Grid widgets.

PARAMETER	DESCRIPTION
`event_type`	Event type (e.g., "grid:cell-click", "cell_click"). TYPE: `str`
`handler`	Callback function. TYPE: `CallbackFunc`
`label`	Window label. If None, registers on all active windows. TYPE: `str` DEFAULT: `None`
`grid_id`	Grid ID to target specific grid instance (default "" for all). TYPE:* `str` DEFAULT: `'*'`

RETURNS	DESCRIPTION
`bool`	True if registered successfully.

on_chart ¶

on_chart(event_type: str, handler: CallbackFunc, label: str | None = None, chart_id: str = '*') -> bool

Register an event handler for chart (Plotly) events.

Convenience method that filters events to only Plotly chart widgets.

PARAMETER	DESCRIPTION
`event_type`	Event type (e.g., "plotly:click", "plotly:hover"). TYPE: `str`
`handler`	Callback function. TYPE: `CallbackFunc`
`label`	Window label. If None, registers on all active windows. TYPE: `str` DEFAULT: `None`
`chart_id`	Chart ID to target specific chart instance (default "" for all). TYPE:* `str` DEFAULT: `'*'`

RETURNS	DESCRIPTION
`bool`	True if registered successfully.

on_toolbar ¶

on_toolbar(event_type: str, handler: CallbackFunc, label: str | None = None, toolbar_id: str = '*') -> bool

Register an event handler for toolbar events.

Convenience method that filters events to only toolbar widgets.

PARAMETER	DESCRIPTION
`event_type`	Event type (e.g., "toolbar:change", custom button events). TYPE: `str`
`handler`	Callback function. TYPE: `CallbackFunc`
`label`	Window label. If None, registers on all active windows. TYPE: `str` DEFAULT: `None`
`toolbar_id`	Toolbar ID to target specific toolbar (default "" for all). TYPE:* `str` DEFAULT: `'*'`

RETURNS	DESCRIPTION
`bool`	True if registered successfully.

on_html ¶

on_html(event_type: str, handler: CallbackFunc, label: str | None = None, element_id: str = '*') -> bool

Register an event handler for HTML element events.

Convenience method that filters events to HTML content.

PARAMETER	DESCRIPTION
`event_type`	Event type (e.g., custom events from HTML elements). TYPE: `str`
`handler`	Callback function. TYPE: `CallbackFunc`
`label`	Window label. If None, registers on all active windows. TYPE: `str` DEFAULT: `None`
`element_id`	HTML element ID to target specific element (default "" for all). TYPE:* `str` DEFAULT: `'*'`

RETURNS	DESCRIPTION
`bool`	True if registered successfully.

on_window ¶

on_window(event_type: str, handler: CallbackFunc, label: str | None = None) -> bool

Register an event handler for window-level events.

Convenience method that filters events to window lifecycle events.

PARAMETER	DESCRIPTION
`event_type`	Event type (e.g., "window:close", "window:resize"). TYPE: `str`
`handler`	Callback function. TYPE: `CallbackFunc`
`label`	Window label. If None, registers on all active windows. TYPE: `str` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if registered successfully.

send_event ¶

send_event(event_type: str, data: Any, label: str | None = None) -> bool

Send an event to window(s).

PARAMETER	DESCRIPTION
`event_type`	Event type (namespace:event-name). TYPE: `str`
`data`	Event data. TYPE: `Any`
`label`	Specific window label (None = all windows). TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if event was sent to at least one window.

update_content ¶

update_content(html: str, label: str | None = None) -> bool

Update window content.

PARAMETER	DESCRIPTION
`html`	New HTML content. TYPE: `str`
`label`	Window label (required for NEW_WINDOW/MULTI_WINDOW). TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if updated successfully.

eval_js ¶

eval_js(script: str, label: str | None = None) -> bool

Evaluate JavaScript in a window without replacing content.

This is useful for DOM queries and dynamic updates that should not replace the window content.

PARAMETER	DESCRIPTION
`script`	JavaScript code to execute. TYPE: `str`
`label`	Window label (None = main window in SINGLE_WINDOW mode). TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if command was sent.

show_window ¶

show_window(label: str) -> bool

Show a hidden window.

PARAMETER	DESCRIPTION
`label`	Window label to show. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if window was shown.

hide_window ¶

hide_window(label: str) -> bool

Hide a window (keeps it alive, just not visible).

PARAMETER	DESCRIPTION
`label`	Window label to hide. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if window was hidden.

close ¶

close(label: str | None = None) -> bool

Close window(s).

PARAMETER	DESCRIPTION
`label`	Window label to close (None = close all). TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if any window was closed.

get_labels ¶

get_labels() -> list[str]

Get all active window labels.

RETURNS	DESCRIPTION
`list of str`	List of window labels.

is_open ¶

is_open(label: str | None = None) -> bool

Check if window(s) are open.

PARAMETER	DESCRIPTION
`label`	Specific window to check (None = any window). TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if window(s) are open.

refresh ¶

refresh(label: str | None = None) -> bool

Refresh window content.

Triggers a full page refresh while preserving scroll position.

PARAMETER	DESCRIPTION
`label`	Specific window to refresh (None = all windows). TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if at least one window was refreshed.

refresh_css ¶

refresh_css(label: str | None = None) -> bool

Hot-reload CSS files for window(s).

Re-injects CSS files without page refresh.

PARAMETER	DESCRIPTION
`label`	Specific window to refresh CSS (None = all windows). TYPE: `str or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if at least one window's CSS was refreshed.

enable_hot_reload ¶

enable_hot_reload() -> None

Enable hot reload if not already enabled.

disable_hot_reload ¶

disable_hot_reload() -> None

Disable hot reload and stop file watching.

get_icon ¶

get_icon() -> bytes

Get the OpenBB icon.

RETURNS	DESCRIPTION
`bytes`	Icon bytes.

get_lifecycle ¶

get_lifecycle() -> WindowLifecycle

Get the window lifecycle manager.

RETURNS	DESCRIPTION
`WindowLifecycle`	WindowLifecycle instance.

destroy ¶

destroy() -> None

Destroy all resources and close all windows.

block ¶

block(label: str | None = None) -> None

Block until window(s) are closed or KeyboardInterrupt.

This is the recommended way to keep your script running while windows are open. Works for all modes:

Native modes (NEW_WINDOW, SINGLE_WINDOW, MULTI_WINDOW): Waits for windows to close via the Tauri event loop.
BROWSER mode: Delegates to pywry.inline.block() to wait for browser tabs to disconnect.

PARAMETER	DESCRIPTION
`label`	Specific window label to wait for. If None, waits for all windows. TYPE: `str or None` DEFAULT: `None`

Examples:

>>> app = PyWry()
>>> label = app.show("<h1>Hello</h1>")
>>> app.block()  # Wait until all windows are closed

>>> # Or wait for a specific window
>>> app.block(label)  # Wait until this specific window is closed

request_toolbar_state ¶

request_toolbar_state(toolbar_id: str | None = None) -> None

Request values of all toolbar inputs.

set_toolbar_value ¶

set_toolbar_value(component_id: str, value: Any = _UNSET, toolbar_id: str | None = None, **attrs: Any) -> None

Set a toolbar component's value and/or attributes.

PARAMETER	DESCRIPTION
`component_id`	The component_id of the toolbar item to update. TYPE: `str`
`value`	The new value for the component. TYPE: `Any` DEFAULT: `_UNSET`
`toolbar_id`	The toolbar ID (if applicable). TYPE: `str` DEFAULT: `None`
`**attrs`	Additional attributes to set on the component: - label/text: Update text content - disabled: Enable/disable the component - variant: Button variant (primary, secondary, danger, etc.) - tooltip/description: Update tooltip text - options: Update dropdown/select options - style: Inline styles (str or dict) - className/class: Add/remove CSS classes - placeholder, min, max, step: Input constraints TYPE: `Any` DEFAULT: `{}`

set_toolbar_values ¶

set_toolbar_values(values: dict[str, Any], toolbar_id: str | None = None) -> None

Set multiple toolbar input values at once.

update_figure ¶

update_figure(figure: Any, chart_id: str | None = None, animate: bool = False, config: dict[str, Any] | None = None) -> None

Update the entire chart figure (data and layout).

update_layout ¶

update_layout(layout: dict[str, Any], chart_id: str | None = None) -> None

Update specific layout properties (Plotly.relayout).

update_traces ¶

update_traces(patch: dict[str, Any], indices: list[int] | None = None, chart_id: str | None = None) -> None

Update specific trace properties (Plotly.restyle).

request_plotly_state ¶

request_plotly_state(chart_id: str | None = None) -> None

Request current chart state (viewport, zoom, selections).

reset_zoom ¶

reset_zoom(chart_id: str | None = None) -> None

Reset the chart zoom/pan to default.

set_zoom ¶

set_zoom(xaxis_range: tuple[Any, Any] | None = None, yaxis_range: tuple[Any, Any] | None = None, chart_id: str | None = None) -> None

Set specific zoom ranges for axes.

set_trace_visibility ¶

set_trace_visibility(visible: bool | str | list[bool | str], indices: list[int] | None = None, chart_id: str | None = None) -> None

Set visibility for specific traces.

request_grid_state ¶

request_grid_state(context: dict[str, Any] | None = None, grid_id: str | None = None) -> None

Request the current state of the grid (sort, filter, columns, etc.).

The frontend will respond with a 'grid:state-response' event.

PARAMETER	DESCRIPTION
`context`	Context data to include in the response. This is echoed back unchanged in the state_response event, useful for tracking which request triggered the response (e.g., view switching). TYPE: `dict` DEFAULT: `None`
`grid_id`	The ID of the grid to query. TYPE: `str` DEFAULT: `None`

restore_state ¶

restore_state(state: dict[str, Any], grid_id: str | None = None) -> None

Restore the grid state from a previous state object.

reset_state ¶

reset_state(grid_id: str | None = None, hard: bool = False) -> None

Reset the grid state to default values.

PARAMETER	DESCRIPTION
`grid_id`	The ID of the grid to reset. TYPE: `str \| None` DEFAULT: `None`
`hard`	If True, completely destroys and recreates the grid instance. If False (default), only resets state columns/filters/sort. TYPE: `bool` DEFAULT: `False`

update_cell ¶

update_cell(row_id: str | int, col_id: str, value: Any, grid_id: str | None = None) -> None

Update a single cell value.

update_data ¶

update_data(data: list[dict[str, Any]], grid_id: str | None = None, strategy: str = 'set') -> None

Update grid data rows.

PARAMETER	DESCRIPTION
`data`	List of row data dictionaries. TYPE: `list[dict[str, Any]]`
`grid_id`	The ID of the grid. TYPE: `str \| None` DEFAULT: `None`
`strategy`	Update strategy ('set', 'append', 'update'). 'set' replaces all data. TYPE: `str` DEFAULT: `'set'`

update_columns ¶

update_columns(column_defs: list[dict[str, Any]], grid_id: str | None = None) -> None

Update column definitions.

update_grid ¶

update_grid(data: list[dict[str, Any]] | Any | None = None, columns: list[dict[str, Any]] | None = None, restore_state: dict[str, Any] | None = None, grid_id: str | None = None) -> None

Update the grid with new data, columns, and/or restore saved state.

This is the primary method for switching views or making bulk updates. It combines data, column, and state updates into a single operation to minimize UI flicker.

PARAMETER	DESCRIPTION
`data`	New row data. If a DataFrame, it will be converted to records. TYPE: `list[dict] \| DataFrame` DEFAULT: `None`
`columns`	New column definitions. TYPE: `list[dict]` DEFAULT: `None`
`restore_state`	Previously saved grid state to restore (from grid:state-response). Contains columnState, filterModel, sortModel. TYPE: `dict` DEFAULT: `None`
`grid_id`	The ID of the grid to update. TYPE: `str` DEFAULT: `None`

Inline Rendering Functions¶

These functions provide quick one-liner display for Plotly figures and DataFrames.

pywry.inline.show_plotly ¶

show_plotly(figure: Figure, callbacks: dict[str, Callable[..., Any]] | None = None, title: str = 'PyWry', width: str = '100%', height: int = 500, theme: ThemeLiteral | None = None, port: int | None = None, config: dict[str, Any] | PlotlyConfig | None = None, toolbars: list[dict[str, Any] | Toolbar] | None = None, modals: list[dict[str, Any] | Modal] | None = None, open_browser: bool = False) -> BaseWidget

Show a Plotly figure inline in a notebook with automatic event handling.

This function automatically wires up Plotly events (click, hover, selected) and uses the best available widget backend (anywidget or InlineWidget).

PARAMETER	DESCRIPTION
`figure`	Plotly figure to display. TYPE: `Figure`
`callbacks`	Event callbacks. Keys are event names (e.g., 'plotly_click', 'plotly_hover', 'plotly_selected'), values are handler functions receiving (data, event_type, label). The function signature should be: callback(data: dict, event_type: str, label: str). TYPE: `dict[str, Callable]` DEFAULT: `None`
`title`	Page title. TYPE: `str` DEFAULT: `'PyWry'`
`width`	Widget width (CSS format). TYPE: `str` DEFAULT: `'100%'`
`height`	Widget height in pixels. TYPE: `int` DEFAULT: `500`
`theme`	Color theme. TYPE: `'dark' or 'light'` DEFAULT: `None`
`port`	Server port (only used if InlineWidget fallback is needed). TYPE: `int` DEFAULT: `None`
`config`	Plotly config dictionary (e.g., {'modeBarButtonsToAdd': [...]}). TYPE: `dict` DEFAULT: `None`
`toolbars`	List of toolbar configurations, each with: - position: "top", "bottom", "left", "right", "inside" - items: list of item configs TYPE: `list[dict]` DEFAULT: `None`
`modals`	List of modal configurations. TYPE: `list[dict]` DEFAULT: `None`
`open_browser`	If True, open in system browser instead of displaying IFrame in notebook. Used by BROWSER mode. Default: False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`BaseWidget`	Widget implementing BaseWidget protocol (PyWryPlotlyWidget or InlineWidget).

Examples:

>>> import plotly.graph_objects as go
>>> fig = go.Figure(data=go.Scatter(x=[1, 2, 3], y=[4, 5, 6]))
>>> widget = show_plotly(
...     fig,
...     callbacks={
...         "plotly_click": lambda d, t, l: print(f"Clicked: {d['points']}"),
...         "plotly_hover": lambda d, t, l: print(f"Hover: {d['points']}"),
...     },
... )

pywry.inline.show_dataframe ¶

show_dataframe(df: Any, callbacks: dict[str, Callable[..., Any]] | None = None, title: str = 'PyWry', width: str = '100%', height: int = 500, theme: ThemeLiteral | None = None, aggrid_theme: Literal['quartz', 'alpine', 'balham', 'material'] = 'alpine', header_html: str = '', grid_options: dict[str, Any] | None = None, toolbars: list[Any] | None = None, modals: list[Any] | None = None, port: int | None = None, widget_id: str | None = None, column_defs: list[Any] | None = None, row_selection: Any | bool = False, enable_cell_span: bool | None = None, pagination: bool | None = None, pagination_page_size: int = 100, open_browser: bool = False) -> BaseWidget

Show a DataFrame (or dict/list) inline in a notebook with automatic event handling.

This function automatically wires up AG Grid events (grid:cell-click, grid:row-selected) and uses the best available widget backend (anywidget or InlineWidget).

PARAMETER	DESCRIPTION
`df`	Data to display. Can be pandas DataFrame, list of row dicts, or dict of columns. TYPE: `DataFrame \| list[dict] \| dict[str, list]`
`callbacks`	Event callbacks. TYPE: `dict[str, Callable]` DEFAULT: `None`
`title`	Page title. TYPE: `str` DEFAULT: `'PyWry'`
`width`	Widget width (CSS format). TYPE: `str` DEFAULT: `'100%'`
`height`	Widget height in pixels. TYPE: `int` DEFAULT: `500`
`theme`	Color theme. TYPE: `'dark' or 'light'` DEFAULT: `None`
`aggrid_theme`	AG Grid theme. TYPE: `str` DEFAULT: `'alpine'`
`header_html`	Custom HTML to display above the grid (e.g., buttons). TYPE: `str` DEFAULT: `''`
`grid_options`	Custom AG Grid options. TYPE: `dict` DEFAULT: `None`
`toolbars`	List of toolbars. Each can be a Toolbar model or dict with: - position: "top", "bottom", "left", "right", "inside" - items: list of item configs (Button, Select, etc.) TYPE: `list[Toolbar \| dict]` DEFAULT: `None`
`modals`	List of modal configurations. TYPE: `list[dict]` DEFAULT: `None`
`port`	Server port (only used if InlineWidget fallback is needed). TYPE: `int` DEFAULT: `None`
`widget_id`	Unique ID for the widget. If None, a random UUID is generated. TYPE: `str` DEFAULT: `None`
`column_defs`	Custom column definitions. Can be dicts or ColDef objects. TYPE: `list` DEFAULT: `None`
`row_selection`	Row selection config. True = multiRow with checkboxes. TYPE: `RowSelection \| dict \| bool` DEFAULT: `False`
`enable_cell_span`	Enable row spanning for index columns. None = auto-detect from MultiIndex. TYPE: `bool \| None` DEFAULT: `None`
`pagination`	Enable pagination. None = auto-enable for datasets > 10 rows. TYPE: `bool \| None` DEFAULT: `None`
`pagination_page_size`	Rows per page when pagination is enabled. TYPE: `int` DEFAULT: `100`
`open_browser`	If True, open in system browser instead of displaying IFrame in notebook. Used by BROWSER mode. Default: False. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`BaseWidget`	Widget implementing BaseWidget protocol.

pywry.inline.block ¶

block() -> None

Block until all widgets disconnect or KeyboardInterrupt.

Use this in scripts using BROWSER mode to keep the server alive until all browser tabs are closed.

Examples:

>>> widget = pywry.inline.show("<h1>Hello</h1>")
>>> widget.open_in_browser()
>>> pywry.inline.block()  # Wait until browser tab is closed

App-level convenience methods for native menus and tray icons. See the Native Menus and System Tray guides.

The following methods are on the PyWry class (documented above via autodoc):

create_menu(menu_id, items) → MenuProxy
create_tray(tray_id, ...) → TrayProxy
remove_tray(tray_id) — remove a tracked tray icon
set_initialization_script(js) — set default init script for new windows
default_config property — mutable WindowConfig with builder defaults

Window Lifecycle¶

pywry.window_manager.get_lifecycle ¶

get_lifecycle() -> WindowLifecycle

Get the global window lifecycle manager.

RETURNS	DESCRIPTION
`WindowLifecycle`	The window lifecycle singleton.

pywry¶

PyWry Class¶

pywry.app.PyWry ¶

Attributes¶

settings property ¶

theme property writable ¶

is_authenticated property ¶

default_config property ¶

Functions¶

login ¶

logout ¶

set_initialization_script ¶

create_menu ¶

create_tray ¶

remove_tray ¶

show ¶

show_plotly ¶

show_dataframe ¶

emit ¶

alert ¶

on ¶

command ¶

on_grid ¶

on_chart ¶

on_toolbar ¶

on_html ¶

on_window ¶

send_event ¶

update_content ¶

eval_js ¶

show_window ¶

hide_window ¶

close ¶

get_labels ¶

is_open ¶

refresh ¶

refresh_css ¶

enable_hot_reload ¶

disable_hot_reload ¶

get_icon ¶

get_lifecycle ¶

destroy ¶

block ¶

request_toolbar_state ¶

set_toolbar_value ¶

set_toolbar_values ¶

update_figure ¶

update_layout ¶

update_traces ¶

request_plotly_state ¶

reset_zoom ¶

set_zoom ¶

set_trace_visibility ¶

request_grid_state ¶

restore_state ¶

reset_state ¶

update_cell ¶

update_data ¶

update_columns ¶

update_grid ¶

Inline Rendering Functions¶

pywry.inline.show_plotly ¶

pywry.inline.show_dataframe ¶

pywry.inline.block ¶

Menu & Tray¶

Window Lifecycle¶

pywry.window_manager.get_lifecycle ¶

settings `property` ¶

theme `property` `writable` ¶

is_authenticated `property` ¶

default_config `property` ¶