flow: structured dtypes, and the widgets that read them
A series, record or list message declares its shape instead of riding DType.JSON, so a widget binds a shape rather than some JSON and a wrong binding is refused before anything runs. A list declares its item type, which is what keeps list[float] expressible for a pipeline. On top of that: an agenda over a list, a notification over a record, and a dashboard alert channel that publishes engine faults as one — so a panel can show what went wrong without a flow wiring it by hand. Also: only None means a node published nothing, a falsy value of the wrong shape is now the named error it always should have been; and the gauge's readout says its size is viewBox geometry rather than type scale.
This commit is contained in:
+105
-12
@@ -20,6 +20,11 @@ from pydantic import BaseModel, ConfigDict, Field, model_validator
|
||||
class DType(str, Enum):
|
||||
"""Serializable payload types.
|
||||
|
||||
The scalars carry what a single reading can say. The three structured ones
|
||||
are declared shapes rather than "some JSON": a widget or a downstream node
|
||||
knows what it is getting before anything runs, which is what lets the
|
||||
dashboard picker offer a message and refuse a wrong binding.
|
||||
|
||||
Binary payloads (tensors, images) will arrive later as explicitly declared
|
||||
codec fields; until then everything on the wire is JSON.
|
||||
"""
|
||||
@@ -29,10 +34,78 @@ class DType(str, Enum):
|
||||
STR = "str"
|
||||
BOOL = "bool"
|
||||
JSON = "json"
|
||||
#: ``{"lines": [{"label": str, "points": [[ts, value], ...]}], ...}``.
|
||||
#: Keys beside ``lines`` are carried through untouched — a chart's query
|
||||
#: puts the range and interval it asked for there and reads them back.
|
||||
SERIES = "series"
|
||||
#: Flat named scalars: ``{"title": "Boiler", "severity": "error"}``.
|
||||
RECORD = "record"
|
||||
#: Ordered items of one declared shape; see :attr:`MessageSpec.item`.
|
||||
LIST = "list"
|
||||
|
||||
|
||||
_JSON_TYPES = (dict, list, str, int, float, bool, type(None))
|
||||
|
||||
#: What a record may hold. Nesting is deliberately out: a record that can
|
||||
#: contain a record is a schema language, and the shape stops being readable
|
||||
#: from the declaration alone.
|
||||
_SCALARS = (str, int, float, bool)
|
||||
|
||||
#: Item types a list may declare. Recursion is refused for the same reason.
|
||||
_ITEM_TYPES = frozenset(
|
||||
{DType.FLOAT, DType.INT, DType.STR, DType.BOOL, DType.JSON, DType.RECORD}
|
||||
)
|
||||
|
||||
|
||||
def _is_number(value: Any) -> bool:
|
||||
"""A measurement. bool is an int subclass; a flag is not a number here."""
|
||||
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
||||
|
||||
|
||||
def _is_record(value: Any) -> bool:
|
||||
return isinstance(value, dict) and all(
|
||||
isinstance(key, str) and (item is None or isinstance(item, _SCALARS))
|
||||
for key, item in value.items()
|
||||
)
|
||||
|
||||
|
||||
def _is_series(value: Any) -> bool:
|
||||
"""Labelled lines of ``(timestamp, value)`` pairs.
|
||||
|
||||
Checked all the way down. That is O(n) in the number of points, but so is
|
||||
the JSON encoding every message already pays for.
|
||||
"""
|
||||
if not isinstance(value, dict) or not isinstance(value.get("lines"), list):
|
||||
return False
|
||||
return all(
|
||||
isinstance(line, dict)
|
||||
and isinstance(line.get("label"), str)
|
||||
and isinstance(line.get("points"), list)
|
||||
and all(
|
||||
isinstance(point, (list, tuple))
|
||||
and len(point) == 2
|
||||
and _is_number(point[0])
|
||||
and _is_number(point[1])
|
||||
for point in line["points"]
|
||||
)
|
||||
for line in value["lines"]
|
||||
)
|
||||
|
||||
|
||||
def _matches(dtype: DType, value: Any) -> bool:
|
||||
"""Whether one value satisfies a scalar or record type."""
|
||||
if dtype is DType.BOOL:
|
||||
return isinstance(value, bool)
|
||||
if dtype is DType.INT:
|
||||
return isinstance(value, int) and not isinstance(value, bool)
|
||||
if dtype is DType.FLOAT:
|
||||
return _is_number(value)
|
||||
if dtype is DType.STR:
|
||||
return isinstance(value, str)
|
||||
if dtype is DType.RECORD:
|
||||
return _is_record(value)
|
||||
return isinstance(value, _JSON_TYPES)
|
||||
|
||||
|
||||
class MessageSpec(BaseModel):
|
||||
"""A single port of a node, and the message it is bound to.
|
||||
@@ -42,6 +115,10 @@ class MessageSpec(BaseModel):
|
||||
:param port: The identifier the node function sees. Defaults to the last
|
||||
segment of ``name``, so unqualified flows read naturally.
|
||||
:param dtype: Payload type, validated on every message that passes through.
|
||||
:param item: The type of each item of a ``list`` port, ignored otherwise.
|
||||
Unset means ``record``, which is what the agenda and forecast widgets
|
||||
read; ``float`` is the numeric list a pipeline passes around. A list of
|
||||
lists, or of series, is refused — one declared level is the point.
|
||||
:param interval: Deliver at most every this many seconds; 0 is every time.
|
||||
On an output it holds back publishing, on an input it holds back waking
|
||||
the node. The value is never lost — state keeps the latest — only the
|
||||
@@ -57,6 +134,7 @@ class MessageSpec(BaseModel):
|
||||
name: str = ""
|
||||
port: str = ""
|
||||
dtype: DType = DType.FLOAT
|
||||
item: DType | None = None
|
||||
interval: float = Field(default=0, ge=0)
|
||||
trigger: bool = True
|
||||
|
||||
@@ -64,25 +142,36 @@ class MessageSpec(BaseModel):
|
||||
def _default_port(self) -> MessageSpec:
|
||||
if not self.port and self.name:
|
||||
object.__setattr__(self, "port", self.name.rsplit(".", 1)[-1])
|
||||
if self.item is not None and self.item not in _ITEM_TYPES:
|
||||
raise ValueError(f"a list cannot hold '{self.item.value}' items")
|
||||
return self
|
||||
|
||||
@property
|
||||
def item_dtype(self) -> DType:
|
||||
"""What each item of a ``list`` port is, declared or defaulted."""
|
||||
return self.item or DType.RECORD
|
||||
|
||||
def check(self, value: Any) -> None:
|
||||
"""Raise if ``value`` does not match this port's declared type."""
|
||||
if self.dtype is DType.BOOL:
|
||||
ok = isinstance(value, bool)
|
||||
elif self.dtype is DType.INT:
|
||||
# bool is an int subclass; a flag is not a number here.
|
||||
ok = isinstance(value, int) and not isinstance(value, bool)
|
||||
elif self.dtype is DType.FLOAT:
|
||||
ok = isinstance(value, (int, float)) and not isinstance(value, bool)
|
||||
elif self.dtype is DType.STR:
|
||||
ok = isinstance(value, str)
|
||||
where = self.name or self.port
|
||||
if self.dtype is DType.SERIES:
|
||||
ok = _is_series(value)
|
||||
elif self.dtype is DType.LIST:
|
||||
if not isinstance(value, list):
|
||||
raise TypeError(f"{where}: expected list, got {type(value).__name__}")
|
||||
item = self.item_dtype
|
||||
for index, element in enumerate(value):
|
||||
if not _matches(item, element):
|
||||
raise TypeError(
|
||||
f"{where}: expected list[{item.value}], got "
|
||||
f"{type(element).__name__} at index {index}"
|
||||
)
|
||||
return
|
||||
else:
|
||||
ok = isinstance(value, _JSON_TYPES)
|
||||
ok = _matches(self.dtype, value)
|
||||
if not ok:
|
||||
raise TypeError(
|
||||
f"{self.name or self.port}: expected {self.dtype.value}, "
|
||||
f"got {type(value).__name__}"
|
||||
f"{where}: expected {self.dtype.value}, got {type(value).__name__}"
|
||||
)
|
||||
|
||||
def coerce(self, value: Any) -> Any:
|
||||
@@ -101,6 +190,10 @@ class MessageSpec(BaseModel):
|
||||
return str(value).lower() in ("true", "1", "yes", "on")
|
||||
if self.dtype is DType.STR:
|
||||
return value if isinstance(value, str) else json.dumps(value)
|
||||
if self.dtype in (DType.SERIES, DType.RECORD, DType.LIST):
|
||||
# A structured payload arriving as text is the same hint a numeric
|
||||
# one is; the shape itself is still checked afterwards.
|
||||
return json.loads(value) if isinstance(value, str) else value
|
||||
return value
|
||||
|
||||
def __repr__(self) -> str:
|
||||
|
||||
Reference in New Issue
Block a user