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:

Type	Description
`bool`	True if PYWRY_HEADLESS environment variable is set.

pywry.runtime.start ¶

start() -> bool

Start the pytauri subprocess.

Returns:

Type	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:

Type	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.

Parameters:

Name	Type	Description	Default
`behavior`	`str`	Either "hide" (keep window alive) or "close" (destroy window).	required

pywry.runtime.set_window_mode ¶

set_window_mode(mode: str) -> None

Set the window mode.

Parameters:

Name	Type	Description	Default
`mode`	`str`	Either "single", "multi", or "new".	required

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().

Parameters:

Name	Type	Description	Default
`plugins`	`list[str]`	Plugin names (e.g. `["dialog", "fs", "notification"]`).	required

pywry.runtime.set_extra_capabilities ¶

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

Set additional Tauri capability permission strings.

Must be called before start().

Parameters:

Name	Type	Description	Default
`caps`	`list[str]`	Permission strings (e.g. `["shell:allow-execute"]`).	required

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.

Parameters:

Name	Type	Description	Default
`cmd`	`dict[str, Any]`	Command to send. A request_id will be added automatically.	required
`timeout`	`float`	Maximum time to wait for response.	`5.0`

Returns:

Type	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.

Parameters:

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

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.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label.	required
`html`	`str`	HTML content.	required
`theme`	`str`	Theme mode ('dark' or 'light') - MUST match window background.	`'dark'`

pywry.runtime.check_window_open ¶

check_window_open(label: str) -> bool

Check if a window exists and is open via IPC.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label to refresh.	required

Returns:

Type	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:

Type	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.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label to inject into.	required
`css`	`str`	CSS content to inject.	required
`asset_id`	`str`	ID for the style element (for updates).	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label.	required
`asset_id`	`str`	ID of the style element to remove.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label.	required
`script`	`str`	JavaScript code to execute.	required

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label (or "*" for all windows).	required
`event`	`str`	Event name.	required
`payload`	`dict[str, Any] or None`	Event payload data.	`None`

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
`label`	`str`	Window label.	required
`property_name`	`str`	Name of the property to get.	required
`args`	`dict or None`	Optional arguments for parameterised getters (e.g. `monitor_from_point`).	`None`
`timeout`	`float`	Maximum time to wait for response.	`5.0`

Returns:

Type	Description
`Any`	The property value.

Raises:

Type	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.

Parameters:

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

Returns:

Type	Description
`Any`	The method result (if expect_response=True), otherwise None.

Raises:

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