plesty.lib.ui

GUI framework: one home window, many rearrangeable sub-windows.

The framework is generic — a Panel is anything worth a sub-window, and MonitorPanel (live views) is only its first implementation; device controls and run boards are the same contract. Theme carries the plesty.net design tokens so every PLESTY GUI looks like the platform it belongs to.

The Qt-dependent names (Shell, PlotRenderer, run()) are resolved lazily, so import plesty.lib.ui works on a headless host without PySide6 installed; only using them requires the gui extra:

uv add "plesty-lib[gui]"

Submodules

Attributes

`DOCK_AREAS`
`ASSETS`

Classes

`MonitorPanel`	Sub-window rendering one monitor.
`Panel`	Base class for the dockable units of a `Shell`.
`Theme`	Resolved design tokens plus the stylesheet built from them.

Package Contents

class plesty.lib.ui.MonitorPanel(monitor: plesty.lib.monitor.base_monitor.Monitor, *, theme: plesty.lib.ui.theme.Theme | None = None, **kwargs: Any)

Bases: plesty.lib.ui.panel.Panel

Sub-window rendering one monitor.

The panel is toolkit-free until it is built: constructing and describing it needs no GUI, which is what lets a headless test cover a shell’s composition.

Wrap monitor into a dockable panel.

Parameters:

monitor (plesty.lib.monitor.base_monitor.Monitor) – The live view to render; its name and title become the panel’s unless overridden.
theme (Optional[plesty.lib.ui.theme.Theme]) – Palette for the plot; None loads the packaged theme.
**kwargs (Any) – Forwarded to Panel (name, title, area, floating, closable, min_width, min_height).

kind: ClassVar[str] = 'monitor': Panel category, used for layout keys and styling hooks.

monitor

theme = None

renderer: Any = None

build(parent: Any = None) → Any

Create the plot widget and attach it to the monitor.

Parameters:: parent (Any) – The parent widget provided by the shell.
Returns:: The plot widget.
Return type:: Any

tick() → None

Drain the monitor’s source; every new frame redraws immediately.

Return type:: None

status() → str

Return the monitor’s status line.

Returns:: The text the monitor wants shown in the title bar.
Return type:: str

close() → None

Detach the renderer and close the monitor’s source.

Return type:: None

describe() → dict[str, Any]

Return the panel description including the monitor it shows.

Returns:: The panel’s placement plus describe().
Return type:: dict[str, Any]

plesty.lib.ui.DOCK_AREAS: tuple[str, Ellipsis] = ('left', 'right', 'top', 'bottom')

class plesty.lib.ui.Panel(*, name: str | None = None, title: str | None = None, area: str = 'right', floating: bool = False, closable: bool = True, weight: float = 1.0, min_width: int | None = None, min_height: int | None = None)

Bases: abc.ABC

Base class for the dockable units of a Shell.

Subclasses implement build() and usually tick(). The panel owns its widget; the shell owns where the widget sits, and remembers that placement between sessions through name.

Configure how the shell should place this panel.

Parameters:

name (Optional[str]) – Stable identifier used as the layout key; must be unique within a shell. Defaults to the class name.
title (Optional[str]) – Title shown in the panel’s bar; defaults to name.
area (str) – Initial docking area — one of DOCK_AREAS.
floating (bool) – Start as a free-floating window instead of docked.
closable (bool) – Allow the operator to close the panel (it can always be brought back from the shell’s Panels menu).
weight (float) – Share of the area’s space this panel starts with, relative to its neighbours: a plot 3, a readout strip 1. Only the initial arrangement — the operator resizes from there, and a saved layout overrides it.
min_width (Optional[int]) – Minimum widget width in pixels.
min_height (Optional[int]) – Minimum widget height in pixels.

Raises:

ValueError – If area is not a known docking area.

kind: ClassVar[str] = 'panel': Panel category, used for layout keys and styling hooks.

name = 'Panel'

title = 'Panel'

area = 'right'

floating = False

closable = True

weight = 1.0

min_width = None

min_height = None

_widget: Any = None

abstractmethod build(parent: Any = None) → Any

Create and return the panel’s widget.

Called once, when the panel is added to a shell. Toolkit imports belong inside this method, so that constructing a panel — and describing it, and testing it — needs no GUI installed.

Parameters:: parent (Any) – The parent widget the shell provides.
Returns:: The widget to show inside the sub-window.
Return type:: Any

tick() → None

Advance the panel on the shell’s clock.

Called at the shell’s refresh interval on the GUI thread. Implementations must return quickly: drain a source, redraw, and nothing more.

Return type:: None

status() → str

Return the one-line status shown in the panel’s title bar.

Returns:: The status text; empty by default.
Return type:: str

close() → None

Release whatever the panel holds; called when the shell shuts down.

Return type:: None

property widget: Any

The built widget, or None before the panel was added to a shell.

Return type:: Any

ensure_widget(parent: Any = None) → Any

Build the widget on first use and return it.

Parameters:: parent (Any) – The parent widget passed to build().
Returns:: The panel’s widget.
Return type:: Any

describe() → dict[str, Any]

Return a JSON-serializable description of this panel.

Returns:: Identity and placement, as stored in a saved layout.
Return type:: dict[str, Any]

plesty.lib.ui.ASSETS = 'plesty.lib.ui.assets'

class plesty.lib.ui.Theme

Resolved design tokens plus the stylesheet built from them.

Variables:

name – Theme identifier, e.g. "plesty-dark".
tokens – Token name → hex colour.
series – Token names cycled for successive traces of a view.
colormap – Hex stops of the image/heatmap colour map, dark to bright.
state – Semantic state name → token name (running, idle, error, …).

name: str = 'plesty-dark'

tokens: dict[str, str]

series: list[str] = []

colormap: list[str] = []

state: dict[str, str]

classmethod load(palette: str | pathlib.Path | None = None) → Theme

Load the packaged palette, or a custom one from disk.

Parameters:: palette (Optional[str | pathlib.Path]) – Path to a JSON palette with the same keys as the packaged palette.json; None loads the packaged one.
Returns:: The resolved theme.
Return type:: Theme

color(token: str, default: str | None = None) → str

Return the hex colour of a design token.

Parameters:

token (str) – Token name ("cyan", "violet", "muted", …) or a literal #rrggbb value, which is passed through.
default (Optional[str]) – Returned when the token is unknown; without it an unknown token resolves to a glaring magenta rather than failing silently mid-experiment.

Returns:

The hex colour.

Return type:

str

series_color(index: int) → str

Return the colour of the index-th trace of a view.

Parameters:: index (int) – Zero-based trace index; wraps around the series list.
Returns:: The hex colour.
Return type:: str

state_color(state: str) → str

Return the colour marking a run or device state.

Parameters:: state (str) – State name, e.g. "running", "error", "idle".
Returns:: The hex colour; unknown states fall back to the muted text colour.
Return type:: str

stylesheet(source: str | pathlib.Path | None = None) → str

Return the Qt stylesheet with every {{token}} substituted.

Parameters:: source (Optional[str | pathlib.Path]) – Path to a custom .qss template; None uses the packaged shell.qss.
Returns:: The rendered stylesheet.
Return type:: str