pywry.models¶
Core Pydantic models for content, window configuration, and events.
Window Mode¶
Theme Mode¶
Window Configuration¶
Bases: BaseModel
Configuration for window creation.
Fields are split into two groups:
Application-level fields — used by PyWry's template and content pipeline
(theme, enable_plotly, aggrid_theme, etc.).
Builder-level fields — forwarded to WebviewWindowBuilder.build() in
the subprocess. Fields marked (build-only) can only be set at window
creation time; they have no post-creation set_* equivalent.
Attributes¶
class-attribute
instance-attribute
¶
plotly_theme: Literal['plotly', 'plotly_white', 'plotly_dark', 'ggplot2', 'seaborn', 'simple_white'] = 'plotly_dark'
class-attribute
instance-attribute
¶
class-attribute
¶
_BUILDER_FIELDS: set[str] = {'resizable', 'decorations', 'always_on_top', 'always_on_bottom', 'transparent', 'fullscreen', 'maximized', 'focused', 'visible', 'shadow', 'skip_taskbar', 'content_protected', 'user_agent', 'incognito', 'initialization_script', 'drag_and_drop'}
Functions¶
Return non-default builder kwargs for WebviewWindowBuilder.build().
Only includes fields whose values differ from the Pydantic defaults,
keeping the IPC payload minimal. title and inner_size are
always handled separately by the caller.
validate_dimensions() -> WindowConfig
Validate min dimensions don't exceed actual dimensions.
HTML Content¶
Bases: BaseModel
HTML content bundle rendered inside a PyWry window.
Attributes:
| Name | Type | Description |
|---|---|---|
html |
str
|
HTML markup to load into the window. |
json_data |
dict[str, Any] | None
|
Optional JSON payload injected into the page bootstrap. |
init_script |
str | None
|
JavaScript executed after the page is initialized. |
css_files |
list[Path | str] | None
|
External CSS files to load alongside the HTML. |
script_files |
list[Path | str] | None
|
External JavaScript files to load alongside the HTML. |
inline_css |
str | None
|
Inline CSS appended to the generated document. |
watch |
bool
|
Whether the content should participate in hot-reload file watching. |
Event Models¶
Generic Event¶
Bases: BaseModel
Generic event envelope for custom event handling.
Attributes:
| Name | Type | Description |
|---|---|---|
event_type |
str
|
Event name in |
data |
Any
|
Arbitrary event payload forwarded from the frontend. |
window_label |
str
|
Window identifier that emitted the event. |
timestamp |
datetime
|
Event creation time. |
Attributes¶
Functions¶
classmethod
¶
Validate event type matches namespace:event-name pattern.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
v
|
str
|
The event type string to validate. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The validated event type. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the event type is invalid. |
Result Event¶
Bases: BaseModel
Result sent from JavaScript via window.pywry.result().
Attributes:
| Name | Type | Description |
|---|---|---|
data |
Any
|
Arbitrary result payload returned by the page. |
window_label |
str
|
Window identifier that produced the result. |
Plotly Click Event¶
Bases: BaseModel
Plotly click event payload.
Attributes:
| Name | Type | Description |
|---|---|---|
point_indices |
list[int]
|
Indices of points included in the click interaction. |
curve_number |
int
|
Trace index for the clicked point. |
point_data |
dict[str, Any]
|
Raw Plotly point payload for the clicked datum. |
window_label |
str
|
Window identifier that emitted the event. |
Plotly Select Event¶
Bases: BaseModel
Plotly selection event payload.
Attributes:
| Name | Type | Description |
|---|---|---|
points |
list[dict[str, Any]]
|
Plotly point payloads included in the current selection. |
range |
dict[str, Any] | None
|
Selected axis range when Plotly reports it. |
window_label |
str
|
Window identifier that emitted the event. |
Plotly Hover Event¶
Bases: BaseModel
Plotly hover event payload.
Attributes:
| Name | Type | Description |
|---|---|---|
point_indices |
list[int]
|
Indices of points under the cursor. |
curve_number |
int
|
Trace index for the hovered point. |
point_data |
dict[str, Any]
|
Raw Plotly point payload for the hover target. |
window_label |
str
|
Window identifier that emitted the event. |
Plotly Relayout Event¶
Bases: BaseModel
Plotly relayout event payload for zoom, pan, and layout changes.
Attributes:
| Name | Type | Description |
|---|---|---|
relayout_data |
dict[str, Any]
|
Raw Plotly relayout payload. |
window_label |
str
|
Window identifier that emitted the event. |
Validation Functions¶
Validate event type matches namespace:event-name pattern or is wildcard.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event_type
|
str
|
The event type string to validate. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if valid, False otherwise. |
Grid Events¶
Bases: BaseModel
AG Grid selection event payload.
Attributes:
| Name | Type | Description |
|---|---|---|
selected_rows |
list[dict[str, Any]]
|
Full row objects currently selected in the grid. |
selected_row_ids |
list[str]
|
Stable identifiers for the selected rows. |
window_label |
str
|
Window identifier that emitted the event. |
Bases: BaseModel
AG Grid cell event payload.
Attributes:
| Name | Type | Description |
|---|---|---|
row_id |
str
|
Stable identifier for the edited row. |
row_index |
int
|
Visible row index in the current grid view. |
column |
str
|
Column field associated with the event. |
old_value |
Any
|
Previous cell value before the edit. |
new_value |
Any
|
New cell value after the edit. |
window_label |
str
|
Window identifier that emitted the event. |
Attributes¶
Bases: BaseModel
AG Grid row click event payload.
Attributes:
| Name | Type | Description |
|---|---|---|
row_data |
dict[str, Any]
|
Full row object for the clicked row. |
row_id |
str
|
Stable identifier for the clicked row. |
row_index |
int
|
Visible row index in the current grid view. |
window_label |
str
|
Window identifier that emitted the event. |
Event Payloads¶
Bases: BaseModel
Payload for the pywry_result command.
Attributes:
| Name | Type | Description |
|---|---|---|
data |
Any
|
Result payload supplied by the frontend. |
window_label |
str
|
Window identifier associated with the result. |
Bases: BaseModel
Payload for the pywry_event command.
Attributes:
| Name | Type | Description |
|---|---|---|
event_type |
str
|
Event name in |
data |
Any
|
Arbitrary event payload. |
window_label |
str
|
Window identifier associated with the event. |
Attributes¶
Functions¶
classmethod
¶
Validate event type matches namespace:event-name pattern.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
v
|
str
|
The event type string to validate. |
required |
Returns:
| Type | Description |
|---|---|
str
|
The validated event type. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If the event type is invalid. |
Bases: BaseModel
Payload for a window closed notification.
Attributes:
| Name | Type | Description |
|---|---|---|
window_label |
str
|
Identifier of the window that was closed. |
Bases: BaseModel
Enhanced alert event payload for pywry:alert system event.
Supports typed toast notifications with auto-dismiss, persistence, and confirmation dialogs with callbacks.
Attributes¶
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
type: Literal['info', 'success', 'warning', 'error', 'confirm'] = Field(default='info', description='Alert type determining icon and behavior')
class-attribute
instance-attribute
¶
class-attribute
instance-attribute
¶
duration: int | None = Field(default=None, description='Auto-dismiss duration in ms (None uses type default)')
class-attribute
instance-attribute
¶
callback_event: str | None = Field(default=None, description="Event to emit on confirm/cancel (for type='confirm')")
class-attribute
instance-attribute
¶
position: Literal['top-right', 'bottom-right', 'bottom-left', 'top-left'] = Field(default='top-right', description='Toast position on screen')