roboto.experimental.boards.definition#

Module Contents#

class roboto.experimental.boards.definition.BoardCalendar(/, **data)#

Bases: _DefinitionPart

The time zone a board reads its times in, and the day its weeks start on.

The Roboto web app shows every time on the board in this zone, and divides time into days, weeks and other calendar periods in it, with weeks beginning on week_start: for a chart’s time units and weekly groups, for the rows a click on one of those periods selects, and for the periods of a metric aggregate. The bounds of a custom time_range, each a date ("2026-09-06") or a date and time written without a zone or offset ("2026-09-06T14:00"), are read in this zone too.

Parameters:: data (Any)

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

time_zone: str = 'UTC'#: The zone’s name in the IANA time zone database, in the database’s letter case, such as "America/Los_Angeles". This model does not check the name. The web app reports the definition as invalid when the name is not in the database, is an offset such as "+05:30", is written in another letter case such as "america/los_angeles", or is CET, EET, MET or WET, which Roboto reads as fixed offsets without daylight saving time when it aggregates metrics; name such a zone by area and location instead, such as "Europe/Paris" for CET.

week_start: roboto.domain.metrics.record.DayOfWeek#: The day the board’s weeks start on.

class roboto.experimental.boards.definition.BoardColumnControlDomain(/, **data)#

Bases: _DefinitionPart

A value control’s choices taken from the distinct values of a column in the result of the one stage the control reads.

Parameters:: data (Any)

column: str#: The column of the input stage’s result whose distinct values the control lists.

kind: Literal['column']#: Marks the choices as a column’s values.

class roboto.experimental.boards.definition.BoardControlFilterBody(/, **data)#

Bases: _DefinitionPart

Keeps the rows of the stage’s first input that match the values chosen in the value control it reads second.

The stage’s inputs name the data stage and then the value control. A control that is not required and has no value filters nothing.

Parameters:: data (Any)

column: str#: The column of the data stage’s result that the filter compares with the chosen values.

columnHolds: Literal['value', 'entity-id'] | None = None#

value, a value of the control’s type, which matches when it is a chosen value; or entity-id, the id of an entity of the control’s entity-field domain, which matches when that entity’s field holds a chosen value. value when absent.

Type:: What the column holds

kind: Literal['control-filter']#: Marks the stage as a control-filter.

class roboto.experimental.boards.definition.BoardControlOption(/, **data)#

Bases: _DefinitionPart

One choice a value control lists, and the label the control shows for it.

Parameters:: data (Any)

label: str#: The text the control shows for the choice.

value: dict[str, Any]#: The value as a tagged JSON object, for example {"type": "string", "value": "north"}.

class roboto.experimental.boards.definition.BoardDefinition(/, **data)#

Bases: _DefinitionPart

A board definition whose outline is checked as the model is built.

The platform refuses a definition whose top level this model refuses, with the entries of panels and stages set aside, and stores the panels and stages in it as given; the web app decides what a definition means when it opens the board. This model checks a definition’s outline:

the top-level keys, the calendar’s members, and the keys every panel, stage, section and selection carries;
the members of a control or control-filter stage, and how many inputs it names;
that no two stages share an id;
that each stage a panel or another stage names is declared;
that a control-filter reads a data stage (a stage that is not a control), then a value control.

It does not check what lies deeper, such as a stage’s query or a chart’s specification, nor whether the calendar’s time zone is one the web app accepts, so the web app can still report a definition this model accepts, or a panel or stage in it, as invalid.

At the top level and in the calendar, a key the models do not declare is refused, as the web app refuses it. Elsewhere below the top level, such a key is kept as given. An optional key left as None is omitted when the model is serialized.

Parameters:: data (Any)

calendar: BoardCalendar | None = None#: The time zone the board reads its times in, and the day its weeks start on. Without one, the board reads its times in UTC and its weeks start on Monday.

model_config#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

panels: list[BoardPanel]#: The panels on the canvas. May be empty.

schema_version: Literal[1] = 1#: Version of the definition’s schema.

sections: list[BoardSection] | None = None#: Titled regions of the canvas.

selections: list[BoardSelection] | None = None#: Named selections that panels publish to and filter by.

stages: list[BoardStage] | None = None#: The stages that provide the panels’ data, and the controls above the canvas.

time_range: str | dict[str, Any]#

a preset such as "90d", or a JSON object describing a custom or relative range.

Type:: The time range the board opens with

title: str | None = None#: The board’s title. The platform keeps a board’s name equal to a title that is a non-empty string.

validate_stage_ids_and_references()#

Reject a reused stage id, a reference to an undeclared stage, and a control-filter reading the wrong stages.

A control-filter reads a data stage, then a value control. A control-filter input that names no stage, or an id several stages share, is reported only as an undeclared or a reused stage id.

Return type:: BoardDefinition

class roboto.experimental.boards.definition.BoardEntityFieldControlDomain(/, **data)#

Bases: _DefinitionPart

A value control’s choices taken from the values a field holds on one kind of entity.

Parameters:: data (Any)

field: str#: The field, for example name, or custom.<field_name> for a custom field.

kind: Literal['entity-field']#: Marks the choices as an entity field’s values.

target: str#: The kind of entity, for example sessions or devices.

class roboto.experimental.boards.definition.BoardFieldControlBody(/, **data)#

Bases: _DefinitionPart

A control above the canvas in which a viewer chooses which field a chart or query reads.

The fields it offers belong to exactly one kind of entity (target) or one topic (topic). The stage reads no input.

Parameters:: data (Any)

default: str | None#: The field the control holds when the board opens and the board’s URL has no control.<name> key for the control, and after the control is reset to its default from the control bar.

kind: Literal['field-control']#: Marks the stage as a field control.

label: str | None = None#: The control’s caption.

options: list[BoardFieldControlOption] | None#: The fields the control lists, when it lists fewer than its entity or topic has.

target: str | None#: The kind of entity whose fields the control offers, for example sessions.

topic: str | None#: The name of the topic whose fields the control offers.

validate_target_or_topic()#

Reject a field control that declares both or neither of a target and a topic.

Return type:: BoardFieldControlBody

class roboto.experimental.boards.definition.BoardFieldControlOption(/, **data)#

Bases: _DefinitionPart

One field a field control lists, and the label the control shows for it.

Parameters:: data (Any)

label: str#: The text the control shows for the field.

value: str#: The field, for example name, custom.<field_name> or a dotted topic field path.

class roboto.experimental.boards.definition.BoardPanel(/, **data)#

Bases: _DefinitionPart

A panel on the board’s canvas: a chart, a table, or a map.

Only the keys every panel carries are checked. Everything else a panel holds, such as its title, its placement on the canvas and a chart’s spec, is kept as given and is not checked.

Parameters:: data (Any)

bindings: list[BoardPanelBinding]#: The stage results the panel draws. A panel has at least one.

id: str#: Identifies the panel within the board.

kind: str#: What the panel draws, for example chart, table or map.

class roboto.experimental.boards.definition.BoardPanelBinding(/, **data)#

Bases: _DefinitionPart

One stage’s result, under the name a panel draws it by.

Parameters:: data (Any)

name: str#: The name the panel knows the result by. A chart’s specification refers to the result by this name.

stage: str#: The id of the stage whose result the panel draws.

class roboto.experimental.boards.definition.BoardSection(/, **data)#

Bases: _DefinitionPart

A titled region of the canvas. A panel joins a section by naming the section in its own placement.

Parameters:: data (Any)

height: _Number#: Height of the region, in canvas units.

id: str#: Identifies the section within the board.

title: str#: The title shown on the region.

width: _Number#: Width of the region, in canvas units.

x: _Number#: Horizontal position of the region’s left edge, in canvas units.

y: _Number#: Vertical position of the region’s top edge, in canvas units.

class roboto.experimental.boards.definition.BoardSelection(/, **data)#

Bases: _DefinitionPart

A named selection that panels publish to and filter by.

Parameters:: data (Any)

keys: list[dict[str, Any]]#: The values a selection carries, each a JSON object with a key and a valueType. May be empty.

name: str#: The name panels refer to the selection by.

class roboto.experimental.boards.definition.BoardStage(/, **data)#

Bases: _DefinitionPart

One stage of the board’s data: a query of the platform, a transformation of other stages’ results, a control above the canvas whose result is the value a viewer chooses, or a filter of a stage’s rows by such a control.

Parameters:: data (Any)

body: BoardValueControlBody | BoardFieldControlBody | BoardControlFilterBody | BoardStageBody#: What the stage does.

id: str#: Identifies the stage within the board, so no two stages of a board share an id. Panels and other stages refer to the stage by it. Starts with a letter or digit, and holds only letters, digits, underscores and hyphens.

inputs: list[str] | None = None#: The id of each stage this stage reads.

name: str#: The name the stage’s result goes by, for example as a table in another stage’s SQL. Starts with a letter or digit, and holds only letters, digits, underscores and hyphens. A control’s name is also what a $name reference names, so it starts with a letter and holds only letters, digits and underscores.

classmethod read_body_as_its_kind(body)#

Read a body as the model of its kind, so a mistake in it is reported at the key it was made in.

Parameters:: body (Any)
Return type:: Any

validate_control_name_and_inputs()#

Reject a control name a $name reference cannot hold, and a control or control-filter with wrong inputs.

A control reads no input, except a value control whose choices are a column’s values, which reads the one stage holding the column. A control-filter reads a data stage and then a value control.

Return type:: BoardStage

class roboto.experimental.boards.definition.BoardStageBody(/, **data)#

Bases: _DefinitionPart

What a stage does, for a kind of stage this module has no model of.

Each kind of stage has its own keys, which are kept as given and are not checked. A control or a control-filter is read as BoardValueControlBody, BoardFieldControlBody or BoardControlFilterBody instead.

Parameters:: data (Any)

kind: str#: The kind of stage, for example entity.query or sql.

class roboto.experimental.boards.definition.BoardStaticControlDomain(/, **data)#

Bases: _DefinitionPart

A value control’s choices listed in the definition.

Parameters:: data (Any)

kind: Literal['static']#: Marks the choices as listed here.

options: list[BoardControlOption]#: The choices the control lists, in order.

class roboto.experimental.boards.definition.BoardValueControlBody(/, **data)#

Bases: _DefinitionPart

A control above the canvas in which a viewer chooses one or several values of a type.

The stage’s result is the chosen values. A control-filter stage that reads it keeps the rows of its data stage that match the choice, and SQL text, stage expressions, chart specifications and panel titles read the choice as $name, where name is the stage’s name. The stage reads no input, except the one stage whose column a BoardColumnControlDomain lists.

Parameters:: data (Any)

default: dict[str, Any] | list[dict[str, Any]] | None = None#: The value the control holds when the board opens and the board’s URL has no control.<name> key for the control, and after the control is reset to its default from the control bar or by the reset operation of a control interaction: one tagged JSON object, or a list of them when multi is true.

domain: BoardValueControlDomain | None = None#: Where the control’s choices come from. Absent, the viewer types the value.

kind: Literal['value-control']#: Marks the stage as a value control.

label: str | None = None#: The control’s caption. Absent or blank, the caption is the display name of the entity field the control takes its choices from (a custom field’s display name, a catalog field’s display name such as “Device ID” for device_id, or a metadata path as written), or else the stage’s name.

multi: bool | None = None#: Whether the viewer may choose several values. False when absent.

required: bool | None = None#: Whether the stages and panels that read the control wait for a value. False when absent, and a control that is not required and has no value filters nothing.

validate_default_matches_multi()#

Reject a default that is a list when the control holds one value, or one value when it holds several.

Return type:: BoardValueControlBody

valueType: dict[str, Any]#: The type of the values the control holds, as a JSON object with a type, for example {"type": "string"}.

roboto.experimental.boards.definition.BoardValueControlDomain#: Where a value control’s choices come from.

roboto.experimental.boards.definition.check_definition_top_level(definition)#

Refuse a board definition whose top level BoardDefinition refuses.

The definition is checked as BoardDefinition checks it, except for the entries of panels and stages, which are not checked. It is refused for an unknown top-level key, a missing time_range or panels, a panels that is not a list, a stages, sections or selections that is neither a list nor null, a title that is neither a string nor null, a time_range that is neither a string nor an object, a schema_version other than 1, a calendar that is neither an object nor null or has a member other than time_zone and week_start, a week_start that is not a day’s name, or a malformed section or selection. The web app reads each panel and stage on its own: it shows a panel or stage that fails beside the rest of the board and saves it as written, so a person can repair a board one panel or stage at a time. A mistake at the top level leaves the web app nothing to show.

Parameters:: definition (dict[str, Any]) – The board definition as a JSON object.
Raises:: pydantic.ValidationError – BoardDefinition refuses the definition’s top level.
Return type:: None