pgwidgets-python 0.3.4__py3-none-any.whl → 0.4.0__py3-none-any.whl

pgwidgets/method_types.py

@@ -87,9 +87,13 @@ ACTION_METHODS = {
     # Per-cell / row / column / table colour overrides — the
     # ``set_*`` naming would otherwise classify them as SETTERs,
     # whose single-state-slot semantics can't represent the
-    # accumulated dict of overrides we actually keep.  ACTION
-    # dispatch sends each call straight through to the JS side,
-    # which holds the canonical state in its own maps.
+    # accumulated dict of overrides we actually keep.  Listed here
+    # so no SETTER is generated; _add_tree_view_methods() then
+    # supplies generators that accumulate them into the _cell_styles
+    # / _row_styles / _column_styles / _table_style dicts, which
+    # reconstruct() replays (see TREE_OVERRIDE_REPLAY).  Same
+    # arrangement as expand_item / sort_by_column above.
+    "set_colors",
     "set_cell_color", "set_row_color", "set_column_color",
     "set_table_color",
     "clear_cell_color", "clear_row_color", "clear_column_color",
@@ -107,8 +111,14 @@ ACTION_METHODS = {
     "raise_", "lower",
     # Timer
     "start", "cancel", "set", "cond_set",
-    # Table/Tree row-level modifications (tracked via bulk set_data)
-    "add_item", "remove_item", "update_tree", "remove_items",
+    # Tree / table / column mutations.  Listed here so no SETTER is
+    # generated (none of them sets a single state slot);
+    # _add_tree_view_methods() then supplies generators that apply each
+    # mutation to the tree / rows / columns model in _state, so the bulk
+    # state replayed on reconnect reflects every change since, not just
+    # the last wholesale set.  See pgwidgets.tree_model.
+    "add_item", "remove_item", "update_tree", "remove_items", "delete_tree",
+    "update_data", "update_rows",
     "insert_row", "append_row", "delete_row",
     "insert_column", "append_column", "delete_column",
     "set_cell",
@@ -232,7 +242,123 @@ CHILD_SELECT_METHODS = {
 # (e.g. Splitter.set_sizes needs panes to already exist).
 POST_CHILDREN_STATE_KEYS = {"sizes", "index", "_collapsed_paths",
                             "_expanded_paths", "_sort", "scroll_position",
-                            "scroll_percent"}
+                            "scroll_percent",
+                            # Tree/table colour overrides.  Unlike the row
+                            # data -- which folds into the tree/rows model
+                            # and is replayed by the bulk setter -- these
+                            # have no bulk setter, so they are accumulated
+                            # and replayed on top of the data.
+                            "_cell_styles", "_row_styles",
+                            "_column_styles", "_table_style"}
+
+# Maps a colour-override state key to the method that replays one stored
+# entry during reconstruction.  Each entry holds the original call's
+# argument tuple, so replaying is a straight re-dispatch.  _table_style
+# holds a single tuple rather than a dict of them.
+TREE_OVERRIDE_REPLAY = {
+    "_cell_styles": "set_cell_color",
+    "_row_styles": "set_row_color",
+    "_column_styles": "set_column_color",
+}
+
+# Colour overrides are replayed in batches rather than one call per
+# cell: each single call is a blocking websocket round-trip *and* a full
+# re-render in the browser, so restoring a few hundred coloured cells
+# one at a time is slow and visibly iterative.  Cells are chunked so no
+# single message grows unreasonably large.
+COLOUR_BATCH_SIZE = 500
+
+
+# Colour calls that can be folded into a single ``set_colors``, mapped
+# to the spec key they contribute to and the names of their arguments.
+_COLOUR_CALL_SPEC = {
+    "set_cell_color": ("cells", ("path", "col_key", "fg", "bg", "bold")),
+    "set_row_color": ("rows", ("path", "fg", "bg", "bold")),
+    "set_column_color": ("columns", ("col_key", "fg", "bg", "bold")),
+    "set_table_color": ("table", ("fg", "bg", "bold")),
+}
+
+
+def coalesce_colour_calls(calls):
+    """Fold runs of colour calls in a batch into single ``set_colors``.
+
+    Each ``set_*_color`` re-renders the widget, so a few hundred of them
+    are slow in the browser even when they arrive in one message -- the
+    reason the reconnect path uses ``set_colors`` instead.  Doing the
+    same for batched calls means an app can keep writing the simple
+    per-cell loop and still get one render.
+
+    Only *consecutive* calls on the same widget are merged, so ordering
+    against any interleaved non-colour call is preserved.  Runs of one
+    are left alone.  ``set_colors`` and the batch message arrived
+    together, so a browser that understands the batch understands the
+    merged call.
+    """
+    out = []
+    i = 0
+    n = len(calls)
+    while i < n:
+        call = calls[i]
+        if call.get("method") not in _COLOUR_CALL_SPEC:
+            out.append(call)
+            i += 1
+            continue
+
+        wid = call.get("wid")
+        run = []
+        while (i < n and calls[i].get("method") in _COLOUR_CALL_SPEC
+               and calls[i].get("wid") == wid):
+            run.append(calls[i])
+            i += 1
+
+        if len(run) == 1:
+            out.append(run[0])
+            continue
+
+        spec = {}
+        for entry in run:
+            key, names = _COLOUR_CALL_SPEC[entry["method"]]
+            values = dict(zip(names, entry.get("args", [])))
+            if key == "table":
+                spec["table"] = values
+            else:
+                spec.setdefault(key, []).append(values)
+        out.append({"wid": wid, "method": "set_colors", "args": [spec]})
+    return out
+
+
+def colour_batches(widget, chunk=COLOUR_BATCH_SIZE):
+    """Return the ``set_colors`` specs that restore a widget's colours.
+
+    The row, column and table layers ride along in the first batch; the
+    per-cell overrides are split across as many batches as needed.
+    """
+    state = getattr(widget, "_state", None) or {}
+    cells = [dict(zip(("path", "col_key", "fg", "bg", "bold"), args))
+             for args in state.get("_cell_styles", {}).values()]
+    rows = [dict(zip(("path", "fg", "bg", "bold"), args))
+            for args in state.get("_row_styles", {}).values()]
+    columns = [dict(zip(("col_key", "fg", "bg", "bold"), args))
+               for args in state.get("_column_styles", {}).values()]
+    table = state.get("_table_style")
+
+    if not (cells or rows or columns or table):
+        return []
+
+    first = {}
+    if rows:
+        first["rows"] = rows
+    if columns:
+        first["columns"] = columns
+    if table is not None:
+        first["table"] = dict(zip(("fg", "bg", "bold"), table))
+    if cells[:chunk]:
+        first["cells"] = cells[:chunk]
+
+    batches = [first]
+    for i in range(chunk, len(cells), chunk):
+        batches.append({"cells": cells[i:i + chunk]})
+    return batches
 
 # Default state values applied when a widget is created without
 # explicitly setting the key (e.g. TextEntry() with no text arg).
@@ -297,8 +423,12 @@ CLEAR_RESETS = {
     "TextArea": ["text"],
     "TextSource": ["text"],
     "ComboBox": ["text", "index", "_items"],
-    "TreeView": ["tree", "data", "_collapsed_paths", "_sort"],
-    "TableView": ["rows", "data", "_collapsed_paths", "_sort"],
+    # The JS clear() empties its per-cell and per-row style maps but
+    # keeps the column / table layers, so mirror exactly that.
+    "TreeView": ["tree", "data", "_collapsed_paths", "_sort",
+                 "_cell_styles", "_row_styles"],
+    "TableView": ["rows", "data", "_collapsed_paths", "_sort",
+                  "_cell_styles", "_row_styles"],
     "HtmlView": ["html"],
     "ExternalWidget": ["content"],
 }
@@ -419,7 +549,34 @@ BINARY_STATE_KEYS = {
 }
 
 
+def _combobox_get_index(self):
+    """Index of the item matching the current text, or -1 when the text is
+    not one of the offerings (e.g. a value typed into an editable combo box
+    but not yet committed with Enter).  Mirrors the JS get_index(), which
+    is items.indexOf(input value), and stays consistent with get_text()
+    (the cached entry text, kept live by the 'modified' callback)."""
+    items = self._state.get("_items", [])
+    try:
+        return items.index(self._state.get("text", ""))
+    except ValueError:
+        return -1
+
+
+def _combobox_set_index(self, idx):
+    """Select the item at *idx*, keeping the cached text consistent with
+    the index so get_text() agrees with get_index() after a programmatic
+    change (the generic setter would leave 'text' stale)."""
+    items = self._state.get("_items", [])
+    if 0 <= idx < len(items):
+        self._state["text"] = items[idx]
+    self._state["index"] = idx
+    self._user_set_state.add("index")
+    return self._call("set_index", idx)
+
+
 CUSTOM_METHODS = {
+    ("ComboBox", "get_index"): _combobox_get_index,
+    ("ComboBox", "set_index"): _combobox_set_index,
     ("TabWidget", "index_to_widget"): _index_to_widget,
     ("TabWidget", "index_of"): _index_of,
     ("StackWidget", "index_to_widget"): _index_to_widget,

pgwidgets/sync/application.py

@@ -11,6 +11,7 @@ the UI can be reconstructed when a browser reconnects.
 """
 
 import asyncio
+import contextlib
 import json
 import logging
 import mimetypes
@@ -33,6 +34,8 @@ from pgwidgets.method_types import (
     STATE_SYNC_CALLBACKS, STATE_SYNC_REQUIRES_OPTION,
     WIDGET_CALLBACK_SYNC, POST_CHILDREN_STATE_KEYS, ITEM_LIST_CONFIG,
     CHILD_CLOSE_CALLBACKS, REPLAY_METHODS, TREE_VIEW_WIDGETS,
+    TREE_OVERRIDE_REPLAY, colour_batches, JS_ONLY_METHODS,
+    coalesce_colour_calls,
     BINARY_STATE_KEYS, _send_binary_auto,
 )
 
@@ -189,6 +192,14 @@ class Session:
 
         self._reconstructing = False  # suppress callbacks during reconstruction
 
+        # Batching (see batch()).  While _batch_depth is non-zero, calls
+        # are buffered here instead of being sent one at a time.
+        self._batch_depth = 0
+        self._batch_calls = []
+        # cleared if a browser rejects the 'batch' message; a new
+        # connection may be a newer client, so add_connection resets it
+        self._batch_supported = True
+
         # Browser viewport size (updated by 'viewport' messages from JS).
         self._screen_size = (0, 0)
 
@@ -247,6 +258,9 @@ class Session:
         """Add a browser connection to this session."""
         if ws not in self._connections:
             self._connections.append(ws)
+        # a reconnecting browser may be a newer client than the one
+        # that made us give up on batching
+        self._batch_supported = True
 
     def remove_connection(self, ws):
         """Remove a browser connection from this session."""
@@ -524,6 +538,14 @@ class Session:
                         widget._state[spec[0]] = tuple(args)
                     else:
                         widget._state[spec] = args[0]
+            # ComboBox: a value committed with Enter in the browser may be
+            # a new entry the browser appended to its list; mirror that
+            # append so our _items (and thus get_index) stays consistent.
+            if (widget._js_class == "ComboBox" and action == "activated"
+                    and len(args) >= 2):
+                items = widget._state.setdefault("_items", [])
+                if args[1] not in items:
+                    items.append(args[1])
         # Dialog autoclose: the JS side auto-hides when a button is
         # clicked.  Sync that to Python so reconstruction doesn't
         # re-show a dialog that was autoclosed.
@@ -540,7 +562,8 @@ class Session:
                 key_path = tuple(path) if isinstance(path, list) else path
                 expanded = widget._state.setdefault(
                     "_expanded_paths", set())
-                expanded.add(key_path)
+                if expanded != "_all":
+                    expanded.add(key_path)
                 collapsed = widget._state.get("_collapsed_paths")
                 if collapsed is not None and collapsed != "_all":
                     collapsed.discard(key_path)
@@ -549,7 +572,7 @@ class Session:
                 path = args[1]
                 key_path = tuple(path) if isinstance(path, list) else path
                 expanded = widget._state.get("_expanded_paths")
-                if expanded is not None:
+                if expanded is not None and expanded != "_all":
                     expanded.discard(key_path)
                 collapsed = widget._state.setdefault(
                     "_collapsed_paths", set())
@@ -725,11 +748,101 @@ class Session:
         })
         return wid
 
+    @contextlib.contextmanager
+    def batch(self):
+        """Apply many updates as one message.
+
+        Every call normally goes to the browser on its own and blocks
+        for the reply, and widgets like TreeView re-render on each one.
+        For a burst of updates -- a refresh rewriting a few hundred
+        cells, say -- that is slow and paints in visible stages.  Inside
+        this context the calls are buffered and sent as a single batch
+        on exit, which the browser applies with rendering suspended, so
+        each widget draws once::
+
+            with tree.get_session().batch():
+                for path, col, value in changes:
+                    tree.set_cell(path, col, value)
+
+        Widget state is still updated as each call is made -- only the
+        traffic is deferred -- so the Python-side model stays correct
+        throughout, and a reconnect landing mid-batch reconstructs from
+        it correctly.
+
+        Calls made inside a batch return None.  Methods that genuinely
+        need an answer from the browser (getters, and the browser-only
+        queries) flush the batch first and execute immediately, so
+        ordering is preserved.
+
+        Nests: only the outermost block flushes.  The buffer is flushed
+        on the way out even if the body raises, because those calls have
+        already been applied to the model and dropping them would leave
+        the browser diverged from it.
+        """
+        self._batch_depth += 1
+        try:
+            yield self
+        finally:
+            self._batch_depth -= 1
+            if self._batch_depth == 0:
+                self._flush_batch()
+
+    def _flush_batch(self):
+        """Send everything buffered by batch() as one message.
+
+        A browser older than this server won't know the ``batch``
+        message -- a page that was loaded before the server was
+        upgraded, most commonly.  Rather than failing the caller's
+        update, fall back to sending the calls individually and stop
+        trying to batch for this connection.  Reloading the page picks
+        up the current client and re-enables it.
+        """
+        calls, self._batch_calls = self._batch_calls, []
+        if not calls:
+            return None
+        # _send handles the no-browser case (and is the single place
+        # that policy lives)
+        # Fold runs of colour calls into set_colors: one re-render in
+        # the browser instead of one per cell.
+        calls = coalesce_colour_calls(calls)
+        if self._batch_supported:
+            self._logger.debug("flushing a batch of %d call(s)", len(calls))
+            try:
+                return self._send({"type": "batch", "calls": calls})
+            except RuntimeError as e:
+                if "Unknown message type" not in str(e):
+                    raise
+                self._batch_supported = False
+                self._logger.warning(
+                    "browser does not understand batched updates (it is "
+                    "running an older pgwidgets-js); sending calls "
+                    "individually. Reload the page to re-enable batching.")
+        for call in calls:
+            self._send({"type": "call", **call})
+        return None
+
+    def _needs_result(self, method):
+        """True if `method` has to reach the browser now to be useful.
+
+        Getters answer from local state where they can; the ones that
+        can't (and the browser-only queries) must not be deferred, or
+        the caller gets None where it expected a value.
+        """
+        return method.startswith("get_") or method in JS_ONLY_METHODS
+
     def _call(self, wid, method, *args):
         """Call a method on a JS widget.
 
         Returns None if no browser is connected.
         """
+        if self._batch_depth > 0:
+            if not self._needs_result(method):
+                self._batch_calls.append({"wid": wid, "method": method,
+                                          "args": list(args)})
+                return None
+            # has to go now -- flush what's queued so it stays ordered
+            self._flush_batch()
+
         result = self._send({
             "type": "call",
             "wid": wid,
@@ -1524,6 +1637,13 @@ class Session:
                                        list(path))
                     continue
 
+                # Tree/table colour overrides are replayed together as
+                # batches once the whole state has been walked (see
+                # below) -- one round-trip and one browser re-render per
+                # batch, rather than per coloured cell.
+                if key in TREE_OVERRIDE_REPLAY or key == "_table_style":
+                    continue
+
                 # Tree/table sort
                 if key == "_sort":
                     col, asc = value
@@ -1539,6 +1659,10 @@ class Session:
                 else:
                     self._call(widget._wid, method_name, value)
 
+            # Colour overrides, batched
+            for spec in colour_batches(widget):
+                self._call(widget._wid, "set_colors", spec)
+
             # Show/hide
             for key, value in widget._state.items():
                 if key in self._FIXED_STATE_KEYS: