pywry.window_manager

Window lifecycle management, controllers, and rendering mode strategies.

---

Lifecycle

pywry.window_manager.get_lifecycle

get_lifecycle() -> WindowLifecycle

Get the global window lifecycle manager.

Returns:

Type	Description
WindowLifecycle	The window lifecycle singleton.

pywry.window_manager.WindowLifecycle

WindowLifecycle()

Manages window lifecycle with aggressive cleanup.

Uses subprocess IPC to communicate with pytauri process.

Notes

This class is implemented as a singleton so all PyWry entry points share the same view of tracked window resources.

Initialize the lifecycle manager.

Functions

clear

clear() -> None

Clear all tracked windows.

This resets the lifecycle manager to its initial state. Useful for test cleanup when the runtime is stopped.

create

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

Create or register a window via subprocess IPC.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
title	str	Window title.	'PyWry'
width	int	Window width.	800
height	int	Window height.	600
**builder_opts	Any	Additional keyword arguments forwarded to runtime.create_window() and ultimately to WebviewWindowBuilder.build() (e.g. resizable, decorations, transparent, initialization_script).	{}

Returns:

Type	Description
WindowResources	The window resources object.

get

get(label: str) -> WindowResources | None

Get resources for a window.

Parameters:

Name	Type	Description	Default
label	str	Window label to look up.	required

Returns:

Type	Description
WindowResources | None	Tracked resources for the window, or None when unknown.

exists

exists(label: str) -> bool

Check if a window exists and is not destroyed.

Parameters:

Name	Type	Description	Default
label	str	Window label to test.	required

Returns:

Type	Description
bool	True when the window is tracked and still active.

register_window

register_window(label: str) -> WindowResources

Register a window in lifecycle tracking without creating via IPC.

Use this when the window already exists (e.g., from previous PyWry instance) and just needs to be tracked.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
WindowResources	The window resources object.

get_active_windows

get_active_windows() -> list[str]

Get labels of all tracked active windows.

Returns:

Type	Description
list[str]	Labels for windows that have not been destroyed.

set_content

set_content(label: str, html: str, theme: str = 'dark', config: WindowConfig | None = None) -> bool

Set the HTML content for a window via IPC.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
html	str	The HTML content.	required
theme	str	Theme mode ('dark' or 'light') - MUST match window background.	'dark'
config	WindowConfig or None	Store config for content-request handler to use.	None

Returns:

Type	Description
bool	True if successful, False otherwise.

is_open

is_open(label: str) -> bool

Check if window is truly open via IPC.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if window is verified open in backend.

store_content_for_refresh

store_content_for_refresh(label: str, content: HtmlContent, config: WindowConfig) -> bool

Store content and config for window refresh.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
content	HtmlContent	The HtmlContent object.	required
config	WindowConfig	The WindowConfig object.	required

Returns:

Type	Description
bool	True if stored successfully.

get_content_for_refresh

get_content_for_refresh(label: str) -> tuple[HtmlContent | None, WindowConfig | None]

Get stored content and config for window refresh.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
tuple[HtmlContent or None, WindowConfig or None]	Tuple of (content, config) or (None, None) if not found.

add_watched_file

add_watched_file(label: str, path: Path, file_type: str, asset_id: str | None = None) -> bool

Track a file for hot reload.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
path	Path	Path to the watched file.	required
file_type	str	Either "css" or "script".	required
asset_id	str or None	Asset ID for CSS files.	None

Returns:

Type	Description
bool	True if tracked successfully.

clear_watched_files

clear_watched_files(label: str) -> bool

Clear all watched files for a window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if cleared successfully.

add_script

add_script(label: str, script_name: str) -> bool

Track a script injection.

add_library

add_library(label: str, library_name: str) -> bool

Track a library load.

set_data

set_data(label: str, key: str, value: Any) -> bool

Set custom data for a window.

get_data

get_data(label: str, key: str, default: Any = None) -> Any

Get custom data for a window.

destroy

destroy(label: str) -> bool

Destroy a window via IPC.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if resources were destroyed, False if window not found.

destroy_all

destroy_all() -> int

Destroy all tracked windows.

Returns:

Type	Description
int	Number of windows destroyed.

get_labels

get_labels() -> list[str]

Get all active window labels.

Returns:

Type	Description
list of str	List of window labels.

get_stats

get_stats() -> dict[str, Any]

Get statistics about tracked windows.

Returns:

Type	Description
dict[str, Any]	Statistics dict.

pywry.window_manager.WindowResources dataclass

WindowResources(label: str, created_at: datetime = now(), html_content: str | None = None, scripts_injected: list[str] = list(), libraries_loaded: list[str] = list(), custom_data: dict[str, Any] = dict(), is_destroyed: bool = False, last_content: HtmlContent | None = None, last_config: WindowConfig | None = None, watched_css: list[Path] = list(), watched_scripts: list[Path] = list(), css_asset_ids: dict[Path, str] = dict(), content_set_at: datetime | None = None, on_close: list[Callable[[str, str], None]] = list(), close_reason: str | None = None)

Tracks resources associated with a window.

Attributes:

Name	Type	Description
label	str	Window label used to address the native webview.
created_at	datetime	Timestamp when lifecycle tracking was created for the window.
html_content	str | None	Most recent HTML content sent to the window.
scripts_injected	list[str]	Script payloads injected into the window lifecycle.
libraries_loaded	list[str]	External libraries recorded as loaded for the window.
custom_data	dict[str, Any]	Arbitrary caller-managed metadata associated with the window.
is_destroyed	bool	Indicates the window has been torn down and should not be reused.
last_content	HtmlContent | None	Last HtmlContent object retained for hot-refresh restoration.
last_config	WindowConfig | None	Last WindowConfig retained for hot-refresh restoration.
watched_css	list[Path]	CSS files watched for hot-reload updates.
watched_scripts	list[Path]	Script files watched for hot-reload updates.
css_asset_ids	dict[Path, str]	Asset identifiers assigned to watched CSS files.
content_set_at	datetime | None	Timestamp of the last content IPC update.
on_close	list[Callable[[str, str], None]]	Close callbacks invoked with (label, close_reason).
close_reason	str | None	Last recorded reason the window was closed.

---

Controller

pywry.window_manager.WindowController

WindowController(mode: WindowMode = NEW_WINDOW)

Controller for window management across different modes.

This class provides a unified interface for creating and managing windows regardless of the underlying window mode.

Initialize the controller.

Parameters:

Name	Type	Description	Default
mode	WindowMode	The window mode to use.	NEW_WINDOW

Attributes

mode property

mode: WindowMode

Get the current window mode.

Functions

set_mode

set_mode(mode: WindowMode) -> None

Change the window mode.

Warning: This closes all existing windows.

Parameters:

Name	Type	Description	Default
mode	WindowMode	The new window mode.	required

show

show(config: WindowConfig, html: str, callbacks: dict[str, CallbackFunc] | None = None) -> str

Show content in a window.

Parameters:

Name	Type	Description	Default
config	WindowConfig	Window configuration.	required
html	str	HTML content to display.	required
callbacks	dict[str, CallbackFunc] or None	Optional event callbacks.	None

Returns:

Type	Description
str	The window label.

close

close(label: str) -> bool

Close a specific window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if closed successfully.

close_all

close_all() -> int

Close all windows.

Returns:

Type	Description
int	Number of windows closed.

is_open

is_open(label: str) -> bool

Check if a window is open.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if window is open.

update_content

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

Update window content.

Parameters:

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

Returns:

Type	Description
bool	True if updated successfully.

send_event

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

Send an event to a window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
event_type	str	The event type.	required
data	Any	The event data.	required

Returns:

Type	Description
bool	True if sent successfully.

get_labels

get_labels() -> list[str]

Get all window labels.

Returns:

Type	Description
list of str	List of window labels.

get_stats

get_stats() -> dict[str, Any]

Get window statistics.

Returns:

Type	Description
dict[str, Any]	Statistics dict.

---

Mode Strategies

pywry.window_manager.WindowModeBase

Bases: ABC

Abstract base class for window modes.

Functions

show abstractmethod

show(config: WindowConfig, html: str, callbacks: dict[str, Any] | None = None, label: str | None = None) -> str

Show content in a window.

Parameters:

Name	Type	Description	Default
config	WindowConfig	Window configuration.	required
html	str	HTML content to display.	required
callbacks	dict[str, Any] or None	Optional callback handlers.	None
label	str or None	Optional window label (for multi-window mode).	None

Returns:

Type	Description
str	The window label.

close abstractmethod

close(label: str) -> bool

Close a window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if closed successfully, False otherwise.

is_open abstractmethod

is_open(label: str) -> bool

Check if a window is open.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if window is open, False otherwise.

update_content abstractmethod

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

Update window content.

Parameters:

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

Returns:

Type	Description
bool	True if updated successfully, False otherwise.

send_event abstractmethod

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

Send an event to a window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
event_type	str	The event type.	required
data	Any	The event data.	required

Returns:

Type	Description
bool	True if sent successfully, False otherwise.

get_labels abstractmethod

get_labels() -> list[str]

Get all window labels managed by this mode.

Returns:

Type	Description
list of str	List of window labels.

close_all abstractmethod

close_all() -> int

Close all windows.

Returns:

Type	Description
int	Number of windows closed.

show_window

show_window(label: str) -> bool

Show a hidden window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if shown successfully, False otherwise.

hide_window

hide_window(label: str) -> bool

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

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if hidden successfully, False otherwise.

pywry.window_manager.NewWindowMode

NewWindowMode()

Bases: WindowModeBase

Creates a new window for each show() call.

Each window is independent and has its own lifecycle.

Initialize the mode.

Functions

show

show(config: WindowConfig, html: str, callbacks: dict[str, Any] | None = None, label: str | None = None) -> str

Show content in a new window.

Parameters:

Name	Type	Description	Default
config	WindowConfig	Window configuration.	required
html	str	HTML content to display.	required
callbacks	dict[str, Any] or None	Optional callback handlers.	None
label	str or None	Ignored in new window mode.	None

Returns:

Type	Description
str	The window label.

close

close(label: str) -> bool

Close a window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if closed successfully, False otherwise.

is_open

is_open(label: str) -> bool

Check if a window is open.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if window is open and visible, False otherwise.

update_content

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

Update window content.

Parameters:

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

Returns:

Type	Description
bool	True if updated successfully, False otherwise.

send_event

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

Send an event to a window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
event_type	str	The event type.	required
data	Any	The event data.	required

Returns:

Type	Description
bool	True if sent successfully, False otherwise.

get_labels

get_labels() -> list[str]

Get all visible window labels managed by this mode.

Returns:

Type	Description
list of str	List of visible window labels.

close_all

close_all() -> int

Close all windows.

Returns:

Type	Description
int	Number of windows closed.

pywry.window_manager.SingleWindowMode

SingleWindowMode(label: str = 'main')

Bases: WindowModeBase

Reuses a single window for all show() calls.

Content is replaced in-place without creating new windows.

Initialize the mode.

Parameters:

Name	Type	Description	Default
label	str	The fixed label for the single window, by default "main".	'main'

Attributes

label property

label: str

Get the window label.

Functions

show

show(config: WindowConfig, html: str, callbacks: dict[str, Any] | None = None, label: str | None = None) -> str

Show content in the single window.

If window doesn't exist, creates it. Otherwise replaces content. Window is never destroyed - just hidden when user clicks X.

Parameters:

Name	Type	Description	Default
config	WindowConfig	Window configuration.	required
html	str	HTML content to display.	required
callbacks	dict[str, Any] or None	Optional callback handlers.	None
label	str or None	Ignored for single window mode.	None

Returns:

Type	Description
str	The window label.

close

close(label: str) -> bool

Close the window.

This closes the window but preserves lifecycle tracking and callbacks, allowing the window to be reopened via show(). For full cleanup, use the app's destroy() method instead.

Parameters:

Name	Type	Description	Default
label	str	The window label (must match our label).	required

Returns:

Type	Description
bool	True if closed successfully, False otherwise.

is_open

is_open(label: str) -> bool

Check if the window is open.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if window is open, False otherwise.

update_content

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

Update window content.

Parameters:

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

Returns:

Type	Description
bool	True if updated successfully, False otherwise.

send_event

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

Send an event to the window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
event_type	str	The event type.	required
data	Any	The event data.	required

Returns:

Type	Description
bool	True if sent successfully, False otherwise.

get_labels

get_labels() -> list[str]

Get window labels.

Returns:

Type	Description
list of str	List containing the single window label if visible.

close_all

close_all() -> int

Close all windows (just the one).

Returns:

Type	Description
int	Number of windows closed (0 or 1).

pywry.window_manager.MultiWindowMode

MultiWindowMode()

Bases: WindowModeBase

Manages multiple independent windows.

Each window has a unique label and can be controlled independently. Non-blocking - all windows can be interacted with simultaneously.

Initialize the mode.

Functions

show

show(config: WindowConfig, html: str, callbacks: dict[str, Any] | None = None, label: str | None = None) -> str

Show content in a window.

If label is provided and window exists, updates content. Otherwise creates a new window.

Parameters:

Name	Type	Description	Default
config	WindowConfig	Window configuration.	required
html	str	HTML content to display.	required
callbacks	dict[str, Any] or None	Optional callback handlers.	None
label	str or None	Optional specific label (for update).	None

Returns:

Type	Description
str	The window label.

close

close(label: str) -> bool

Close a specific window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if closed successfully, False otherwise.

is_open

is_open(label: str) -> bool

Check if a window is open.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if window is open, False otherwise.

update_content

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

Update window content.

Parameters:

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

Returns:

Type	Description
bool	True if updated successfully, False otherwise.

send_event

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

Send an event to a specific window.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required
event_type	str	The event type.	required
data	Any	The event data.	required

Returns:

Type	Description
bool	True if sent successfully, False otherwise.

send_event_all

send_event_all(event_type: str, data: Any) -> int

Send an event to all windows.

Parameters:

Name	Type	Description	Default
event_type	str	The event type.	required
data	Any	The event data.	required

Returns:

Type	Description
int	Number of windows that received the event.

get_labels

get_labels() -> list[str]

Get all visible window labels.

Returns:

Type	Description
list of str	List of visible window labels.

close_all

close_all() -> int

Close all windows.

Returns:

Type	Description
int	Number of windows closed.

get_window_count

get_window_count() -> int

Get the number of open windows.

Returns:

Type	Description
int	Number of open windows.

show_window

show_window(label: str) -> bool

Show a hidden window and update visibility tracking.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if shown successfully, False otherwise.

hide_window

hide_window(label: str) -> bool

Hide a window and update visibility tracking.

Parameters:

Name	Type	Description	Default
label	str	The window label.	required

Returns:

Type	Description
bool	True if hidden successfully, False otherwise.

pywry.window_manager.BrowserMode

BrowserMode()

Bases: WindowModeBase

Opens content in the system's default browser.

Uses the inline FastAPI server and opens the widget URL in a browser tab. Each show() call creates a new widget instance with its own state.

This mode is ideal for headless environments (servers, SSH sessions) or when native window support is not available.

Initialize the browser mode.

Functions

show

show(config: WindowConfig, html: str, callbacks: dict[str, Any] | None = None, label: str | None = None) -> str

Show content in the system browser.

Parameters:

Name	Type	Description	Default
config	WindowConfig	Window configuration (width/height used for suggestion only).	required
html	str	HTML content to display.	required
callbacks	dict[str, Any] or None	Optional callback handlers.	None
label	str or None	Optional widget label (used as prefix for widget_id).	None

Returns:

Type	Description
str	The widget ID (used as window_label for GenericEvent).

close

close(label: str) -> bool

Close a widget by removing it from tracking.

Note: This does not close the browser tab - that's user-controlled. It does trigger the disconnect callback and cleanup.

Parameters:

Name	Type	Description	Default
label	str	The widget ID.	required

Returns:

Type	Description
bool	True if widget was found and cleaned up.

close_all

close_all() -> int

Close all tracked widgets.

Returns:

Type	Description
int	Number of widgets closed.

is_open

is_open(label: str) -> bool

Check if a widget is being tracked.

Note: This only checks if we're tracking the widget, not if the browser tab is actually open (we can't know that).

Parameters:

Name	Type	Description	Default
label	str	The widget ID.	required

Returns:

Type	Description
bool	True if widget is being tracked.

update_content

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

Update widget content.

Parameters:

Name	Type	Description	Default
label	str	The widget ID.	required
html	str	New HTML content.	required
theme	str	Theme mode ('dark' or 'light').	'dark'

Returns:

Type	Description
bool	True if updated successfully.

send_event

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

Send an event to a widget's browser.

Parameters:

Name	Type	Description	Default
label	str	The widget ID.	required
event_type	str	The event type.	required
data	Any	The event data.	required

Returns:

Type	Description
bool	True if sent successfully.

get_labels

get_labels() -> list[str]

Get all tracked widget IDs.

Returns:

Type	Description
list of str	List of widget IDs.

get_widget

get_widget(widget_id: str) -> Any | None

Get an InlineWidget by ID for further interaction.

Parameters:

Name	Type	Description	Default
widget_id	str	The widget ID returned from show().	required

Returns:

Type	Description
InlineWidget or None	The widget instance, or None if not found.