pgwidgets-python 0.1.3__tar.gz → 0.2.0__tar.gz

pgwidgets_python-0.2.0/.github/workflows/tests.yml

@@ -0,0 +1,28 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with test dependencies
+        run: pip install -e ".[test]"
+
+      - name: Run tests
+        run: pytest tests/ -v

{pgwidgets_python-0.1.3 → pgwidgets_python-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.1.3
+Version: 0.2.0
 Summary: Python bindings for the pgwidgets JavaScript widget library
 Author: PGWidgets Developers
 License: BSD-3-Clause
@@ -33,6 +33,11 @@ Python bindings for the [pgwidgets](https://github.com/naojsoft/pgwidgets-js)
 JavaScript widget library. Build desktop-style browser UIs from Python
 with a familiar Qt/GTK-style API.
 
+## Documentation
+
+Full documentation is available at
+[pgwidgets-python.readthedocs.io](https://pgwidgets-python.readthedocs.io/en/latest/).
+
 ## Installation
 
 ```bash
@@ -116,6 +121,35 @@ back over WebSocket. Python widget constructors and method calls are
 translated to JSON messages and executed in the browser. Callbacks are
 forwarded back to Python.
 
+## Sessions and Reconnection
+
+Sessions persist independently of browser connections. When a browser
+disconnects (page refresh, network drop, tab close), the session and its
+widget tree remain alive on the Python side. When the browser reconnects,
+the entire UI is automatically reconstructed.
+
+```python
+app = Application(max_sessions=4, logger=logger)
+
+@app.on_connect
+def setup(session):
+    Widgets = session.get_widgets()
+    # Build your UI...
+    # If the browser refreshes, this UI is reconstructed automatically.
+```
+
+**Key features:**
+
+- **Automatic reconstruction** -- refresh the browser and the UI reappears
+  in its current state (widget positions, text, slider values, etc.).
+- **Multi-browser support** -- open the same session URL in a second browser
+  tab or window. Both browsers show the same UI and stay synchronized.
+  Widget state changes (slider moves, tab switches, tree expand/collapse)
+  are pushed to all connected browsers in real time.
+- **Headless sessions** -- create sessions without a browser using
+  `app.create_session()`, build the widget tree, then connect a browser
+  later to see the pre-built UI.
+
 ## License
 
 BSD 3-Clause

{pgwidgets_python-0.1.3 → pgwidgets_python-0.2.0}/README.md

@@ -4,6 +4,11 @@ Python bindings for the [pgwidgets](https://github.com/naojsoft/pgwidgets-js)
 JavaScript widget library. Build desktop-style browser UIs from Python
 with a familiar Qt/GTK-style API.
 
+## Documentation
+
+Full documentation is available at
+[pgwidgets-python.readthedocs.io](https://pgwidgets-python.readthedocs.io/en/latest/).
+
 ## Installation
 
 ```bash
@@ -87,6 +92,35 @@ back over WebSocket. Python widget constructors and method calls are
 translated to JSON messages and executed in the browser. Callbacks are
 forwarded back to Python.
 
+## Sessions and Reconnection
+
+Sessions persist independently of browser connections. When a browser
+disconnects (page refresh, network drop, tab close), the session and its
+widget tree remain alive on the Python side. When the browser reconnects,
+the entire UI is automatically reconstructed.
+
+```python
+app = Application(max_sessions=4, logger=logger)
+
+@app.on_connect
+def setup(session):
+    Widgets = session.get_widgets()
+    # Build your UI...
+    # If the browser refreshes, this UI is reconstructed automatically.
+```
+
+**Key features:**
+
+- **Automatic reconstruction** -- refresh the browser and the UI reappears
+  in its current state (widget positions, text, slider values, etc.).
+- **Multi-browser support** -- open the same session URL in a second browser
+  tab or window. Both browsers show the same UI and stay synchronized.
+  Widget state changes (slider moves, tab switches, tree expand/collapse)
+  are pushed to all connected browsers in real time.
+- **Headless sessions** -- create sessions without a browser using
+  `app.create_session()`, build the widget tree, then connect a browser
+  later to see the pre-built UI.
+
 ## License
 
 BSD 3-Clause

pgwidgets_python-0.2.0/docs/WhatsNew.rst

@@ -0,0 +1,162 @@
+What's New
+==========
+
+Significant changes since the last tagged release (``v0.1.3``).
+
+Major changes
+-------------
+
+TreeView / TableView: dict-tree model
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Mirroring the JS-side rewrite, ``TreeView`` and ``TableView`` now
+work with hierarchies of dicts keyed by stable string identifiers.
+Paths are arrays of those keys and stay valid no matter how the
+visible tree is sorted.
+
+.. code-block:: python
+
+   tree = W.TreeView(columns=[
+       {"label": "Name", "key": "NAME", "type": "string"},
+       {"label": "Type", "key": "TYPE", "type": "string"},
+       {"label": "Size", "key": "SIZE", "type": "integer"},
+   ], sortable=True)
+
+   tree.set_tree({
+       "Documents": {
+           "report.pdf": {"TYPE": "PDF",  "SIZE": 2400},
+           "notes.txt":  {"TYPE": "Text", "SIZE": 12},
+       },
+       "Pictures": {
+           "photo.jpg": {"TYPE": "JPEG", "SIZE": 3200},
+       },
+   })
+
+Highlights:
+
+- New column-key-based API: ``set_column_width(col_key)``,
+  ``sort_by_column(col_key, ascending)``,
+  ``insert_column(column, before=None)``,
+  ``delete_column(col_key)``,
+  ``set_cell(path, col_key, value)``,
+  ``set_column_editable(col_key, tf)``.
+- New column types: ``"string"`` / ``"integer"`` / ``"float"`` /
+  ``"boolean"`` (renders ✓ when truthy) / ``"icon"``.
+  ``halign`` field with sensible per-type defaults.
+- New tree methods:
+
+  - ``add_tree(tree, parent=None)`` -- merge a dict-tree under a
+    parent path (preserves selection by path).
+  - ``update_tree(tree)`` -- replace the tree, preserve selection.
+  - ``get_subtree(status='all')`` -- return a connected subset
+    (selected / expanded / collapsed nodes plus their descendants
+    and ancestors), round-trippable through ``set_tree``.
+  - ``clear_selection()`` -- explicit no-arg reset.
+
+- Auto-spanning: a row whose value for a column is missing causes
+  the previous present cell to extend across it.  Lets parent rows
+  be terse: ``{"NAME": "Documents"}`` (with the rest of the columns
+  omitted) renders as a single cell across the row.
+- ``TableView.set_data`` accepts a list of dicts (preferred) or a
+  list of arrays.
+
+See :doc:`widgets` for the full reference.
+
+Window controls (TopLevel) and shade (MDISubWindow)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``TopLevel`` gains the same window controls that ``MDISubWindow``
+has, plus a "shade" (roll up to title bar) state on both.
+
+New ``TopLevel`` options (default ``False`` except ``shadeable``
+which defaults ``True``):
+
+- ``minimizable`` -- show minimize button.  Minimized windows
+  auto-stack along the bottom of the viewport.
+- ``maximizable`` -- show maximize button.  Fills the browser
+  viewport (snapshot at click time).
+- ``lowerable`` -- show send-to-back button.
+- ``shadeable`` -- collapse to title bar in place.  Available from
+  the right-click context menu and via double-click on the title
+  bar.
+- ``icon`` -- title-bar icon (URL or ``data:`` URI).
+
+New methods: ``set_icon(url)``, ``toggle_minimize()``,
+``toggle_maximize()``, ``toggle_shade()``,
+``set_window_state(state)``, ``get_window_state()``.
+
+New callback ``window-state`` is auto-tracked, so the
+minimize/maximize/shade state survives a browser reconnect.
+
+``MDIWidget.add_widget`` accepts ``shadeable`` (default ``True``).
+
+Right-click on the title bar of either widget opens a context menu
+with the applicable actions (Raise, Lower, Shade, Minimize,
+Maximize, Close).  The menu supports both click-release and
+press-drag-release, like a menubar.
+
+Image: binary-frame protocol
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New method ``Image.set_binary_image(data, format='jpeg')`` sends raw
+bytes (``bytes`` / ``bytearray`` / ``memoryview``) via a WebSocket
+binary frame, avoiding the ~33% base64 overhead of ``set_image``.
+Useful for animation/streaming.  ``format`` is one of ``"jpeg"``,
+``"png"``, ``"webp"``, ``"gif"``.  The latest frame is stored in
+widget state and replayed on reconnect.
+
+Callbacks base class
+~~~~~~~~~~~~~~~~~~~~
+
+New module ``pgwidgets.callbacks`` exposes ``Callbacks``, a small
+base class that provides the same callback API (``add_callback``,
+``on``, ``make_callback``, ``enable_callback``, ...) as a real
+``Widget`` without the widget machinery.  Use it for Python-side
+composite/utility classes that need to expose handler registration.
+
+``FileBrowser`` (in ``pgwidgets.extras``) is now a subclass and so
+supports both ``add_callback("activated", ...)`` and
+``on("activated", ...)`` directly.
+
+See :ref:`callbacks-base`.
+
+Robustness improvements
+-----------------------
+
+- ``Session._send`` and ``_send_binary`` no longer hang when the
+  asyncio loop refuses a coroutine (loop closed mid-call,
+  ``RecursionError`` from a deep callback chain, etc.).  The
+  schedule failure is logged, the orphan coroutine is closed, and
+  ``_send`` returns ``None`` so the caller continues.
+- ``json.dumps`` errors in ``_send`` / ``_push`` are caught and
+  logged instead of crashing reconstruction with a non-JSON-
+  serialisable widget state.
+- After every ``create``, ``Session._next_wid`` is advanced past
+  the JS-side ``next_wid`` so subsequent Python allocations skip
+  any auto-allocated sub-widget IDs (matching the JS-side
+  collision rescue).  This fixes "callback fires on the wrong
+  widget" cases where a widget like ``TreeView`` allocates
+  internal ``ScrollBar`` widgets in its constructor.
+
+Other notable changes
+---------------------
+
+- ``ColorDialog`` now exposes ``popup``, ``set_position``,
+  ``set_modal``, and the ``move`` / ``close`` callbacks (inherited
+  from ``Dialog`` on the JS side).  Its ``popup`` is wired through
+  the ``_dialog_popup`` custom method so visibility/position state
+  is tracked for reconstruction.
+- ``MenuAction`` ``activated`` callback signature simplified.  Old:
+  ``handler(widget, text, checked)``.  New: ``handler(widget)`` for
+  non-checkable actions; ``handler(widget, checked)`` for checkable
+  ones.  *This is a breaking change for any handler that took the
+  text arg.*
+- ``Widget`` base class now exposes
+  ``set_allow_text_selection(tf)``; browser text selection is off
+  by default for most widgets (form controls and the cell editor
+  in ``TreeView`` always allow selection).
+- ``clear()`` on ``TreeView`` / ``TableView`` no longer resets the
+  ``columns`` state (it was popping ``_state["columns"]`` even
+  though the JS side preserves columns on clear).
+- ``FileBrowser`` migrated to the new dict-tree ``TableView`` API
+  internally and now subclasses ``Callbacks``.

pgwidgets_python-0.2.0/docs/architecture.rst

@@ -0,0 +1,180 @@
+Architecture
+============
+
+Overview
+--------
+
+pgwidgets follows a client-server architecture. Python is the server; the
+browser is the client. Widget constructors and method calls in Python are
+translated to JSON messages and sent over WebSocket to the browser, where the
+pgwidgets JavaScript library executes them. User interactions (clicks, input,
+etc.) travel back as callback messages.
+
+::
+
+   Python (server)                     Browser (client)
+   +-----------------+                 +------------------+
+   | Application     |   WebSocket    | pgwidgets JS     |
+   |   Session  <----|----JSON------->|   widget tree     |
+   |     widgets     |                |   DOM rendering   |
+   +-----------------+                +------------------+
+          |
+          | HTTP (static files)
+          v
+   JS/CSS assets served to browser
+
+Servers
+-------
+
+The ``Application`` class starts two servers:
+
+**HTTP server** (default port 9501)
+   Serves the pgwidgets JavaScript/CSS assets and a connector HTML page.
+   When a browser hits ``/``, it gets ``remote.html`` with the WebSocket URL
+   injected. Set ``http_server=False`` if you serve the static files from
+   your own web server (Flask, FastAPI, nginx, etc.).
+
+**WebSocket server** (default port 9500)
+   Carries the JSON command protocol. Each browser tab opens one WebSocket
+   connection, which becomes one ``Session``.
+
+JSON Protocol
+-------------
+
+All messages are JSON objects with a ``type`` field.
+
+**Python -> Browser:**
+
+- ``{"type": "init", "id": 0}`` -- handshake initiation.
+- ``{"type": "session-info", "session_id": 1, "token": "..."}`` --
+  session credentials for reconnection.
+- ``{"type": "create", "wid": 1, "class": "Button", "args": ["Click"]}`` --
+  create a widget.
+- ``{"type": "call", "wid": 1, "method": "set_text", "args": ["New"]}`` --
+  call a method on a widget.
+- ``{"type": "call", ..., "silent": true}`` -- call a method without
+  triggering callbacks (used for cross-browser sync).
+- ``{"type": "listen", "wid": 1, "action": "activated"}`` -- subscribe to a
+  callback.
+- ``{"type": "unlisten", "wid": 1, "action": "activated"}`` -- unsubscribe.
+- ``{"type": "reconstruct-start", "next_wid": N}`` -- begin UI reconstruction.
+- ``{"type": "reconstruct-end"}`` -- end UI reconstruction.
+
+**Browser -> Python:**
+
+- ``{"type": "ack", "session_id": 1, "token": "..."}`` -- handshake
+  acknowledgment (includes session credentials when reconnecting).
+- ``{"type": "result", "id": 1, "value": ...}`` -- method return value.
+- ``{"type": "error", "id": 1, "error": "..."}`` -- method error.
+- ``{"type": "callback", "wid": 1, "action": "activated", "args": [...]}`` --
+  user interaction.
+- ``{"type": "file-chunk", ...}`` -- chunked file data (see :doc:`callbacks`).
+
+Session Model
+-------------
+
+Each browser connection gets a ``Session`` object. Sessions persist
+independently of browser connections -- they survive page refreshes,
+network drops, and tab closes. Python is the source of truth for all
+widget state.
+
+A session owns:
+
+- A widget tree with full state tracking (text, colors, sizes, children, etc.)
+- A callback registry (``"wid:action"`` -> handler function)
+- A list of active browser connections
+- A security token for reconnection
+- A message-ID counter for request/response matching
+
+Multiple sessions can be active concurrently (controlled by ``max_sessions``).
+
+Lifecycle:
+
+1. Browser opens the URL and loads ``remote.html``.
+2. JavaScript connects to the WebSocket server.
+3. Python sends ``init``; browser acknowledges with session info (if reconnecting).
+4. For a **new** connection: ``on_connect`` fires with a new ``Session``.
+5. For a **reconnection**: the existing session's UI is automatically
+   reconstructed in the browser.
+6. User code creates widgets, registers callbacks.
+7. When a browser disconnects, ``on_disconnect`` fires. The session
+   remains alive for reconnection.
+8. Sessions are only destroyed when ``session.destroy()`` is called explicitly.
+
+Reconnection and Reconstruction
+--------------------------------
+
+When a browser reconnects to an existing session (e.g. after a page refresh),
+the framework walks the widget tree and replays every widget's creation,
+state, children, and callbacks. The browser receives the full UI as if it
+were being built for the first time.
+
+The reconstruction process:
+
+1. Clean up stale auto-wrapped widget references from the previous connection.
+2. Send ``reconstruct-start`` so the browser suppresses callback echo.
+3. For each widget (parents before children):
+
+   a. Create the widget with its original constructor arguments.
+   b. Replay item lists (e.g. ComboBox items).
+   c. Replay state changes (text, colors, size, position, etc.).
+   d. Attach to parent via the same child method used originally.
+   e. Replay factory calls (menu actions, toolbar actions, separators).
+   f. Re-register all callbacks.
+   g. Re-register auto-sync listeners.
+
+4. Replay deferred state (splitter sizes, tab/stack index, tree collapse state).
+5. Replay show/hide state.
+6. Send ``reconstruct-end``.
+
+Multi-Browser Synchronization
+-----------------------------
+
+Multiple browsers can connect to the same session simultaneously. When one
+browser triggers a state change (slider move, tab switch, tree expand, etc.),
+the change is pushed to all other connected browsers in real time.
+
+::
+
+   Browser A                Python (session)              Browser B
+   +---------+              +---------------+              +---------+
+   | slider  |---callback-->| update state  |---push------>| slider  |
+   | moved   |              | in _state     |  (silent)    | updated |
+   +---------+              +---------------+              +---------+
+
+The push uses a ``silent`` flag so the receiving browser suppresses callback
+echo, preventing infinite feedback loops.
+
+State changes that are synchronized include:
+
+- Widget state: slider values, checkbox state, text content, tab index, etc.
+- Layout: move and resize of windows and MDI subwindows.
+- Tree/table: expand, collapse, and sort operations.
+- Child management: closing MDI subwindows or tab pages.
+
+Headless Sessions
+-----------------
+
+Sessions can be created without a browser using
+``app.create_session()``. The widget tree can be built up before any
+browser connects. When a browser navigates to the session URL, the
+pre-built UI is reconstructed automatically.
+
+.. code-block:: python
+
+   session = app.create_session()
+   Widgets = session.get_widgets()
+   top = Widgets.TopLevel(title="Pre-built UI")
+   top.show()
+   # ... build the full UI ...
+   # When a browser connects with this session's ID and token,
+   # the UI appears immediately.
+
+Widget References
+-----------------
+
+Widgets are identified by integer IDs (``wid``). When a Python widget is
+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.

{pgwidgets_python-0.1.3 → pgwidgets_python-0.2.0}/docs/async.rst

@@ -59,17 +59,42 @@ Running
 Session
 -------
 
-The async ``Session`` has the same interface as the sync version, but methods
-are coroutines:
+The async ``Session`` has the same interface as the sync version, but most
+methods are coroutines. Sessions persist independently of browser connections,
+support reconnection and multi-browser synchronization (see :doc:`sync` for
+details on these features).
 
 .. code-block:: python
 
    Widgets = session.get_widgets()          # sync -- returns namespace
    btn = await Widgets.Button("Click me")   # async -- creates widget
    await btn.set_text("New text")           # async -- calls method
+   text = btn.get_text()                    # sync -- returns from local state
    await session.close()                    # async
    timer = await session.make_timer(duration=1000)  # async
 
+**Properties:**
+
+- ``session.id`` -- unique session identifier.
+- ``session.app`` -- the owning ``Application``.
+- ``session.token`` -- security token for reconnection.
+- ``session.is_connected`` -- ``True`` if at least one browser is connected.
+- ``session.connections`` -- list of active WebSocket connections.
+
+**Getter methods** (``get_text()``, ``get_value()``, ``is_visible()``, etc.)
+return from local state without a browser round-trip and do **not** need to
+be awaited. All other widget methods (setters, actions, child methods) are
+coroutines and must be awaited.
+
+Creating Sessions Without a Browser
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   session = app.create_session()
+   # Build widgets -- sends are queued; no browser needed.
+   # Connect a browser later to see the pre-built UI.
+
 Concurrency Modes
 -----------------
 

{pgwidgets_python-0.1.3 → pgwidgets_python-0.2.0}/docs/callbacks.rst

@@ -77,11 +77,17 @@ common patterns:
      - Dialog
      - ``(button_text: str)``
    * - ``page-switch``
-     - TabWidget, StackWidget
-     - ``(index: int)``
+     - TabWidget, StackWidget, MDIWidget
+     - ``(child: Widget, index: int)``
    * - ``page-close``
-     - TabWidget, MDIWidget
-     - ``(index: int)``
+     - TabWidget, StackWidget, MDIWidget
+     - ``(child: Widget)``
+   * - ``child-added``
+     - All containers
+     - ``(child: Widget)``
+   * - ``child-removed``
+     - All containers
+     - ``(child: Widget)``
    * - ``selected``
      - TreeView, TableView
      - ``(selected_items)``