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

pgwidgets/tree_model.py

@@ -0,0 +1,356 @@
+"""Python-side model of TreeView / TableView content.
+
+pgwidgets-python drives the browser over a websocket: the browser is a
+*view* that can be discarded and rebuilt at any moment -- a page reload, a
+network blip, a second browser attaching to the same session.  Everything
+needed to rebuild it therefore has to live on the Python side, which is the
+source of truth.
+
+Historically only the bulk calls (``set_tree`` / ``set_rows`` /
+``set_columns``) were tracked, and every later mutation -- ``set_cell``,
+``add_item``, ``add_tree``, ``delete_tree``, the row and column edits --
+was fire-and-forget.  A reconnect then replayed the *original* bulk
+snapshot, silently reverting every change made since.  These helpers keep
+the model current as those calls go by, so reconstruction replays one
+accurate ``set_tree`` / ``set_rows``.
+
+Having the model on hand also makes ``update_tree`` incremental: rather
+than shipping the whole tree and having the browser rebuild it (losing
+expansion state, cell styles and any open editor), :func:`diff_tree`
+computes the minimal set of operations against the model and only those go
+over the wire.
+
+Everything here is a pure function over plain dicts and lists, so the sync
+and async wrappers share one implementation and it can be tested without a
+session or a browser.
+
+Tree shape (mirroring the JS side)
+----------------------------------
+A tree is a dict keyed by stable string ids.  A node's children are its
+dict-valued entries; its own column values are either the ``__values__``
+entry, when present, or its primitive entries.  A node with no dict-valued
+entries is a leaf, and the dict *is* its column values.
+"""
+
+import copy
+
+VALUES_KEY = '__values__'
+
+_MISSING = object()
+
+__all__ = ['VALUES_KEY', 'node_at', 'children_of', 'values_of',
+           'values_target', 'copy_tree', 'set_cell', 'add_item',
+           'remove_item', 'remove_items', 'merge_tree', 'delete_tree',
+           'diff_tree', 'row_set_cell', 'insert_row', 'append_row',
+           'delete_row', 'column_key', 'insert_column', 'append_column',
+           'delete_column']
+
+
+# ----- tree navigation ---------------------------------------------
+
+def copy_tree(tree):
+    """Return a deep copy, so the model can't be mutated behind our back
+    by a caller that keeps and edits the structure it handed us."""
+    try:
+        return copy.deepcopy(tree)
+    except Exception:
+        # exotic values (e.g. an unpicklable object stashed in a row)
+        # -- fall back to sharing rather than failing the call
+        return tree
+
+
+def node_at(tree, path):
+    """Return the node at `path` (a sequence of keys), or None.
+
+    An empty path denotes the root, i.e. `tree` itself.
+    """
+    node = tree
+    for key in (path or ()):
+        if not isinstance(node, dict) or key not in node:
+            return None
+        node = node[key]
+    return node
+
+
+def children_of(node):
+    """Return {key: child} for a node's dict-valued entries."""
+    if not isinstance(node, dict):
+        return {}
+    return {k: v for k, v in node.items()
+            if k != VALUES_KEY and isinstance(v, dict)}
+
+
+def values_of(node):
+    """Return a node's column values (read-only use)."""
+    if not isinstance(node, dict):
+        return {}
+    vals = node.get(VALUES_KEY)
+    if isinstance(vals, dict):
+        return vals
+    return {k: v for k, v in node.items() if not isinstance(v, dict)}
+
+
+def values_target(node):
+    """Return the dict a node's column values should be *written* to.
+
+    That is ``__values__`` for an interior node that carries one, else the
+    node itself (a leaf, or an interior whose values sit alongside its
+    children).
+    """
+    if not isinstance(node, dict):
+        return None
+    vals = node.get(VALUES_KEY)
+    if isinstance(vals, dict):
+        return vals
+    return node
+
+
+# ----- tree mutation -----------------------------------------------
+
+def set_cell(tree, path, col_key, value):
+    """Write one column value.  Returns True if the path resolved."""
+    node = node_at(tree, path)
+    target = values_target(node)
+    if target is None:
+        return False
+    target[col_key] = value
+    return True
+
+
+def add_item(tree, parent, key, values):
+    """Add/replace a single child under `parent` (None/[] = root)."""
+    node = node_at(tree, parent)
+    if not isinstance(node, dict):
+        return False
+    node[key] = copy_tree(values) if isinstance(values, dict) else values
+    return True
+
+
+def remove_item(tree, path):
+    """Remove the node at `path` together with its subtree."""
+    if not path:
+        return False
+    parent = node_at(tree, path[:-1])
+    if not isinstance(parent, dict) or path[-1] not in parent:
+        return False
+    del parent[path[-1]]
+    return True
+
+
+def remove_items(tree, paths):
+    return sum(1 for p in (paths or []) if remove_item(tree, p))
+
+
+def merge_tree(tree, subtree, parent=None):
+    """Merge `subtree` under `parent`, replacing same-key children
+    subtree-deep -- the semantics of the JS ``add_tree``."""
+    node = node_at(tree, parent)
+    if not isinstance(node, dict) or not isinstance(subtree, dict):
+        return False
+    for key, value in subtree.items():
+        node[key] = copy_tree(value) if isinstance(value, dict) else value
+    return True
+
+
+def delete_tree(tree, spec, prune_empty=True):
+    """Delete the nodes named by `spec`, mirroring the JS ``_deleteSpec``.
+
+    A key mapping to an empty dict (or a non-dict) removes that node and
+    its whole subtree; a key mapping to a non-empty dict is descended into
+    so only the named descendants go.  Keys absent from the tree are
+    ignored.  With `prune_empty`, a branch left childless is removed too,
+    cascading upward.  Returns the number of nodes removed.
+    """
+    def _delete(node, sub_spec):
+        count = 0
+        for key in list(sub_spec.keys()):
+            if not isinstance(node, dict) or key not in node:
+                continue          # not present; skip
+            child = node[key]
+            sub = sub_spec[key]
+            descend = (isinstance(sub, dict) and len(sub) > 0
+                       and len(children_of(child)) > 0)
+            if not descend:
+                del node[key]
+                count += 1
+            else:
+                count += _delete(child, sub)
+                if prune_empty and len(children_of(child)) == 0:
+                    del node[key]
+                    count += 1
+        return count
+
+    return _delete(tree, spec or {})
+
+
+# ----- tree diffing -------------------------------------------------
+
+def _count_nodes(tree):
+    total = 0
+    for child in children_of(tree).values():
+        total += 1 + _count_nodes(child)
+    return total
+
+
+def diff_tree(old, new, max_ops=None):
+    """Return the operations that turn `old` into `new`.
+
+    Each operation is a tuple ``(method_name, *args)`` ready to dispatch
+    at the browser: ``remove_items``, ``add_tree`` and ``set_cell``.
+    Deletions are emitted first so additions never collide with a node on
+    its way out.
+
+    Returns None when the trees differ so broadly that replacing the whole
+    thing is cheaper than patching it -- the caller should fall back to
+    ``set_tree``.  `max_ops` defaults to the node count of `new`.
+    """
+    removals = []
+    additions = []
+    updates = []
+
+    def walk(old_node, new_node, path):
+        old_children = children_of(old_node)
+        new_children = children_of(new_node)
+
+        for key in old_children:
+            if key not in new_children:
+                removals.append(list(path) + [key])
+
+        for key, new_child in new_children.items():
+            old_child = old_children.get(key, _MISSING)
+            if old_child is _MISSING:
+                additions.append((list(path), key, new_child))
+            else:
+                walk(old_child, new_child, tuple(path) + (key,))
+
+        if path:      # the root has no column values of its own
+            old_vals = values_of(old_node)
+            new_vals = values_of(new_node)
+            for col_key, value in new_vals.items():
+                if old_vals.get(col_key, _MISSING) != value:
+                    updates.append((list(path), col_key, value))
+
+    walk(old if isinstance(old, dict) else {},
+         new if isinstance(new, dict) else {}, ())
+
+    if max_ops is None:
+        max_ops = max(_count_nodes(new), 1)
+    if len(removals) + len(additions) + len(updates) > max_ops:
+        return None       # wholesale replacement is cheaper
+
+    ops = []
+    if removals:
+        ops.append(('remove_items', removals))
+    for parent, key, node in additions:
+        ops.append(('add_tree', {key: node}, parent or None))
+    for path, col_key, value in updates:
+        ops.append(('set_cell', path, col_key, value))
+    return ops
+
+
+# ----- flat rows (TableView) ----------------------------------------
+
+def column_key(column, index=None):
+    """Extract a column's key from any descriptor form."""
+    if isinstance(column, dict):
+        return column.get('key') or column.get('label') or (
+            f'col{index}' if index is not None else None)
+    if isinstance(column, (list, tuple)):
+        return column[1] if len(column) > 1 else column[0]
+    return column
+
+
+def row_set_cell(rows, columns, row, col, value):
+    """Write one cell of a flat row list.
+
+    `row` is an index; `col` is a column key or index.  Rows may be dicts
+    (keyed by column key) or positional sequences.
+    """
+    if not isinstance(rows, list) or not isinstance(row, int):
+        return False
+    if not (0 <= row < len(rows)):
+        return False
+    keys = [column_key(c, i) for i, c in enumerate(columns or [])]
+    target = rows[row]
+    if isinstance(target, dict):
+        key = col if not isinstance(col, int) else (
+            keys[col] if 0 <= col < len(keys) else None)
+        if key is None:
+            return False
+        target[key] = value
+        return True
+    if isinstance(target, list):
+        idx = col if isinstance(col, int) else (
+            keys.index(col) if col in keys else None)
+        if idx is None or not (0 <= idx < len(target)):
+            return False
+        target[idx] = value
+        return True
+    return False
+
+
+def insert_row(rows, index, values):
+    if not isinstance(rows, list):
+        return False
+    if not isinstance(index, int) or index < 0 or index > len(rows):
+        index = len(rows)          # out of range clamps to append, as in JS
+    rows.insert(index, copy_tree(values))
+    return True
+
+
+def append_row(rows, values):
+    if not isinstance(rows, list):
+        return False
+    rows.append(copy_tree(values))
+    return True
+
+
+def delete_row(rows, index):
+    if not isinstance(rows, list) or not isinstance(index, int):
+        return False
+    if not (0 <= index < len(rows)):
+        return False
+    del rows[index]
+    return True
+
+
+# ----- columns -------------------------------------------------------
+
+def insert_column(columns, column, before=None, index=None):
+    """Insert a column.
+
+    TreeView names the insertion point by column key (`before`); TableView
+    by position (`index`).  Pass whichever the caller supplied.
+    """
+    if not isinstance(columns, list):
+        return False
+    if index is None and before is not None:
+        keys = [column_key(c, i) for i, c in enumerate(columns)]
+        index = keys.index(before) if before in keys else len(columns)
+    if not isinstance(index, int) or index < 0 or index > len(columns):
+        index = len(columns)
+    columns.insert(index, copy_tree(column))
+    return True
+
+
+def append_column(columns, column):
+    if not isinstance(columns, list):
+        return False
+    columns.append(copy_tree(column))
+    return True
+
+
+def delete_column(columns, col):
+    """Delete by column key (TreeView) or by index (TableView)."""
+    if not isinstance(columns, list):
+        return False
+    if isinstance(col, int):
+        if not (0 <= col < len(columns)):
+            return False
+        del columns[col]
+        return True
+    keys = [column_key(c, i) for i, c in enumerate(columns)]
+    if col not in keys:
+        return False
+    del columns[keys.index(col)]
+    return True

{pgwidgets_python-0.3.4.dist-info → pgwidgets_python-0.4.0.dist-info}/METADATA

@@ -1,15 +1,14 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.3.4
+Version: 0.4.0
 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
@@ -17,7 +16,7 @@ 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.0
 Requires-Dist: websockets>=12
 Provides-Extra: dev
 Requires-Dist: sphinx; extra == "dev"

{pgwidgets_python-0.3.4.dist-info → pgwidgets_python-0.4.0.dist-info}/RECORD

@@ -3,24 +3,23 @@ pgwidgets/_json.py,sha256=o21qywJ6yAldbqxTq3nLwgK9O67r3a8JxhvI_WAJnMY,2184
 pgwidgets/buffer.py,sha256=BYj_nb6fuyGsBqUp3_Z1YrzUm4h5VmoWPGKvpTjWrYk,4048
 pgwidgets/callbacks.py,sha256=gA2FnX0N5BmbmOMyEV35yHySgAfVjfAZcZhZbo7j4-c,3314
 pgwidgets/defs.py,sha256=Q8qhvTeansFU1Av6j5ncdwF2xSNHrpXuKErdHWQ3HiA,436
-pgwidgets/method_types.py,sha256=m4jyBchh3CbS-n1vaKoyMkw0Vd5IVeHIKgUEeMiJMu0,18328
+pgwidgets/method_types.py,sha256=XDT8EfE6UWFcs_S2moqZs3SulUDLIjwNFx6UigNAeRk,24811
 pgwidgets/text_model.py,sha256=xlSAoh1ikIG9ZYVwx5wHWrohkGkyu7R6Cbs36_xnbMg,29313
+pgwidgets/tree_model.py,sha256=agif6vSeLzcGfLe1tB-O2MIkXv7Qgb53uWMoTXDSgAc,12144
 pgwidgets/async_/Widgets.py,sha256=vld2xkvusBBEVbhbezaJsjBRRj3L7c17Up0pOVs8PGo,723
 pgwidgets/async_/__init__.py,sha256=rXB-v9XRrYt1imYuYikhkzIyiRqaYhlTpQei2LHaQ18,564
-pgwidgets/async_/application.py,sha256=2RJNRerXu5LXG_UcMSi9HWOCAlEOu96TrRaoIcUZ86Q,80957
-pgwidgets/async_/widget.py,sha256=gO7eJh9LV3UY7yRLdeml_0gqmHnFB5VU3NWlDURLtfc,38042
+pgwidgets/async_/application.py,sha256=U-D1WzazOnuuZQ1djQS2vZyS-xtcRY0RVWtbgr0bCrQ,85368
+pgwidgets/async_/widget.py,sha256=nHWszUHXgwv37SOmvjA2AqGNYdxOVaEugPOjfRrwB48,57043
 pgwidgets/extras/__init__.py,sha256=AXUmFtnn4RSlp6pJX6z55j-m_29VmfzpYIjQvAy7pO0,325
 pgwidgets/extras/file_browser.py,sha256=Lkz_n56_YW7rV_k8pmhgZrwulGsujk9vrzv66zgIgec,17347
 pgwidgets/icons/pgw-python-logo.png,sha256=_Rxicp9EKy2Pzz1HtobxEnntSI-y5TtAVPlIzZIsfYs,2428840
 pgwidgets/sync/Widgets.py,sha256=7SaocMVMzFHhi51pjuEAr47Wez90b_a61kDbiv0jOfM,706
 pgwidgets/sync/__init__.py,sha256=SF5RTAvtu8BbYBWzpiCPipy6DJzNXf6nqk9xdvwxUhQ,542
-pgwidgets/sync/application.py,sha256=cjF7Ql3Ukkpb_wv39kdOxkwImmr30tuRNRaaCwnDcc8,96832
+pgwidgets/sync/application.py,sha256=WOWQAR8FeieVWjwc9yHFHqGposBdZk8AcGqIKj27bwM,102478
 pgwidgets/sync/text_source.py,sha256=Vz8mJsQXLFOAVwZCOrAXSixNfYQHjYZxxAIZjWBCAnY,8341
-pgwidgets/sync/widget.py,sha256=Kw2CQFOaa7rfroKfn0MwNwXT-PjoecqCErav5BEc0UI,38652
-pgwidgets_python-0.3.4.dist-info/licenses/LICENSE.md,sha256=LoM3fMTiMnQuHRCJghdjOtjnCrL8soBpu2PFk24Xvyg,1528
-pgwidgets_python-0.3.4.dist-info/METADATA,sha256=mYbCrbwXb_7AJTTFzc8lx0wekc5xXCvtPob88f6qQn4,4683
-pgwidgets_python-0.3.4.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-pgwidgets_python-0.3.4.dist-info/scm_file_list.json,sha256=IYU1Sj8wmNZV5NJbOcAqZMFFo3cJDmHEHVO9yNzJeoA,2044
-pgwidgets_python-0.3.4.dist-info/scm_version.json,sha256=1gVS2afyYI_kYay3yptOGjKz_RV3I2woNhdQjYuuLNU,160
-pgwidgets_python-0.3.4.dist-info/top_level.txt,sha256=wwL6fBq0gU-JwzlM6TdduY1qYpu39ysqnnbQT-1bqAs,10
-pgwidgets_python-0.3.4.dist-info/RECORD,,
+pgwidgets/sync/widget.py,sha256=gp7cio4uB822hrk-AcqoGWsOsABaweB5wUpIro3yV0g,57455
+pgwidgets_python-0.4.0.dist-info/licenses/LICENSE.md,sha256=LoM3fMTiMnQuHRCJghdjOtjnCrL8soBpu2PFk24Xvyg,1528
+pgwidgets_python-0.4.0.dist-info/METADATA,sha256=-lBgjLX8ifsJ7rtF7HqniV8I_JN2fmBGv8mr11kCnEs,4643
+pgwidgets_python-0.4.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pgwidgets_python-0.4.0.dist-info/top_level.txt,sha256=wwL6fBq0gU-JwzlM6TdduY1qYpu39ysqnnbQT-1bqAs,10
+pgwidgets_python-0.4.0.dist-info/RECORD,,

{pgwidgets_python-0.3.4.dist-info → pgwidgets_python-0.4.0.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: setuptools (83.0.0)
+Generator: setuptools (84.0.0)
 Root-Is-Purelib: true
 Tag: py3-none-any
 

pgwidgets_python-0.3.4.dist-info/scm_file_list.json

@@ -1,71 +0,0 @@
-{
-  "files": [
-    ".flake8",
-    "test_pg2.py",
-    "README.md",
-    "pyproject.toml",
-    "LICENSE.md",
-    ".readthedocs.yaml",
-    ".gitignore",
-    "docs/web-servers.rst",
-    "docs/WhatsNew.rst",
-    "docs/subclassing.rst",
-    "docs/sync.rst",
-    "docs/utilities.rst",
-    "docs/extras.rst",
-    "docs/async.rst",
-    "docs/architecture.rst",
-    "docs/widgets.rst",
-    "docs/conf.py",
-    "docs/Makefile",
-    "docs/index.rst",
-    "docs/callbacks.rst",
-    "docs/getting-started.rst",
-    "docs/api/async.rst",
-    "docs/api/sync.rst",
-    "docs/api/index.rst",
-    "tests/test_protocol.py",
-    "tests/__init__.py",
-    "tests/test_stateful.py",
-    "tests/test_resolve_kwargs.py",
-    "tests/test_text_source.py",
-    "tests/test_async_session.py",
-    "tests/test_defs.py",
-    "tests/test_fonts.py",
-    "tests/test_session.py",
-    "tests/test_extras.py",
-    "tests/test_widget_classes.py",
-    "tests/test_reconstruct.py",
-    "pgwidgets/_json.py",
-    "pgwidgets/__init__.py",
-    "pgwidgets/callbacks.py",
-    "pgwidgets/method_types.py",
-    "pgwidgets/buffer.py",
-    "pgwidgets/text_model.py",
-    "pgwidgets/defs.py",
-    "pgwidgets/sync/Widgets.py",
-    "pgwidgets/sync/__init__.py",
-    "pgwidgets/sync/application.py",
-    "pgwidgets/sync/text_source.py",
-    "pgwidgets/sync/widget.py",
-    "pgwidgets/extras/__init__.py",
-    "pgwidgets/extras/file_browser.py",
-    "pgwidgets/icons/pgw-python-logo.png",
-    "pgwidgets/async_/Widgets.py",
-    "pgwidgets/async_/application.py",
-    "pgwidgets/async_/__init__.py",
-    "pgwidgets/async_/widget.py",
-    "examples/demo_sync.py",
-    "examples/all_widgets.py",
-    "examples/all_widgets_async.py",
-    "examples/README.md",
-    "examples/demo_treeview.py",
-    "examples/demo_async.py",
-    "examples/flask-multi-process/server.py",
-    "examples/flask-multi-process/README.md",
-    "examples/flask-multi-process/nginx.conf",
-    "examples/flask-multi-process/gunicorn.conf.py",
-    "examples/flask-multi-process/user_app.py",
-    ".github/workflows/tests.yml"
-  ]
-}

pgwidgets_python-0.3.4.dist-info/scm_version.json

@@ -1,8 +0,0 @@
-{
-  "tag": "0.3.4",
-  "distance": 0,
-  "node": "g723f82b1856fa1a276455b903e3c9131cb62d9a8",
-  "dirty": false,
-  "branch": "main",
-  "node_date": "2026-07-17"
-}