Client

Declarative UI

ui.UI is the preferred way to declare application UI structure. It mirrors the declarative Tags API: define elements as class attributes, declare the UI and tags classes on your application via ui_cls and tags_cls, and keep dynamic values tag-backed where appropriate. By default, tag-backed fields serialize to the compact frontend lookup format such as $tag.voltage:number rather than the expanded object form.

class pydoover.ui.UI(config: Schema, tags: Tags, app_key: str)[source]

async setup()[source]: Mutate this UI instance before it is bound and installed.

Static declarative UI example:

from pydoover import ui
from pydoover.tags import Number, Tags

class MyTags(Tags):
    voltage = Number()

class MyUI(ui.UI):
    voltage = ui.NumericVariable(
        "voltage",
        "Voltage",
        curr_val=MyTags.voltage,
    )

Explicit tag helper example:

from pydoover import ui

class MyUI(ui.UI):
    voltage = ui.NumericVariable(
        "voltage",
        "Voltage",
        curr_val=ui.tag_ref("voltage", tag_type="number"),
    )

Application wiring example:

from pydoover.docker import Application
from pydoover.config import Schema

class MyApp(Application):
    config_cls = Schema
    tags_cls = MyTags
    ui_cls = MyUI

Config-aware setup example:

from pydoover import ui
from pydoover.tags import Number, String, Tags

class ConfiguredTags(Tags):
    voltage = Number()

    async def setup(self, config):
        if config.show_extra.value:
            self.add_tag("extra", String())

class ConfiguredUI(ui.UI):
    voltage = ui.NumericVariable(
        "voltage",
        "Voltage",
        curr_val=ConfiguredTags.voltage,
    )

    async def setup(self, config, tags):
        if config.show_extra.value:
            self.add_element("extra", ui.TextVariable("extra", "Extra"))

Legacy note: Existing instance-based UI construction through UIManager.add_children(), set_ui(), and decorator-generated elements remains supported.

Elements

Elements are the building blocks of the Doover UI. They represent various components that can be used to create user interfaces for applications.

Element is the base class that all other elements inherit from. Following are some miscellaneous elements that are commonly used in applications.

class pydoover.ui.Element(display_name: str, is_available=<class 'pydoover.ui.misc.NotSet'>, help_str: str = <class 'pydoover.ui.misc.NotSet'>, verbose_str: str = <class 'pydoover.ui.misc.NotSet'>, show_activity: bool = True, form=<class 'pydoover.ui.misc.NotSet'>, graphic: str = <class 'pydoover.ui.misc.NotSet'>, layout: str = <class 'pydoover.ui.misc.NotSet'>, component_url: str = <class 'pydoover.ui.misc.NotSet'>, position: int = <class 'pydoover.ui.misc.NotSet'>, conditions: dict[str] = <class 'pydoover.ui.misc.NotSet'>, hidden: Any = False, units: str = <class 'pydoover.ui.misc.NotSet'>, icon: str = <class 'pydoover.ui.misc.NotSet'>, colour: str = <class 'pydoover.ui.misc.NotSet'>, name: str = None, **kwargs)[source]

Base class for UI elements.

name

The name of the UI element.

Type:: str

display_name

The display name of the UI element.

Type:: str, optional

is_available

Indicates if the UI element is available.

Type:: bool, optional

help_str

A help string for the UI element.

Type:: str, optional

verbose_str

A verbose string for the UI element.

Type:: str, optional

show_activity

Whether to show activity for the UI element.

Type:: bool

form

The form associated with the UI element.

Type:: str, optional

graphic

The graphic associated with the UI element.

Type:: str, optional

layout

The layout associated with the UI element.

Type:: str, optional

component_url

The URL for a remote component associated with the UI element.

Type:: str, optional

position

The position of the UI element in the UI.

Type:: int, optional

conditions

Conditions under which the UI element is displayed.

Type:: dict[str, Any], optional

hidden

Whether the UI element is hidden.

Type:: bool

to_dict() → dict[str, Any][source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.ConnectionInfo(name: str = 'connectionInfo', connection_type: ConnectionType = ConnectionType.constant, connection_period: int | None = None, next_connection: int | None = None, offline_after: int | None = None, allowed_misses: int | None = None, **kwargs)[source]

Connection Info

Parameters:

name (str)
connection_type (ConnectionType)
connection_period (int) – The expected time between connection events (seconds) - only applicable for “periodic”
next_connection (int) – Expected time of next connection (seconds after shutdown)
offline_after (int) – Show as offline if disconnected for more than x secs

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.Multiplot(title: str, series: list[Series], earliest_data_time: datetime | None = None, default_zoom: str | None = None, default_range_view: str | None = None, **kwargs)[source]

Represents a MultiPlot UI Element.

Parameters:

display_name (str) – The display name of the multiplot.
series (list[Series]) – A list of Series objects defining the plot series.
earliest_data_time (datetime, optional) – The earliest time for which data is available in the multiplot.
title (str, optional) – The title of the multiplot.
default_zoom (str, optional) – The default zoom level for the multiplot.
default_range_view (str, optional) – Initial range view for the plot ("line", "zone" or "off"). Only applies when exactly one series defines ranges or thresholds.

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

Multiplot now prefers the Doover 2.0 record-based series schema. Legacy list-based series definitions remain supported as deprecated input and are normalized to the newer payload shape on serialization.

class pydoover.ui.RemoteComponent(display_name: str, component_url: str, children: list[Element] = None, **kwargs)[source]

Represents a remote component in the UI.

Parameters:

name (str) – The name of the remote component.
display_name (str) – The display name of the remote component.
component_url (str) – The URL of the remote component.

Interactions

Interactions are a form of UI element that allows users to interact with the application. They can be used to trigger actions, change state, or provide input. Use Button and Select for new code. Action, SlimCommand, and StateCommand remain as compatibility aliases for older Doover 1.0 UI payloads.

class pydoover.ui.Interaction(display_name: str, value: str = <class 'pydoover.ui.misc.NotSet'>, default: Any = <class 'pydoover.ui.misc.NotSet'>, show_activity: bool = <class 'pydoover.ui.misc.NotSet'>, requires_confirm: bool | ConfirmDialog = <class 'pydoover.ui.misc.NotSet'>, global_interaction: bool = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

Base class for all UI interactions.

Interactions are elements that can be interacted with by the user, such as buttons, sliders, and text inputs.

Parameters:

name (str) – The name of the interaction, used to identify it in the UI.
display_name (str, optional) – The display name of the interaction, shown in the UI.
value (Any) – The current value of the interaction. Defaults to NotSet.
default (Any) – The default value for the interaction, used if current_value is NotSet.
callback (callable, optional) – A callback function that is called when the interaction value changes.
transform_check (callable, optional) – A function to transform and check the new value before setting it. Defaults to None.
show_activity (bool, optional) – Whether to show this interaction in the activity log. Defaults to None which uses the site default.

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.Button(display_name: str, disabled: bool = <class 'pydoover.ui.misc.NotSet'>, label_string: str = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

Represents a UI button.

Parameters:

display_name (str) – The display name of the action, shown in the UI.
disabled (bool) – Whether the button appears disabled in the UI. Defaults to False.

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.Select(display_name: str | None = None, options: list[Option] | None = None, **kwargs)[source]

Represents a selectable input in the UI.

Parameters:

display_name (str, optional) – The display name of the state command, shown in the UI.
options (list[Option]) – A list of options that the user can select from. Each option is an instance of the Option class. If not provided, an empty list will be created.

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.WarningIndicator(*args, **kwargs)[source]

Represents a warning indicator in the UI.

Parameters:

name (str) – The name of the warning indicator, used to identify it in the UI.
display_name (str) – The display name of the warning indicator, shown in the UI.
can_cancel (bool) – Whether the warning can be cancelled by the user. Defaults to True.

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.Slider(display_name: str, min_val: int = 0, max_val: int = 100, step_size: float = 0.1, dual_slider: bool = True, inverted: bool = True, colours: str = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

Represents a slider in the UI.

Parameters:

name (str) – The name of the slider, used to identify it in the UI.
display_name (str, optional) – The display name of the slider, shown in the UI.
min_val (int) – The minimum value of the slider. Defaults to 0.
max_val (int) – The maximum value of the slider. Defaults to 100.
step_size (float) – The step size of the slider. Defaults to 0.1.
dual_slider (bool) – Whether the slider has a dual handle. Defaults to True.
inverted (bool) – Whether the slider is inverted (i.e., moves left for higher values). Defaults to True.
icon (str, optional) – An optional icon to display with the slider.
colours (str, optional) – An optional string representing colours for the slider, such as “red,green,blue”.

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

Variables

Variables are read-only elements that can be used to display information in the UI, and are expected to be updated through the lifecycle of an application. Some common examples include the solar voltage, pump state or humidity reading.

class pydoover.ui.Variable(display_name: str, var_type: str, value: Any = <class 'pydoover.ui.misc.NotSet'>, precision: int = <class 'pydoover.ui.misc.NotSet'>, ranges: list[Range] = <class 'pydoover.ui.misc.NotSet'>, thresholds: list[Threshold] = <class 'pydoover.ui.misc.NotSet'>, default_range_view: str = <class 'pydoover.ui.misc.NotSet'>, earliest_data_time: datetime = <class 'pydoover.ui.misc.NotSet'>, default_range_since: timedelta = <class 'pydoover.ui.misc.NotSet'>, default_zoom: str = <class 'pydoover.ui.misc.NotSet'>, log_threshold: float = <class 'pydoover.ui.misc.NotSet'>, graphable: bool = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

Base class for UI variables. All variables should inherit from this class.

A variable is a read-only value in the UI which is updated by a device periodically.

Parameters:

display_name (str) – The display name of the variable.
var_type (str) – The type of the variable (e.g., “float”, “string”, “bool”, “time”).
value (Any) – The current value of the variable. If not set, defaults to NotSet.
precision (int, optional) – The number of decimal places to round the current value to. Defaults to None.
ranges (list[Range]) – A list of ranges associated with the variable, used for display purposes.
thresholds (list[Threshold], optional) – Thresholds drawn as horizontal lines on the variable’s plot.
default_range_view (str, optional) – The initial range view ("line", "zone" or "off") for the plot’s hamburger menu. If unset, the site falls back to "line" when thresholds are defined, "zone" when ranges are defined, otherwise "off".
earliest_data_time (datetime, optional) – The earliest time for which data is available for this variable. Defaults to None.
default_range_since (timedelta, optional) – The timedelta which defines how many seconds the plot should show on load. Defaults to a week if not set.
default_zoom (str, optional) – The default zoom setting for the inbuilt plot viewer. Defaults to None.
log_threshold (float, optional) – The change threshold for logging the variable. Defaults to None (no threshold). 0 means log every change.

to_dict() → dict[str, Any][source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.NumericVariable(display_name: str, value: Any = None, precision: int = <class 'pydoover.ui.misc.NotSet'>, ranges: list[Range] = <class 'pydoover.ui.misc.NotSet'>, thresholds: list[Threshold] = <class 'pydoover.ui.misc.NotSet'>, default_range_view: str = <class 'pydoover.ui.misc.NotSet'>, form: Widget = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

Represents a numeric variable in the UI, which can be an integer or a float.

Parameters:

name (str) – The name of the variable.
display_name (str) – The display name of the variable.
curr_val (Union[int, float], optional) – The current value of the variable. Defaults to None.
precision (int, optional) – The number of decimal places to round the current value to. Defaults to None.
ranges (list[Range], optional) – A list of ranges associated with the variable, used for display purposes. Defaults to None.
thresholds (list[Threshold], optional) – Thresholds drawn as horizontal lines on the variable’s plot.
default_range_view (str, optional) – Initial range view for the plot ("line", "zone" or "off").
form (Widget, optional) – A widget or string representing the form for this variable. Defaults to None.

to_dict() → dict[str, Any][source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.TextVariable(display_name: str, value: str, **kwargs)[source]

Represents a text variable in the UI, which can be used to display or input string values.

Parameters:

display_name (str) – The display name of the variable.
value (str, optional) – The current value of the variable. Defaults to None.

class pydoover.ui.BooleanVariable(display_name: str, value: bool, log_threshold: float | None = 0, **kwargs)[source]

Represents a boolean variable in the UI, which can be used to represent true/false values.

Parameters:

display_name (str) – The display name of the variable.
curr_val (bool, optional) – The current value of the variable. Defaults to None.
log_threshold (float, optional) – The change threshold for logging the variable. Defaults to 0 (log every change). None means don’t log on change.

class pydoover.ui.DateTimeVariable(display_name: str, value: datetime, **kwargs)[source]

Represents a date/time variable in the UI, which can be used to display or input datetime values.

Parameters:

name (str) – The name of the variable.
display_name (str) – The display name of the variable.
value (datetime, optional) – The current value of the variable, which can be a datetime object or a timestamp (int). Defaults to None.

Parameters

Parameters are input fields with various validations for different types. They expect a callback that is executed when a user modifies the input. Use FloatInput, TextInput, DatetimeInput, and TimeInput for new code. The *Parameter classes remain available as deprecated compatibility aliases.

class pydoover.ui.Parameter(display_name: str, value: str = <class 'pydoover.ui.misc.NotSet'>, default: Any = <class 'pydoover.ui.misc.NotSet'>, show_activity: bool = <class 'pydoover.ui.misc.NotSet'>, requires_confirm: bool | ConfirmDialog = <class 'pydoover.ui.misc.NotSet'>, global_interaction: bool = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

Base class for UI parameters. All parameters should inherit from this class.

type = NotImplemented

class pydoover.ui.FloatInput(display_name, min_val: int | float = <class 'pydoover.ui.misc.NotSet'>, max_val: int | float = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

A numeric input that can be used to represent both integer and float values.

name

The name of the parameter.

Type:: str

display_name

The display name of the parameter.

Type:: str

min

The minimum value for the parameter. Defaults to None.

Type:: Union[int, float], optional

max

The maximum value for the parameter. Defaults to None.

Type:: Union[int, float], optional

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.TextInput(display_name, is_text_area: bool = False, **kwargs)[source]

A text input that can be used to represent string values for a user to modify.

This can either be inline or a large form text area, depending on the is_text_area parameter.

display_name

The display name of the parameter.

Type:: str

is_text_area

Whether the text parameter should be displayed as a text area. Defaults to False.

Type:: bool

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.DatetimeInput(display_name: str, include_time: bool = False, **kwargs)[source]

A datetime input that can be used to request date and time values from a user.

Internally, all datetime values are stored as epoch seconds in UTC

name

The name of the parameter.

Type:: str

display_name

The display name of the parameter.

Type:: str

include_time

Whether to include time in the datetime picker. Defaults to False.

Type:: bool

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.TimeInput(display_name: str, **kwargs)[source]: A time-only input.

class pydoover.ui.BooleanParameter(name, display_name, **kwargs)[source]

A boolean parameter that can be used to represent true/false values.

Warning

This is not implemented in the doover site yet, and will raise a NotImplementedError if used!

name

The name of the parameter.

Type:: str

display_name

The display name of the parameter.

Type:: str

Decorators

Decorators can be used as a shortcut to add UI interactions with an associated callback function.

Submodules

class pydoover.ui.Container(display_name: str, children: list[Element] = None, **kwargs)[source]

Represents a container for UI elements, such as a submodule or application.

This class can hold multiple child elements and provides methods to manage them.

Generally, this class is not called by a user directly, but rather through the Submodule or Application classes.

Parameters:

display_name (str) – The display name of the container, used for user interface representation.
children (list[Element]) – A list of child elements contained within this container.

add_children(*children: Element)[source]

Adds one or more child elements to this container.

This method will automatically assign a position to each child if it does not already have one.

Warning

You should generally only call this method once during setup of the container, when you generate all elements and add them at once. Old applications may call this multiple times during setup, but that is not the suggested best practice going forward.

Parameters:: *children – Child elements to add to this container. They must be of type pydoover.ui.Element

clear_children()[source]

Clears all child elements from this container.

You probably don’t want or need to call this method.

remove_children(*children: Element)[source]

Removes one or more child elements from this container.

Warning

Best practice prefers setting hidden=True on elements instead of removing them from the container.

Parameters:: *children – Child elements to remove from this container. They must be of type pydoover.ui.Element

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.Submodule(display_name: str, children: list[Element] = None, status: str = <class 'pydoover.ui.misc.NotSet'>, is_collapsed: bool = <class 'pydoover.ui.misc.NotSet'>, default_open: bool = <class 'pydoover.ui.misc.NotSet'>, **kwargs)[source]

Represents a submodule within a UI application, which can contain other elements and has a status.

Submodules are useful for grouping logical components of an application together, but be careful not to overuse them as they can be burdensome on a user!

Parameters:

name (str) – The name of the submodule, used for identification.
display_name (str) – The display name of the submodule, used for user interface representation.
children (list[Element], optional) – A list of child elements contained within this submodule. Defaults to an empty list.
status (str, optional) – A status string representing the current state of the submodule. Defaults to None.
is_collapsed (bool, optional) – Whether the submodule is initially collapsed in the UI. Defaults to False.

add_children(*children: Element)

Adds one or more child elements to this container.

This method will automatically assign a position to each child if it does not already have one.

Warning

You should generally only call this method once during setup of the container, when you generate all elements and add them at once. Old applications may call this multiple times during setup, but that is not the suggested best practice going forward.

Parameters:: *children – Child elements to add to this container. They must be of type pydoover.ui.Element

clear_children()

Clears all child elements from this container.

You probably don’t want or need to call this method.

remove_children(*children: Element)

Removes one or more child elements from this container.

Warning

Best practice prefers setting hidden=True on elements instead of removing them from the container.

Parameters:: *children – Child elements to remove from this container. They must be of type pydoover.ui.Element

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

class pydoover.ui.Application(*args, **kwargs)[source]

Represents a UI application element.

This is generally not invoked by the user, but is used to represent and store all UI elements for an application.

variant

The variant of the application, used to display applications differently. Defaults to stacked. Valid options are stacked, submodule.

Type:: str, optional

to_dict()[source]

Convert the element to a dictionary representation.

Returns:: A dictionary representation of the UI element. This is used to serialize the element for the site API.
Return type:: dict[str, Any]

Miscellaneous

class pydoover.ui.Colour[source]

A class representing a colour, which can be used in various UI elements.

This class provides a set of predefined colour constants that can be used directly, or allows conversion from hex strings and arbitrary strings to a colour representation.

In reality, the Doover Site will accept any HTML colour name or hex string, but this class allows for future implementations of colour objects if needed.

blue

Type:: ClassVar[str]

yellow

Type:: ClassVar[str]

red

Type:: ClassVar[str]

green

Type:: ClassVar[str]

magenta

Type:: ClassVar[str]

limegreen

Type:: ClassVar[str]

tomato

Type:: ClassVar[str]

orange

Type:: ClassVar[str]

purple

Type:: ClassVar[str]

grey

Type:: ClassVar[str]

classmethod from_hex(hex_string: str) → str[source]

Convert a hex string to a colour string.

This method takes a hex string (e.g., “#FF5733”) that can be used where a Colour object is accepted.

classmethod from_string(value: str) → str[source]

Convert an arbitrary string to a Colour object.

This method takes an HTML colour name (e.g. brown) and allows it to be used where a Colour object is accepted.

class pydoover.ui.Range(label: Any = None, min_val: Any = None, max_val: Any = None, colour: Any = 'blue', show_on_graph: bool = True)[source]

Represents a range of values with associated properties for UI display.

label

A label for the range, used for display purposes.

Type:: str

min

The minimum value of the range.

Type:: Union[int, float]

max

The maximum value of the range.

Type:: Union[int, float]

colour

The colour associated with the range, used for display.

Type:: Colour

show_on_graph

Whether to show this range on the graph.

Type:: bool

class pydoover.ui.Option(display_name: Any)[source]

Represents an option for a UI element, such as a dropdown or selection list.

display_name

The display name of the option, used for user interface representation.

Type:: str

class pydoover.ui.Widget[source]

Base class for UI widgets, which can be used to represent various UI elements.

There are two main types of widgets: linear and radial gauges.

linear

Represents a linear gauge widget.

Type:: ClassVar[str]

radial

Represents a radial gauge widget.

Type:: ClassVar[str]

classmethod from_string(value: str) → str[source]

Convert an arbitrary string to a Widget object.

This method takes a string (e.g. linearGauge) and allows it to be used where a Widget object is accepted.

This allows for future implementations of Widget objects if needed.