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

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.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
title	Window title. TYPE: str DEFAULT: 'PyWry'
width	Window width. TYPE: int DEFAULT: 800
height	Window height. TYPE: int DEFAULT: 600
**builder_opts	Additional keyword arguments forwarded to runtime.create_window() and ultimately to WebviewWindowBuilder.build() (e.g. resizable, decorations, transparent, initialization_script). TYPE: Any DEFAULT: {}

RETURNS	DESCRIPTION
WindowResources	The window resources object.

get

get(label: str) -> WindowResources | None

Get resources for a window.

exists

exists(label: str) -> bool

Check if a window exists.

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.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
WindowResources	The window resources object.

get_active_windows

get_active_windows() -> list[str]

Get labels of all tracked active windows.

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.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
html	The HTML content. TYPE: str
theme	Theme mode ('dark' or 'light') - MUST match window background. TYPE: str DEFAULT: 'dark'
config	Store config for content-request handler to use. TYPE: WindowConfig or None DEFAULT: None

RETURNS	DESCRIPTION
bool	True if successful, False otherwise.

is_open

is_open(label: str) -> bool

Check if window is truly open via IPC.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
content	The HtmlContent object. TYPE: HtmlContent
config	The WindowConfig object. TYPE: WindowConfig

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
path	Path to the watched file. TYPE: Path
file_type	Either "css" or "script". TYPE: str
asset_id	Asset ID for CSS files. TYPE: str or None DEFAULT: None

RETURNS	DESCRIPTION
bool	True if tracked successfully.

clear_watched_files

clear_watched_files(label: str) -> bool

Clear all watched files for a window.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if resources were destroyed, False if window not found.

destroy_all

destroy_all() -> int

Destroy all tracked windows.

RETURNS	DESCRIPTION
int	Number of windows destroyed.

get_labels

get_labels() -> list[str]

Get all active window labels.

RETURNS	DESCRIPTION
list of str	List of window labels.

get_stats

get_stats() -> dict[str, Any]

Get statistics about tracked windows.

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

---

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.

PARAMETER	DESCRIPTION
mode	The window mode to use. TYPE: WindowMode DEFAULT: 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.

PARAMETER	DESCRIPTION
mode	The new window mode. TYPE: WindowMode

show

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

Show content in a window.

PARAMETER	DESCRIPTION
config	Window configuration. TYPE: WindowConfig
html	HTML content to display. TYPE: str
callbacks	Optional event callbacks. TYPE: dict[str, CallbackFunc] or None DEFAULT: None

RETURNS	DESCRIPTION
str	The window label.

close

close(label: str) -> bool

Close a specific window.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if closed successfully.

close_all

close_all() -> int

Close all windows.

RETURNS	DESCRIPTION
int	Number of windows closed.

is_open

is_open(label: str) -> bool

Check if a window is open.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if window is open.

update_content

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

Update window content.

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

RETURNS	DESCRIPTION
bool	True if updated successfully.

send_event

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

Send an event to a window.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
event_type	The event type. TYPE: str
data	The event data. TYPE: Any

RETURNS	DESCRIPTION
bool	True if sent successfully.

get_labels

get_labels() -> list[str]

Get all window labels.

RETURNS	DESCRIPTION
list of str	List of window labels.

get_stats

get_stats() -> dict[str, Any]

Get window statistics.

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

PARAMETER	DESCRIPTION
config	Window configuration. TYPE: WindowConfig
html	HTML content to display. TYPE: str
callbacks	Optional callback handlers. TYPE: dict[str, Any] or None DEFAULT: None
label	Optional window label (for multi-window mode). TYPE: str or None DEFAULT: None

RETURNS	DESCRIPTION
str	The window label.

close abstractmethod

close(label: str) -> bool

Close a window.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if closed successfully, False otherwise.

is_open abstractmethod

is_open(label: str) -> bool

Check if a window is open.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

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

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

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
event_type	The event type. TYPE: str
data	The event data. TYPE: Any

RETURNS	DESCRIPTION
bool	True if sent successfully, False otherwise.

get_labels abstractmethod

get_labels() -> list[str]

Get all window labels managed by this mode.

RETURNS	DESCRIPTION
list of str	List of window labels.

close_all abstractmethod

close_all() -> int

Close all windows.

RETURNS	DESCRIPTION
int	Number of windows closed.

show_window

show_window(label: str) -> bool

Show a hidden window.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if shown successfully, False otherwise.

hide_window

hide_window(label: str) -> bool

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

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

PARAMETER	DESCRIPTION
config	Window configuration. TYPE: WindowConfig
html	HTML content to display. TYPE: str
callbacks	Optional callback handlers. TYPE: dict[str, Any] or None DEFAULT: None
label	Ignored in new window mode. TYPE: str or None DEFAULT: None

RETURNS	DESCRIPTION
str	The window label.

close

close(label: str) -> bool

Close a window.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if closed successfully, False otherwise.

is_open

is_open(label: str) -> bool

Check if a window is open.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

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

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

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
event_type	The event type. TYPE: str
data	The event data. TYPE: Any

RETURNS	DESCRIPTION
bool	True if sent successfully, False otherwise.

get_labels

get_labels() -> list[str]

Get all visible window labels managed by this mode.

RETURNS	DESCRIPTION
list of str	List of visible window labels.

close_all

close_all() -> int

Close all windows.

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

PARAMETER	DESCRIPTION
label	The fixed label for the single window, by default "main". TYPE: str DEFAULT: '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.

PARAMETER	DESCRIPTION
config	Window configuration. TYPE: WindowConfig
html	HTML content to display. TYPE: str
callbacks	Optional callback handlers. TYPE: dict[str, Any] or None DEFAULT: None
label	Ignored for single window mode. TYPE: str or None DEFAULT: None

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

PARAMETER	DESCRIPTION
label	The window label (must match our label). TYPE: str

RETURNS	DESCRIPTION
bool	True if closed successfully, False otherwise.

is_open

is_open(label: str) -> bool

Check if the window is open.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if window is open, False otherwise.

update_content

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

Update window content.

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

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
event_type	The event type. TYPE: str
data	The event data. TYPE: Any

RETURNS	DESCRIPTION
bool	True if sent successfully, False otherwise.

get_labels

get_labels() -> list[str]

Get window labels.

RETURNS	DESCRIPTION
list of str	List containing the single window label if visible.

close_all

close_all() -> int

Close all windows (just the one).

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

PARAMETER	DESCRIPTION
config	Window configuration. TYPE: WindowConfig
html	HTML content to display. TYPE: str
callbacks	Optional callback handlers. TYPE: dict[str, Any] or None DEFAULT: None
label	Optional specific label (for update). TYPE: str or None DEFAULT: None

RETURNS	DESCRIPTION
str	The window label.

close

close(label: str) -> bool

Close a specific window.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if closed successfully, False otherwise.

is_open

is_open(label: str) -> bool

Check if a window is open.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if window is open, False otherwise.

update_content

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

Update window content.

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

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

PARAMETER	DESCRIPTION
label	The window label. TYPE: str
event_type	The event type. TYPE: str
data	The event data. TYPE: Any

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

PARAMETER	DESCRIPTION
event_type	The event type. TYPE: str
data	The event data. TYPE: Any

RETURNS	DESCRIPTION
int	Number of windows that received the event.

get_labels

get_labels() -> list[str]

Get all visible window labels.

RETURNS	DESCRIPTION
list of str	List of visible window labels.

close_all

close_all() -> int

Close all windows.

RETURNS	DESCRIPTION
int	Number of windows closed.

get_window_count

get_window_count() -> int

Get the number of open windows.

RETURNS	DESCRIPTION
int	Number of open windows.

show_window

show_window(label: str) -> bool

Show a hidden window and update visibility tracking.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

RETURNS	DESCRIPTION
bool	True if shown successfully, False otherwise.

hide_window

hide_window(label: str) -> bool

Hide a window and update visibility tracking.

PARAMETER	DESCRIPTION
label	The window label. TYPE: str

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

PARAMETER	DESCRIPTION
config	Window configuration (width/height used for suggestion only). TYPE: WindowConfig
html	HTML content to display. TYPE: str
callbacks	Optional callback handlers. TYPE: dict[str, Any] or None DEFAULT: None
label	Optional widget label (used as prefix for widget_id). TYPE: str or None DEFAULT: None

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

PARAMETER	DESCRIPTION
label	The widget ID. TYPE: str

RETURNS	DESCRIPTION
bool	True if widget was found and cleaned up.

close_all

close_all() -> int

Close all tracked widgets.

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

PARAMETER	DESCRIPTION
label	The widget ID. TYPE: str

RETURNS	DESCRIPTION
bool	True if widget is being tracked.

update_content

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

Update widget content.

PARAMETER	DESCRIPTION
label	The widget ID. TYPE: str
html	New HTML content. TYPE: str
theme	Theme mode ('dark' or 'light'). TYPE: str DEFAULT: 'dark'

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

PARAMETER	DESCRIPTION
label	The widget ID. TYPE: str
event_type	The event type. TYPE: str
data	The event data. TYPE: Any

RETURNS	DESCRIPTION
bool	True if sent successfully.

get_labels

get_labels() -> list[str]

Get all tracked widget IDs.

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

PARAMETER	DESCRIPTION
widget_id	The widget ID returned from show(). TYPE: str

RETURNS	DESCRIPTION
InlineWidget or None	The widget instance, or None if not found.