pywry.runtime¶

Low-level PyTauri subprocess management and IPC communication.

Process Lifecycle¶

pywry.runtime.is_headless ¶

is_headless() -> bool

Check if headless mode is enabled.

Headless mode creates windows that are fully functional but not visible, allowing full E2E testing in CI environments without a display.

RETURNS	DESCRIPTION
`bool`	True if PYWRY_HEADLESS environment variable is set.

pywry.runtime.start ¶

start() -> bool

Start the pytauri subprocess.

RETURNS	DESCRIPTION
`bool`	True if started successfully.

pywry.runtime.stop ¶

stop() -> None

Stop the pytauri subprocess.

pywry.runtime.is_running ¶

is_running() -> bool

Check if the subprocess is running.

pywry.runtime.wait_ready ¶

wait_ready(timeout: float = 10.0) -> bool

Wait for the subprocess to be ready.

pywry.runtime.get_portal ¶

get_portal() -> BlockingPortal | None

Get the async portal if initialized.

RETURNS	DESCRIPTION
`BlockingPortal or None`	The portal, or None if not yet initialized.

pywry.runtime.get_pywry_dir ¶

get_pywry_dir() -> Path

Get the pywry directory containing the subprocess entry point.

Configuration¶

pywry.runtime.set_on_window_close ¶

set_on_window_close(behavior: str) -> None

Set the global window close behavior.

PARAMETER	DESCRIPTION
`behavior`	Either "hide" (keep window alive) or "close" (destroy window). TYPE: `str`

pywry.runtime.set_window_mode ¶

set_window_mode(mode: str) -> None

Set the window mode.

PARAMETER	DESCRIPTION
`mode`	Either "single", "multi", or "new". TYPE: `str`

pywry.runtime.set_tauri_plugins ¶

set_tauri_plugins(plugins: list[str]) -> None

Set the Tauri plugins to initialise in the subprocess.

Must be called before start().

PARAMETER	DESCRIPTION
`plugins`	Plugin names (e.g. `["dialog", "fs", "notification"]`). TYPE: `list[str]`

pywry.runtime.set_extra_capabilities ¶

set_extra_capabilities(caps: list[str]) -> None

Set additional Tauri capability permission strings.

Must be called before start().

PARAMETER	DESCRIPTION
`caps`	Permission strings (e.g. `["shell:allow-execute"]`). TYPE: `list[str]`

Command IPC¶

pywry.runtime.send_command ¶

send_command(cmd: dict[str, Any]) -> None

Send a command to the subprocess.

pywry.runtime.get_response ¶

get_response(timeout: float = 5.0) -> dict[str, Any] | None

Get a response from the subprocess.

pywry.runtime.send_command_with_response ¶

send_command_with_response(cmd: dict[str, Any], timeout: float = 5.0) -> dict[str, Any] | None

Send a command and wait for a correlated response.

Uses request_id for response correlation, allowing multiple concurrent blocking calls without response mixup.

PARAMETER	DESCRIPTION
`cmd`	Command to send. A request_id will be added automatically. TYPE: `dict[str, Any]`
`timeout`	Maximum time to wait for response. TYPE: `float` DEFAULT: `5.0`

RETURNS	DESCRIPTION
`dict[str, Any] or None`	The response, or None on timeout.

Window Operations¶

pywry.runtime.create_window ¶

create_window(label: str, title: str = 'PyWry', width: int = 800, height: int = 600, **builder_opts: Any) -> bool

Create a window via IPC. Waits for window to be created.

PARAMETER	DESCRIPTION
`label`	Window label (unique identifier). TYPE: `str`
`title`	Window title text. TYPE: `str` DEFAULT: `'PyWry'`
`width`	Window width in pixels. TYPE: `int` DEFAULT: `800`
`height`	Window height in pixels. TYPE: `int` DEFAULT: `600`
`**builder_opts`	Additional keyword arguments forwarded to `WebviewWindowBuilder.build()` in the subprocess (e.g. `resizable`, `decorations`, `transparent`, `user_agent`, `initialization_script`, etc.). TYPE: `Any` DEFAULT: `{}`

pywry.runtime.set_content ¶

set_content(label: str, html: str, theme: str = 'dark') -> bool

Set window content via IPC. Waits for content to be set.

PARAMETER	DESCRIPTION
`label`	Window label. TYPE: `str`
`html`	HTML content. TYPE: `str`
`theme`	Theme mode ('dark' or 'light') - MUST match window background. TYPE: `str` DEFAULT: `'dark'`

pywry.runtime.check_window_open ¶

check_window_open(label: str) -> bool

Check if a window exists and is open via IPC.

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

RETURNS	DESCRIPTION
`bool`	True if window exists.

pywry.runtime.close_window ¶

close_window(label: str) -> bool

Close a window via IPC.

pywry.runtime.show_window ¶

show_window(label: str) -> bool

Show a hidden window via IPC.

pywry.runtime.hide_window ¶

hide_window(label: str) -> bool

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

pywry.runtime.refresh_window ¶

refresh_window(label: str) -> bool

Refresh a window by re-sending its stored content.

Re-sends the HTML content that was last set on this window. This is useful when you want to restore the window to its original state after dynamic DOM changes.

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

RETURNS	DESCRIPTION
`bool`	True if content was re-sent successfully.

pywry.runtime.refresh_all_windows ¶

refresh_all_windows() -> bool

Trigger a full page refresh for all windows.

RETURNS	DESCRIPTION
`bool`	True if command succeeded.

CSS & Script Injection¶

pywry.runtime.inject_css ¶

inject_css(label: str, css: str, asset_id: str) -> bool

Inject or update CSS in a window without page reload.

PARAMETER	DESCRIPTION
`label`	Window label to inject into. TYPE: `str`
`css`	CSS content to inject. TYPE: `str`
`asset_id`	ID for the style element (for updates). TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if command succeeded.

pywry.runtime.remove_css ¶

remove_css(label: str, asset_id: str) -> bool

Remove a CSS style element from a window.

PARAMETER	DESCRIPTION
`label`	Window label. TYPE: `str`
`asset_id`	ID of the style element to remove. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if command succeeded.

pywry.runtime.eval_js ¶

eval_js(label: str, script: str) -> bool

Evaluate arbitrary JavaScript in a window.

This runs JavaScript without replacing window content, useful for DOM queries and dynamic updates.

PARAMETER	DESCRIPTION
`label`	Window label. TYPE: `str`
`script`	JavaScript code to execute. TYPE: `str`

RETURNS	DESCRIPTION
`bool`	True if command was sent and succeeded.

Events¶

pywry.runtime.emit_event ¶

emit_event(label: str, event: str, payload: dict[str, Any] | None = None) -> bool

Emit a custom event to a window.

PARAMETER	DESCRIPTION
`label`	Window label (or "" for all windows). TYPE:* `str`
`event`	Event name. TYPE: `str`
`payload`	Event payload data. TYPE: `dict[str, Any] or None` DEFAULT: `None`

RETURNS	DESCRIPTION
`bool`	True if command succeeded.

Window Property Access¶

pywry.runtime.window_get ¶

window_get(label: str, property_name: str, args: dict[str, Any] | None = None, timeout: float = 5.0) -> Any

Get a window property via IPC.

PARAMETER	DESCRIPTION
`label`	Window label. TYPE: `str`
`property_name`	Name of the property to get. TYPE: `str`
`args`	Optional arguments for parameterised getters (e.g. `monitor_from_point`). TYPE: `dict or None` DEFAULT: `None`
`timeout`	Maximum time to wait for response. TYPE: `float` DEFAULT: `5.0`

RETURNS	DESCRIPTION
`Any`	The property value.

RAISES	DESCRIPTION
`PropertyError`	If the property cannot be retrieved.
`IPCTimeoutError`	If the request times out.

pywry.runtime.window_call ¶

window_call(label: str, method: str, args: dict[str, Any] | None = None, expect_response: bool = False, timeout: float = 5.0) -> Any

Call a window method via IPC.

PARAMETER	DESCRIPTION
`label`	Window label. TYPE: `str`
`method`	Name of the method to call. TYPE: `str`
`args`	Method arguments. TYPE: `dict[str, Any] or None` DEFAULT: `None`
`expect_response`	Whether to wait for a response. TYPE: `bool` DEFAULT: `False`
`timeout`	Maximum time to wait for response (if expect_response=True). TYPE: `float` DEFAULT: `5.0`

RETURNS	DESCRIPTION
`Any`	The method result (if expect_response=True), otherwise None.

RAISES	DESCRIPTION
`WindowError`	If the method call fails.
`IPCTimeoutError`	If the request times out (when expect_response=True).