pgwidgets-python 0.3.5__tar.gz → 0.4.1__tar.gz

{pgwidgets_python-0.3.5 → pgwidgets_python-0.4.1}/.github/workflows/tests.yml

@@ -11,7 +11,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.12", "3.13"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4

{pgwidgets_python-0.3.5 → pgwidgets_python-0.4.1}/PKG-INFO

@@ -1,23 +1,23 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.3.5
+Version: 0.4.1
 Summary: Python bindings for the pgwidgets JavaScript widget library
 Author: PGWidgets Developers
-License: BSD-3-Clause
+License-Expression: BSD-3-Clause
 Project-URL: Homepage, https://github.com/naojsoft/pgwidgets-python
 Project-URL: Repository, https://github.com/naojsoft/pgwidgets-python
 Keywords: widgets,ui,gui,websocket,browser
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: BSD License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: User Interfaces
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
-Requires-Dist: pgwidgets-js>=0.3.4
+Requires-Dist: pgwidgets-js>=0.4.1
 Requires-Dist: websockets>=12
 Provides-Extra: dev
 Requires-Dist: sphinx; extra == "dev"

{pgwidgets_python-0.3.5 → pgwidgets_python-0.4.1}/docs/WhatsNew.rst

@@ -1,6 +1,64 @@
 What's New
 ==========
 
+Recent changes — since ``v0.4.0``
+---------------------------------
+
+TextSource: scroll alignment and caret styling
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``scroll_to_ref(ref, align)`` and ``scroll_to_lineno(lineno, align)``
+take an alignment -- ``'nearest'`` (the default, as before),
+``'center'`` or ``'top'`` -- and pass it to the browser alongside the
+offset.  A search that scrolls to its match can now put the match in
+the middle of the view rather than merely bringing it into sight.
+
+``set_cursor_style(style, color)`` picks a ``'line'`` or ``'block'``
+caret in any colour, and ``get_cursor_style()`` reads the pair back.
+The choice is part of the model, replayed from
+``_reconstruct_model()``, so a browser that (re)connects gets the caret
+along with everything else.  It is styled through the browser's own
+``caret-color`` / ``caret-shape``, so it shows only while the editor
+has the focus.
+
+These need the matching methods in pgwidgets-js 0.4.1, which the
+dependency floor now requires.
+
+Recent changes — since ``v0.3.5``
+---------------------------------
+
+TreeView / TableView: Python-authoritative model, batched updates
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Python is now the source of truth for the tree/table model, so a
+browser reconnect rebuilds the *current* state instead of replaying
+the original snapshot.  Previously only the bulk setters were tracked,
+so later mutations were fire-and-forget: a reconnect silently reverted
+every change made since the last full load and dropped the colour
+overrides entirely.
+
+* All the incremental edits -- ``set_cell``, ``add_item`` /
+  ``remove_item`` / ``remove_items``, ``add_tree`` / ``delete_tree``,
+  and the row / column edits -- now apply to the stored model, so they
+  survive reconnect.  Bulk setters deep-copy their input, so a caller
+  that keeps editing the structure it passed in can't corrupt the model.
+* Colour overrides accumulate per cell / row / column / table and are
+  replayed after the data on reconnect, in chunked ``set_colors``
+  batches rather than one call per cell.
+* ``update_tree`` diffs against the model and sends only the deltas, so
+  the browser keeps its expansion state, cell styles, and any open
+  editor.
+* ``Session.batch()`` (and ``widget.batch()``) buffers a burst of calls
+  into a single ``batch`` message; runs of colour calls fold into
+  ``set_colors``, so a plain per-cell loop still redraws once.  State
+  updates as each call is made, so a reconnect mid-batch still
+  reconstructs correctly, and a browser predating the batch message
+  falls back to individual calls.
+* Fixed expand/collapse tracking after ``expand_all()`` /
+  ``collapse_all()`` (the ``"_all"`` sentinel raised ``AttributeError``
+  in the websocket handler when a node was later expanded or
+  collapsed).
+
 Recent changes — since ``v0.3.0``
 ---------------------------------
 
@@ -121,7 +179,7 @@ the 4th argument, so handlers that double-click a file can see
 which column they hit.  Existing handlers (3-arg) keep working.
 
 ``_resolve_kwargs``: skipped-positional kwargs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The kwarg resolver used by every generated widget method now
 allows a caller to skip a positional argument and supply the

{pgwidgets_python-0.3.5 → pgwidgets_python-0.4.1}/docs/architecture.rst

@@ -54,6 +54,9 @@ All messages are JSON objects with a ``type`` field.
   call a method on a widget.
 - ``{"type": "call", ..., "silent": true}`` -- call a method without
   triggering callbacks (used for cross-browser sync).
+- ``{"type": "batch", "calls": [{"wid": 1, "method": "set_cell",
+  "args": [...]}, ...]}`` -- apply many calls as one message (see
+  `Batching Updates`_).
 - ``{"type": "listen", "wid": 1, "action": "activated"}`` -- subscribe to a
   callback.
 - ``{"type": "unlisten", "wid": 1, "action": "activated"}`` -- unsubscribe.
@@ -180,3 +183,45 @@ passed as an argument to another widget's method (e.g., ``vbox.add_widget(btn,
 0)``), the framework automatically converts the Python ``Widget`` object to a
 ``{"__wid__": N}`` reference on the wire, and converts it back on return
 values.
+
+
+Batching Updates
+----------------
+
+Every widget call is normally its own message, and blocks until the
+browser replies.  While the UI is being built that costs nothing --
+with no browser attached the calls return immediately -- so the cost
+only shows up when a connected browser is being updated in bulk: a
+refresh rewriting a few hundred cells, say.  Two things make that slow:
+one round-trip per call, and widgets such as ``TreeView`` re-rendering
+on each one, which also makes the update paint in visible stages.
+
+``Session.batch()`` (also reachable as ``widget.batch()``, since
+batching is per session) buffers the calls and sends them as a single
+``batch`` message.  The browser applies them with rendering suspended
+on each widget it touches, so every widget draws once:
+
+.. code-block:: python
+
+   with tree.batch():
+       for path, col_key, value in changes:
+           tree.set_cell(path, col_key, value)
+       status.set_text("updated")
+
+Semantics worth knowing:
+
+- **State is still updated immediately.**  Only the traffic is
+  deferred, so the Python-side model stays correct throughout and a
+  reconnect landing mid-batch reconstructs from it correctly.
+- **Batched calls return None.**  Methods that genuinely need an answer
+  from the browser -- getters, and the browser-only queries -- flush the
+  pending batch and execute immediately, so ordering is preserved.
+- **Nesting is allowed;** only the outermost block flushes.
+- **The buffer is flushed even if the body raises.**  Those calls have
+  already been applied to the model, so dropping them would leave the
+  browser diverged from it.
+
+Reconnection does its own batching: the colour overrides a tree or
+table carries are replayed as a few large ``set_colors`` calls rather
+than one per cell, so restoring a heavily coloured table is not
+proportional to the number of round-trips.

{pgwidgets_python-0.3.5 → pgwidgets_python-0.4.1}/docs/sync.rst

@@ -114,8 +114,8 @@ Bytes are served from ``/_pgwidgets/font/<id>`` by the built-in
 HTTP server with ``Cache-Control: immutable``; behind Flask /
 nginx the same route is served from the Python process.
 
-See also the JS-side write-up at :ref:`custom-fonts` in the
-pgwidgets-js documentation.
+See also the "Custom fonts" section of the pgwidgets-js
+documentation for the browser side of this.
 
 Opening a URL in the browser
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

{pgwidgets_python-0.3.5 → pgwidgets_python-0.4.1}/pgwidgets/async_/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
@@ -31,6 +32,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,
 )
 from pgwidgets.async_.widget import Widget, build_all_widget_classes
@@ -142,6 +145,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)
 
@@ -198,6 +209,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."""
@@ -459,7 +473,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)
@@ -468,7 +483,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())
@@ -678,11 +693,76 @@ class Session:
         })
         return wid
 
+    @contextlib.asynccontextmanager
+    async def batch(self):
+        """Apply many updates as one message.
+
+        The async counterpart of the sync ``Session.batch``; see that
+        docstring for the semantics.  Used as::
+
+            async with tree.batch():
+                for path, col, value in changes:
+                    await tree.set_cell(path, col, value)
+        """
+        self._batch_depth += 1
+        try:
+            yield self
+        finally:
+            self._batch_depth -= 1
+            if self._batch_depth == 0:
+                await self._flush_batch()
+
+    async 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 await 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:
+            await self._send({"type": "call", **call})
+        return None
+
+    def _needs_result(self, method):
+        """True if `method` has to reach the browser now to be useful."""
+        return method.startswith("get_") or method in JS_ONLY_METHODS
+
     async 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
+            await self._flush_batch()
+
         result = await self._send({
             "type": "call",
             "wid": wid,
@@ -1335,6 +1415,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
@@ -1350,6 +1437,10 @@ class Session:
                 else:
                     await self._call(widget._wid, method_name, value)
 
+            # Colour overrides, batched
+            for spec in colour_batches(widget):
+                await self._call(widget._wid, "set_colors", spec)
+
             # Show/hide
             for key, value in widget._state.items():
                 if key in self._FIXED_STATE_KEYS: