pywry.types

Type definitions for window positions, sizes, effects, cookies, and monitors.

---

Position & Size Types

pywry.types.PhysicalSize dataclass

PhysicalSize(width: int, height: int)

Physical size in device pixels.

Attributes:

Name	Type	Description
width	int	Width in physical pixels.
height	int	Height in physical pixels.

Functions

to_dict

to_dict() -> dict[str, int]

Serialize to dictionary for IPC.

from_dict classmethod

from_dict(data: dict[str, Any]) -> PhysicalSize

Deserialize from dictionary.

pywry.types.LogicalSize dataclass

LogicalSize(width: float, height: float)

Logical size scaled by the window DPI factor.

Attributes:

Name	Type	Description
width	float	Width in logical units.
height	float	Height in logical units.

Functions

to_dict

to_dict() -> dict[str, float]

Serialize to dictionary for IPC.

from_dict classmethod

from_dict(data: dict[str, Any]) -> LogicalSize

Deserialize from dictionary.

pywry.types.PhysicalPosition dataclass

PhysicalPosition(x: int, y: int)

Physical position in device pixels.

Attributes:

Name	Type	Description
x	int	Horizontal position in physical pixels.
y	int	Vertical position in physical pixels.

Functions

to_dict

to_dict() -> dict[str, int]

Serialize to dictionary for IPC.

from_dict classmethod

from_dict(data: dict[str, Any]) -> PhysicalPosition

Deserialize from dictionary.

pywry.types.LogicalPosition dataclass

LogicalPosition(x: float, y: float)

Logical position scaled by the window DPI factor.

Attributes:

Name	Type	Description
x	float	Horizontal position in logical units.
y	float	Vertical position in logical units.

Functions

to_dict

to_dict() -> dict[str, float]

Serialize to dictionary for IPC.

from_dict classmethod

from_dict(data: dict[str, Any]) -> LogicalPosition

Deserialize from dictionary.

---

Enumerations

pywry.types.Theme

Bases: Enum

Window theme mode.

pywry.types.TitleBarStyle

Bases: Enum

Title bar style options.

pywry.types.UserAttentionType

Bases: Enum

User attention request type.

pywry.types.CursorIcon

Bases: Enum

Cursor icon options.

pywry.types.Effect

Bases: Enum

Visual effects for window background (platform-specific).

pywry.types.EffectState

Bases: Enum

Effect state options.

pywry.types.ProgressBarStatus

Bases: Enum

Progress bar status options.

pywry.types.SameSite

Bases: Enum

Cookie SameSite attribute.

---

Typed Dicts

pywry.types.Effects

Bases: TypedDict

Visual effects configuration passed to the window layer.

Attributes:

Name	Type	Description
effects	Sequence[Effect]	Ordered list of platform-specific visual effects to apply.
state	EffectState	Active state for the effect where supported by the platform.
radius	float	Optional blur or rounding radius used by some effects.
color	Color	Optional RGBA color tint represented as a 4-tuple of integers.

pywry.types.ProgressBarState

Bases: TypedDict

Progress bar state configuration for taskbar integration.

Attributes:

Name	Type	Description
status	ProgressBarStatus	High-level progress state shown by the operating system.
progress	int	Progress percentage from 0 to 100.

---

Data Classes

pywry.types.Cookie dataclass

Cookie(name: str, value: str, domain: str = '', path: str = '/', secure: bool = False, http_only: bool = False, same_site: SameSite = LAX, expires: float | None = None)

HTTP cookie representation used by the IPC bridge.

Attributes:

Name	Type	Description
name	str	Cookie name.
value	str	Cookie value.
domain	str	Domain scope for the cookie.
path	str	Path scope for the cookie.
secure	bool	Whether the cookie is restricted to secure transports.
http_only	bool	Whether the cookie is hidden from client-side scripts.
same_site	SameSite	SameSite policy applied to cross-site requests.
expires	float | None	Expiration timestamp as seconds since the Unix epoch, if set.

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

from_dict classmethod

from_dict(data: dict[str, Any]) -> Cookie

Deserialize from dictionary.

pywry.types.Monitor dataclass

Monitor(name: str | None, size: PhysicalSize, position: PhysicalPosition, scale_factor: float)

Display monitor information returned by the window layer.

Attributes:

Name	Type	Description
name	str | None	Human-readable monitor name when available.
size	PhysicalSize	Physical pixel dimensions of the monitor.
position	PhysicalPosition	Top-left monitor position in virtual desktop coordinates.
scale_factor	float	DPI scale factor applied by the operating system.

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

from_dict classmethod

from_dict(data: dict[str, Any]) -> Monitor

Deserialize from dictionary.

---

Serialization Helpers

pywry.types.serialize_size

serialize_size(size: SizeType) -> dict[str, Any]

Serialize a logical or physical size for IPC transport.

Parameters:

Name	Type	Description	Default
size	SizeType	Size instance to serialize.	required

Returns:

Type	Description
dict[str, Any]	Dictionary tagged with type and the width and height values.

pywry.types.serialize_position

serialize_position(position: PositionType) -> dict[str, Any]

Serialize a logical or physical position for IPC transport.

Parameters:

Name	Type	Description	Default
position	PositionType	Position instance to serialize.	required

Returns:

Type	Description
dict[str, Any]	Dictionary tagged with type and the position coordinates.

pywry.types.serialize_effects

serialize_effects(effects: Effects) -> dict[str, Any]

Serialize visual effects configuration for IPC transport.

Parameters:

Name	Type	Description	Default
effects	Effects	Visual effects mapping to serialize.	required

Returns:

Type	Description
dict[str, Any]	JSON-serializable representation of the configured effects.

pywry.types.serialize_progress_bar

serialize_progress_bar(state: ProgressBarState) -> dict[str, Any]

Serialize taskbar progress state for IPC transport.

Parameters:

Name	Type	Description	Default
state	ProgressBarState	Progress bar mapping to serialize.	required

Returns:

Type	Description
dict[str, Any]	JSON-serializable representation of the taskbar progress state.

---

Menu Types

See the Native Menus guide for usage.

pywry.types.PredefinedMenuItemKind

Bases: Enum

Predefined OS-level menu item kinds.

pywry.types.MenuItemConfig dataclass

MenuItemConfig(id: str, text: str, handler: Callable[..., Any] = None, enabled: bool = True, accelerator: str | None = None)

Configuration for a regular menu item.

Every clickable menu item must have a handler. Pass a callable that accepts (data, event_type, label).

Parameters:

Name	Type	Description	Default
id	str	Unique identifier used for event routing.	required
text	str	Display text for the item.	required
handler	Callable	Click handler — receives (data, event_type, label).	None
enabled	bool	Whether the item is interactive.	True
accelerator	str or None	Keyboard shortcut (e.g. "CmdOrCtrl+S").	None

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

pywry.types.CheckMenuItemConfig dataclass

CheckMenuItemConfig(id: str, text: str, handler: Callable[..., Any] = None, enabled: bool = True, checked: bool = False, accelerator: str | None = None)

Configuration for a check (toggle) menu item.

Every check menu item must have a handler.

Parameters:

Name	Type	Description	Default
id	str	Unique identifier used for event routing.	required
text	str	Display text.	required
handler	Callable	Click handler — receives (data, event_type, label).	None
enabled	bool	Whether the item is interactive.	True
checked	bool	Initial checked state.	False
accelerator	str or None	Keyboard shortcut.	None

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

pywry.types.IconMenuItemConfig dataclass

IconMenuItemConfig(id: str, text: str, handler: Callable[..., Any] = None, enabled: bool = True, icon: bytes | None = None, icon_width: int = 16, icon_height: int = 16, native_icon: str | None = None, accelerator: str | None = None)

Configuration for a menu item with an icon.

Every icon menu item must have a handler.

Parameters:

Name	Type	Description	Default
id	str	Unique identifier used for event routing.	required
text	str	Display text.	required
handler	Callable	Click handler — receives (data, event_type, label).	None
enabled	bool	Whether the item is interactive.	True
icon	bytes or None	RGBA icon bytes (use pytauri.image.Image format).	None
icon_width	int	Icon width in pixels.	16
icon_height	int	Icon height in pixels.	16
native_icon	str or None	Native OS icon name (macOS only), e.g. "Add", "Folder".	None
accelerator	str or None	Keyboard shortcut.	None

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

pywry.types.PredefinedMenuItemConfig dataclass

PredefinedMenuItemConfig(kind_name: PredefinedMenuItemKind, text: str | None = None)

Configuration for a predefined OS menu item.

Parameters:

Name	Type	Description	Default
kind_name	PredefinedMenuItemKind	Which predefined item to create.	required
text	str or None	Override text (some predefined items accept this).	None

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

pywry.types.SubmenuConfig dataclass

SubmenuConfig(id: str, text: str, enabled: bool = True, items: list[MenuItemKindConfig] | None = None)

Configuration for a submenu.

Parameters:

Name	Type	Description	Default
id	str	Unique submenu identifier.	required
text	str	Display text for the submenu entry.	required
enabled	bool	Whether the submenu is interactive.	True
items	list	Child menu item configurations.	None

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

collect_handlers

collect_handlers() -> dict[str, Callable[..., Any]]

Walk children and return {item_id: handler} for every handled item.

pywry.types.MenuConfig dataclass

MenuConfig(id: str, items: list[MenuItemKindConfig])

Top-level menu configuration.

Parameters:

Name	Type	Description	Default
id	str	Menu identifier.	required
items	list	Menu item configurations.	required

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.

collect_handlers

collect_handlers() -> dict[str, Callable[..., Any]]

Walk the full item tree and return {item_id: handler}.

Recursively descends into submenus. Only items with a handler attribute are included (e.g. PredefinedMenuItemConfig is skipped).

from_dict classmethod

from_dict(data: dict[str, Any]) -> MenuConfig

Deserialize from dictionary.

---

Tray Types

See the System Tray guide for usage.

pywry.types.MouseButton

Bases: Enum

Mouse button identifiers.

pywry.types.MouseButtonState

Bases: Enum

Mouse button press state.

pywry.types.TrayIconConfig dataclass

TrayIconConfig(id: str, tooltip: str | None = None, title: str | None = None, icon: bytes | None = None, icon_width: int = 32, icon_height: int = 32, menu: MenuConfig | None = None, menu_on_left_click: bool = True, on_click: Callable[..., Any] | None = None, on_double_click: Callable[..., Any] | None = None, on_right_click: Callable[..., Any] | None = None)

Configuration for a system tray icon.

Parameters:

Name	Type	Description	Default
id	str	Unique tray icon identifier.	required
tooltip	str or None	Hover tooltip text.	None
title	str or None	Tray icon title (macOS menu bar text).	None
icon	bytes or None	RGBA icon bytes.	None
icon_width	int	Icon width in pixels.	32
icon_height	int	Icon height in pixels.	32
menu	MenuConfig or None	Menu to attach to the tray icon.	None
menu_on_left_click	bool	Whether left click shows the menu.	True
on_click	Callable or None	Handler for single-click events.	None
on_double_click	Callable or None	Handler for double-click events.	None
on_right_click	Callable or None	Handler for right-click events.	None

Functions

to_dict

to_dict() -> dict[str, Any]

Serialize to dictionary for IPC.