dynamic-systems-testing-framework 1.0.1__py3-none-any.whl

dstf/authoring/shell/live_view.py

@@ -0,0 +1,93 @@
+"""The Test page's part of a running test's view (D151): once a second —
+the shell's `poll` — it says which variables its DRAWN plots show, and
+re-sends the plots the last read brought samples for. It reads no file:
+`Session.live_runs` polls once for every page, and the figure a card sends
+is the Session's, the Actual trace the samples read so far.
+
+A plot that is not drawn asks for nothing — a card draws when it scrolls
+into view — and one Focus hides asks for nothing either. A re-send is the
+card's own `redraw` (`Plotly.react`): a zoom, the legend's choices and the
+page's scroll position are the browser's, and stay.
+
+It also marks the page while its test has nothing scored because of a run
+— in progress, or ended without finishing: no criterion has a verdict
+then, and no pill is drawn (the rows say `waiting for result` or `not
+scored` where a readout goes)."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from .tree_card import _set_prop
+
+if TYPE_CHECKING:
+    from .test_page import TestPage
+
+logger = logging.getLogger(__name__)
+
+LIVE_CSS = """
+/* A test with nothing scored because of a run (D151): its criteria have no
+   verdict, so their pills are not drawn — the tree's, the plots' and the
+   Statistics card's. The header's badge is the test's own word. */
+.dstf-test[data-unscored] .dstf-pill { display: none; }
+/* One line under the strip: why a running test's page shows no growing
+   trace. */
+.dstf-strip-note { padding: 2px 24px; font-size: 12px; color: var(--dstf-text-muted);
+  border-top: 1px solid var(--dstf-border-hairline); }
+"""
+
+
+class LiveView:
+    def __init__(self, page: TestPage) -> None:
+        self.page = page
+
+    def mark(self, view: dict | None) -> None:
+        """The page's body says the word its criteria say in place of a
+        verdict (`live_rows.unscored_view`), or nothing. An attribute, the
+        server's own: a class the browser set would not survive a repaint."""
+        body = self.page.body
+        if body is None:
+            return
+        word = None if view is None else view.get("unscored")
+        if _set_prop(body, "data-unscored", word):
+            body.update()
+
+    def names(self) -> set[str]:
+        """The variables of the plots that are drawn and shown."""
+        return {
+            name
+            for card in self._drawn()
+            for name in card.resolved.series
+            if name not in card.resolved.missing
+        }
+
+    def _drawn(self) -> list:
+        return [
+            card
+            for card in self.page.cards
+            if card.plot is not None and card.card.visible
+        ]
+
+    def tick(self) -> None:
+        """Ask for the drawn plots' variables, and re-send each plot the
+        last poll brought a sample for. Nothing on a test that is not
+        running, or runs on a backend without a live view."""
+        page = self.page
+        runs, model_id = page.shell.session.live_runs, page.model_id
+        if not runs.polled(model_id):
+            return
+        runs.ask(model_id, self, self.names())
+        moved = [
+            card
+            for card in self._drawn()
+            if any(runs.moved(model_id, name) for name in card.resolved.series)
+        ]
+        if not moved:
+            return
+        view = page.shell.session.tree_view(model_id)  # one read for them all
+        for card in moved:
+            try:
+                card.redraw(view)
+            except Exception:  # one card's failure is not another's
+                logger.exception("live plot %s of %s", card.index, model_id)

dstf/authoring/shell/picker.py

@@ -0,0 +1,267 @@
+"""The add form's variable picker (the plan's Task 3, Q8, K2): the drawers'
+filter box over a scrolling list of rows in sections, filtered on the
+SERVER (`picker_rows`, `needle.matcher`) — never a `ui.select` over every
+name: TRANSFORM has a test of 76,992. One row is chosen (``value``, the
+result-file name); ArrowUp / ArrowDown move the cursor from the filter
+box, Enter chooses the cursor's row, a click chooses a row. Under the list
+a `Chosen:` line names the choice (K7), so a filter that hides its row
+still shows what Add will stage.
+
+A `ui.column` with a ``value``, so a form reads it as it read the select
+it replaced."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any
+
+import regex
+from nicegui import ui
+
+from ..needle import matcher
+from ..picker_rows import Picked, PickRow
+from .drawer_controls import filter_box
+from .widgets import MiddleCut
+
+_SPACE = re.compile(r"\s+")
+
+#: The filter box's keys the list answers, the page's default kept for
+#: every other key (a caret move, a typed character). Each carries the
+#: box's text AS TYPED: the filter reaches the server 250 ms after the last
+#: keystroke (`debounce`), and ↓ Enter typed inside that moved the cursor
+#: on the list before the filter and chose a row the list then hid. The
+#: `change` first flushes Quasar's debounce, so its model value is that
+#: text too: left at "" while `T_amb` ↓ drew T_amb's rows, the text then
+#: deleted inside the debounce emitted nothing (the value never moved)
+#: and the list stayed T_amb's under an empty box.
+_KEYS = """(e) => {
+  if (['ArrowDown', 'ArrowUp', 'Enter'].includes(e.key)) {
+    e.preventDefault();
+    e.target.dispatchEvent(new Event('change'));
+    emit({key: e.key, needle: e.target.value || ''});
+  }
+}"""
+
+
+def _mark(name: str) -> str:
+    """A row's marker word: NiceGUI splits a marker on whitespace."""
+    return _SPACE.sub("", name)
+
+
+class VariablePicker(ui.column):
+    def __init__(
+        self,
+        rows_of: Callable[[Callable[[str], bool]], Picked],
+        *,
+        value: str,
+        text_of: Callable[[str], str],
+        on_change: Callable[[str], None] | None = None,
+        marker: str,
+    ) -> None:
+        """``rows_of(keep)`` is the rows the filter ``keep`` leaves
+        (`picker_rows`); ``text_of(name)`` what a name reads as, for the
+        Chosen line."""
+        super().__init__()
+        self.classes("dstf-picker w-full gap-0")
+        self.mark(marker)
+        self._rows_of, self._on_change, self._marker = rows_of, on_change, marker
+        self._text_of = text_of
+        self.value = value
+        self.cursor = -1
+        self.shown: list[PickRow] = []
+        self._drawn: dict[str, ui.element] = {}
+        with self:
+            self.box = filter_box(
+                "",
+                False,
+                False,
+                self._filter,
+                "search every variable",
+                f"{marker}:pick-",
+            )
+            # The field's name, as the select it replaced was named.
+            self.box.needle.props["label"] = "Variable"
+            self.box.needle.on("keydown", self._key, js_handler=_KEYS)
+            self.list = (
+                ui.column()
+                .classes("dstf-pick-list w-full gap-0")
+                .mark(f"{marker}:pick-list")
+            )
+            # A combobox over a listbox (WAI-ARIA): the box keeps the focus
+            # and names the cursor's row as its active descendant.
+            self.list.props["role"] = "listbox"
+            # Not "Variables", which reads as the box's "Variable". A lookup
+            # of the box goes by its role: a label lookup of "Variable" also
+            # finds the "Other variables" group.
+            self.list.props["aria-label"] = "Matching names"
+            needle = self.box.needle.props
+            needle["role"] = "combobox"
+            needle["aria-controls"] = self.list.html_id
+            needle["aria-expanded"] = "true"
+            needle["aria-autocomplete"] = "list"
+            # Outside the list: a listbox holds options and groups of them.
+            self.none = ui.label("no variable matches").classes("dstf-why")
+            self.none.props["role"] = "status"
+            self.none.set_visibility(False)
+            self.cap = ui.label().classes("dstf-why").mark(f"{marker}:pick-cap")
+            self.chosen = (
+                ui.label()
+                .classes("dstf-pick-chosen text-caption")
+                .mark(f"{marker}:pick-chosen")
+            )
+        self._state: dict[str, Any] = {"needle": "", "regex": False, "case": False}
+        self._say_chosen()
+        self._draw()
+
+    # -- the list ------------------------------------------------------------
+
+    def _filter(self, needle: str, regex_on: bool, case: bool) -> None:
+        """The box's filter. The same one again — the debounced change after
+        a key already drew its needle (`_key`) — draws nothing: a redraw
+        would take the cursor off the row just moved to."""
+        state = {"needle": needle, "regex": regex_on, "case": case}
+        if state == self._state:
+            return
+        self._state = state
+        self._draw()
+
+    def _draw(self) -> None:
+        st = self._state
+        self.list.clear()
+        self._drawn, self.shown, self.cursor = {}, [], -1
+        self._active(None)
+        try:
+            keep = matcher(st["needle"], regex=st["regex"], case=st["case"])
+            picked = self._rows_of(keep)
+        except regex.error as e:
+            self.box.say(f"not a regular expression: {e}")
+            self.cap.set_visibility(False)
+            self.none.set_visibility(False)
+            return
+        except TimeoutError:
+            self.box.say("the pattern took too long; simplify it")
+            self.cap.set_visibility(False)
+            self.none.set_visibility(False)
+            return
+        self.box.say(None)
+        with self.list:
+            for title, rows in picked.sections:
+                # A named group of options (WAI-ARIA): its title is the
+                # group's name, so it is not read a second time.
+                with ui.column().classes("w-full gap-0") as group:
+                    head = ui.label(title).classes("dstf-group")
+                    head.mark(f"{self._marker}:pick-section:{_mark(title)}")
+                    head.props["aria-hidden"] = "true"
+                    for row in rows:
+                        self._row(row)
+                group.props["role"] = "group"
+                group.props["aria-label"] = title
+        self.none.set_visibility(not picked.sections)
+        self.cap.set_text(picked.capped or "")
+        self.cap.set_visibility(picked.capped is not None)
+        if self.value in self._drawn:
+            self.cursor = [r.name for r in self.shown].index(self.value)
+
+    def _row(self, row: PickRow) -> None:
+        self.shown.append(row)
+        with (
+            ui.row()
+            .classes("dstf-pick-row items-baseline no-wrap gap-2 w-full")
+            .mark(f"{self._marker}:pick:{_mark(row.name)}")
+            .on("click", lambda _e, n=row.name: self.set_value(n))
+        ) as element:
+            # The plain label: the muted name beside it names the row, and
+            # the scope's text would say the name twice, `a.Q (y) y`.
+            text = MiddleCut(row.label).classes("dstf-var-text dstf-mono text-xs")
+            text.props["title"] = row.name
+            if row.label != row.name:
+                ui.label(row.name).classes("dstf-varname dstf-var-text")
+        element.props["role"] = "option"
+        # Its accessible name is said, not read off the row: the middle
+        # cut's two parts read as "…T_very_long_co mponent_name". The name
+        # once — from the scope's text it read `a.Q (y) (y)`.
+        element.props["aria-label"] = (
+            row.label if row.label == row.name else f"{row.label} ({row.name})"
+        )
+        element.props["aria-selected"] = "true" if row.name == self.value else "false"
+        if row.name == self.value:
+            element.classes(add="dstf-pick-on")
+        self._drawn[row.name] = element
+
+    @property
+    def options(self) -> dict[str, str]:
+        """``{name: text}`` of the rows drawn now, in their order."""
+        return {r.name: r.text for r in self.shown}
+
+    # -- choosing ------------------------------------------------------------
+
+    def _say_chosen(self) -> None:
+        self.chosen.set_text(
+            f"Chosen: {self._text_of(self.value)}" if self.value else "Chosen: none"
+        )
+
+    def set_value(self, name: str) -> None:
+        """Choose ``name``: its row is highlighted and carries the cursor
+        (a click's row is the one ↓ moves from), the Chosen line names it,
+        ``on_change`` hears it."""
+        old = self._drawn.get(self.value)
+        if old is not None:
+            old.classes(remove="dstf-pick-on")
+            old.props["aria-selected"] = "false"
+            old.update()
+        self.value = name
+        new = self._drawn.get(name)
+        if new is not None:
+            new.classes(add="dstf-pick-on")
+            new.props["aria-selected"] = "true"
+            new.update()
+            self._move([r.name for r in self.shown].index(name))
+        self._say_chosen()
+        if self._on_change is not None:
+            self._on_change(name)
+
+    def _move(self, to: int) -> None:
+        if not self.shown:
+            return
+        old = self._cursor_element()
+        if old is not None:
+            old.classes(remove="dstf-pick-cursor")
+        self.cursor = to % len(self.shown)
+        new = self._cursor_element()
+        self._active(new)
+        if new is not None:
+            new.classes(add="dstf-pick-cursor")
+            self.client.run_javascript(
+                f'document.getElementById("{new.html_id}")'
+                '?.scrollIntoView({block: "nearest"})'
+            )
+
+    def _active(self, row: ui.element | None) -> None:
+        """The box's ``aria-activedescendant``: the cursor's row, if any."""
+        props = self.box.needle.props
+        if row is None:
+            if props.pop("aria-activedescendant", None) is not None:
+                self.box.needle.update()
+            return
+        props["aria-activedescendant"] = row.html_id
+        self.box.needle.update()
+
+    def _cursor_element(self) -> ui.element | None:
+        if 0 <= self.cursor < len(self.shown):
+            return self._drawn.get(self.shown[self.cursor].name)
+        return None
+
+    def _key(self, e: Any) -> None:
+        """A key on the list AS THE USER SEES IT: a needle typed since the
+        last filter is drawn first (`_KEYS`)."""
+        key, needle = e.args["key"], e.args["needle"]
+        if needle != self._state["needle"]:
+            self._state = {**self._state, "needle": needle}
+            self._draw()
+        if key == "ArrowDown":
+            self._move(self.cursor + 1)
+        elif key == "ArrowUp":
+            self._move(self.cursor - 1 if self.cursor >= 0 else -1)
+        elif key == "Enter" and 0 <= self.cursor < len(self.shown):
+            self.set_value(self.shown[self.cursor].name)

dstf/authoring/shell/placing.py

@@ -0,0 +1,122 @@
+"""The open criterion editor's ⌖ buttons and its one armed field (D149:
+arm a field, then click the plot).
+
+A field that names a place on the plot carries a ⌖ (`Panel.place_button`).
+Pressed, it ARMS that field: the next plain click on the criterion's plot
+is handed to the panel that drew it (`Panel.on_place`), which sets the
+field from the click; a click that goes through disarms, a refused one
+says why under the plot and leaves the field armed. One field is armed at
+a time — one editor is open on a page, and this is its — and pressing ⌖
+again, Esc, closing the editor or opening another criterion disarms.
+
+The armed field is the SERVER's to know (it reads the click), so its
+button's highlight is an attribute the server renders — ``aria-pressed``,
+which the stylesheet reads — never a class the page sets.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Hashable
+from dataclasses import dataclass
+
+from nicegui import ui
+
+from .figure_hook import FigureHook
+
+#: The hook kinds a panel's place handler and preview handler are
+#: subscribed under (`ShellPanel.on_place` / `.on_preview`): so a rebuilt
+#: panel's go with its other handlers (`FigureHook.clear(owner)`).
+PLACE = "dstf_place"
+PREVIEW = "dstf_preview"
+
+#: A click with any of these held is not a plain click.
+MODIFIERS = ("ctrl", "shift", "alt", "meta")
+
+
+@dataclass(frozen=True)
+class Armed:
+    """The armed field: the capability whose panel drew it, the name that
+    panel gave it (`Panel.place_button`'s ``pointer``) and its label."""
+
+    owner: str
+    pointer: Hashable
+    label: str
+
+
+class Placing:
+    """One plot card's: the ⌖ buttons of the editor open under it, which
+    of their fields is armed, and the hook its clicks arrive on."""
+
+    def __init__(self, hook: FigureHook, on_change: Callable[[], None]) -> None:
+        self.hook = hook
+        #: Called when the armed field changes: the card says it in the
+        #: editor's hint line.
+        self._on_change = on_change
+        self.armed: Armed | None = None
+        self._buttons: dict[tuple[str, Hashable], ui.button] = {}
+
+    def button(self, owner: str, pointer: Hashable, label: str) -> None:
+        """Draw the ⌖ of the field ``owner``'s panel calls ``pointer``,
+        into the current slot; its click never reaches the field it sits
+        in. Out of the Tab order: it is the first half of a gesture whose
+        second is a click on the plot, and in it Tab from a field met a ⌖
+        before the next field — twice in every tolerance."""
+        armed = Armed(owner, pointer, label)
+        button = (
+            ui.button(icon="my_location", color=None)
+            .props('flat dense round size=xs tabindex="-1"')
+            .classes("dstf-arm")
+            .on(
+                "click",
+                lambda: self.toggle(armed),
+                js_handler="(e) => { e.stopPropagation(); emit(); }",
+            )
+        )
+        button.props["aria-label"] = f"Set {label} by a click on the plot"
+        button.props["aria-pressed"] = "true" if self.armed == armed else "false"
+        # The browser's own tooltip, not an element: a table of thirty
+        # checkpoints draws 180 of these on every rebuild of the editor.
+        button.props["title"] = "Set by a click on the plot"
+        self._buttons[owner, pointer] = button
+
+    def toggle(self, armed: Armed) -> None:
+        self._set(None if self.armed == armed else armed)
+
+    def disarm(self) -> None:
+        if self.armed is not None:
+            self._set(None)
+
+    def settle(self) -> None:
+        """After the editor's panels were rebuilt: the buttons that went
+        with them are forgotten, and a field that is no longer drawn — its
+        row removed, its mode switched away — is no longer armed."""
+        self._buttons = {k: b for k, b in self._buttons.items() if not b.is_deleted}
+        armed = self.armed
+        if armed is not None and (armed.owner, armed.pointer) not in self._buttons:
+            self._set(None)
+
+    def forget(self) -> None:
+        """The editor closed: nothing is armed and no button is its."""
+        self._buttons = {}
+        self.disarm()
+
+    def _set(self, armed: Armed | None) -> None:
+        self.armed = armed
+        for (owner, pointer), button in self._buttons.items():
+            if button.is_deleted:
+                continue
+            on = armed is not None and (armed.owner, armed.pointer) == (owner, pointer)
+            pressed = "true" if on else "false"
+            # Only when it changes: every write of a prop resends the button.
+            if button.props.get("aria-pressed") != pressed:
+                button.props["aria-pressed"] = pressed
+                button.update()
+        self._on_change()
+
+    def clicked(self, click: dict) -> None:
+        """A click on the plot, as the page reports it: every subscriber
+        of the raw click hears it (Ctrl+click adds a row), and a PLAIN one
+        is the armed field's."""
+        self.hook.emit("dstf_click", click)
+        if self.armed is not None and not any(click.get(key) for key in MODIFIERS):
+            self.hook.emit(PLACE, click)