pgwidgets-python 0.2.1__tar.gz → 0.3.0__tar.gz

{pgwidgets_python-0.2.1 → pgwidgets_python-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.2.1
+Version: 0.3.0
 Summary: Python bindings for the pgwidgets JavaScript widget library
 Author: PGWidgets Developers
 License: BSD-3-Clause

{pgwidgets_python-0.2.1 → pgwidgets_python-0.3.0}/docs/WhatsNew.rst

@@ -1,13 +1,146 @@
 What's New
 ==========
 
-Significant changes since the last tagged release (``v0.1.3``).
+Recent changes — since ``v0.2.3``
+---------------------------------
+
+Chunked binary transport (both directions)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Session`` gained ``_send_binary_chunked(wid, method, args, data,
+chunk_size=512KB, shape=None, dtype=None)`` and a matching
+incoming-binary path.  Large payloads automatically use the
+chunked transport — :meth:`Image.set_binary_image` (and the
+reconstruction replay of binary state) auto-pick chunked above a
+1 MiB threshold.  ``Session._handle_file_chunk`` was rewritten as
+``_handle_binary_chunk`` to consume the new binary-chunk
+envelope: chunks store by ``chunk_index`` (robust to ordering)
+and reassemble as ``bytes``.
+
+**Pre-1.0 API break**: drop-end / FileDialog ``activated``
+handlers now receive each file's ``data`` field as raw ``bytes``
+(was a ``"data:<mime>;base64,…"`` string).  Each file dict now
+also carries an ``encoding`` field (currently ``"bytes"``;
+reserved for future ``"base64"``).
+
+:class:`pgwidgets.Buffer` for typed-array delivery
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+New :class:`pgwidgets.Buffer` wraps raw bytes with ``shape`` and
+``dtype`` metadata.  When passed to a binary-aware method, the
+bytes ride the chunked transport and the receiver on the JS side
+gets a typed array of the right shape (``Uint8Array``,
+``Float32Array``, …) without the per-method casting that used to
+be necessary::
+
+   from pgwidgets import Buffer
+   pixels = ...  # 2048 * 2048 * 4 bytes
+   viewer.load_buffer(
+       Buffer(pixels, shape=(2048, 2048, 4), dtype="uint8"),
+       [2048, 2048], cache)
+
+Supported dtypes: ``uint8`` / ``uint16`` / ``uint32`` / ``int8``
+/ ``int16`` / ``int32`` / ``float32`` / ``float64``.
+Construction validates that ``len(data) == prod(shape) *
+itemsize``.
+
+``Application(ws_sock=…)`` for race-free port allocation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+:class:`Application` accepts an optional pre-bound TCP socket via
+``ws_sock=``.  When provided, ``Application`` adopts the socket
+directly (hands it to ``websockets.serve(sock=...)``) instead of
+binding ``(host, ws_port)`` itself, and reads ``ws_port`` back
+from the socket for logging.  The motivation is TOCTOU-free port
+allocation: the caller can bind in advance, hand the socket in,
+and never release the port between "find" and "use" — no other
+process can grab it in the gap.  The existing ``ws_port=`` API
+is unchanged.
+
+Flask multi-process demo
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+New ``examples/flask-multi-process/`` example: one pgwidgets
+``Application`` per visitor, each in its own OS process with its
+own WebSocket port.  Demonstrates the new ``ws_sock=`` parameter
+(child binds, never releases), idle reaping via a grace timer on
+``app.on_disconnect`` that handles the subtle case where
+``app.on_connect`` doesn't fire on session-reconnect (the wrapper
+also hooks ``session.add_connection``), and serving pgwidgets-js's
+static assets from the pip-installed package rather than a CDN.
+
+----
+
+Recent changes — since ``v0.2.1``
+---------------------------------
+
+Reliable ``get_size()`` / ``get_position()`` on every visual widget
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The auto-sync layer that backs widget getters has been reworked so
+``widget.get_size()`` (and ``get_position()`` where supported)
+returns the current layout-determined value for any visual widget,
+not just ones that opted into the ``resizable`` / ``moveable``
+options.  The binding now installs a *passive* resize listener on
+every visual widget — the value is captured into local state for
+the getter, but it is **not** pushed to other connected browsers or
+replayed on reconstruction.  Explicit ``widget.resize(w, h)`` calls
+are still replayed, as is interactive resize on widgets that opted
+into active sync.
+
+The user-visible upshot: code that calls ``image.get_size()`` on an
+``Image`` placed in a flex container now returns the real pixel
+size the browser laid the widget out at, instead of ``None`` or a
+stale value.  And widgets like ``Image`` with
+``set_expanding(True, True)`` no longer get pinned to pixel
+dimensions on reconnect (a regression in earlier auto-sync work).
+
+The same guard now applies in both reconstruction paths
+(top-level state replay AND ``_transfer_proxy`` for factory-created
+widgets like ``ToolBarAction``), which fixes a "toolbar items
+drift farther apart after each reconnect" bug.
+
+``map`` callback survives reconstruction
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The Python side now forwards ``map`` callbacks during a reconstruct
+window instead of suppressing them along with the rest of the
+state-replay echoes.  ``map`` is a one-shot lifecycle event tied to
+the widget first becoming visually present; missing it on the
+Python side meant a user's map handler stayed un-fired until the
+window happened to be resized.  Pairs with the JS-side reliability
+work for the same callback.
+
+Sensible defaults for more getters
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Getters now return useful zero-value defaults before any state has
+been set or reported from the browser, instead of ``None``:
+
+- ``get_scroll_position()`` → ``(0.0, 0.0)``
+- ``get_scroll_percent()`` → ``(0.0, 0.0)`` (or ``0.0`` on
+  ``ScrollBar``, which uses a single-axis API)
+- ``get_thumb_percent()`` → ``(0.0, 0.0)`` (or ``0.0`` on
+  ``ScrollBar``)
+- ``get_expanding()`` → ``(False, False)``
+- ``get_enabled()`` → ``True``
+- ``get_state()`` → ``False``
+- ``get_volume()`` → ``1.0`` (HTMLMediaElement convention: 0.0
+  muted, 1.0 full).
+
+Configured in ``STATE_KEY_DEFAULTS`` / ``STATE_DEFAULTS`` in
+``method_types.py``.
+
+----
+
+Earlier — since ``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.
@@ -63,7 +196,7 @@ Highlights:
 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.
@@ -96,7 +229,7 @@ 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
@@ -106,7 +239,7 @@ Useful for animation/streaming.  ``format`` is one of ``"jpeg"``,
 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``,
@@ -121,7 +254,7 @@ supports both ``add_callback("activated", ...)`` and
 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,
@@ -139,7 +272,7 @@ Robustness improvements
   internal ``ScrollBar`` widgets in its constructor.
 
 Other notable changes
----------------------
+~~~~~~~~~~~~~~~~~~~~~
 
 - ``ColorDialog`` now exposes ``popup``, ``set_position``,
   ``set_modal``, and the ``move`` / ``close`` callbacks (inherited
@@ -160,3 +293,7 @@ Other notable changes
   though the JS side preserves columns on clear).
 - ``FileBrowser`` migrated to the new dict-tree ``TableView`` API
   internally and now subclasses ``Callbacks``.
+- ``FixedLayout`` container added (auto-generated from the JS
+  definition).  Use ``W.FixedLayout()`` and
+  ``layout.add_widget(child, x, y)`` to place children at fixed
+  pixel offsets; ``remove(child)`` works as on any other container.

{pgwidgets_python-0.2.1 → pgwidgets_python-0.3.0}/docs/architecture.rst

@@ -68,7 +68,9 @@ All messages are JSON objects with a ``type`` field.
 - ``{"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`).
+- ``{"type": "binary-chunk", ...}`` -- one chunk of a chunked binary
+  transfer (used in both directions; file uploads, large image
+  payloads, etc.; see :doc:`callbacks`).
 
 Session Model
 -------------

{pgwidgets_python-0.2.1 → pgwidgets_python-0.3.0}/docs/callbacks.rst

@@ -127,9 +127,10 @@ The protocol works as follows:
    metadata (names, sizes, MIME types) but no file data.
 2. The framework fires a **drop-start** callback with the metadata so you
    can show progress UI.
-3. The browser sends ``file-chunk`` messages with base64-encoded data.
+3. The browser sends ``binary-chunk`` JSON headers, each followed by a raw
+   binary WebSocket frame carrying the chunk's bytes (no base64 inflation).
 4. The framework fires **drop-progress** callbacks with transfer status.
-5. When all chunks arrive, the framework reassembles the data and fires the
+5. When all chunks arrive, the framework reassembles the bytes and fires the
    **drop-end** callback with the complete payload.
 
 drop-start
@@ -175,22 +176,28 @@ drop-end
 ~~~~~~~~
 
 Fires when all file data has been received. The handler receives the full
-payload with base64 data URIs:
+payload; each file dict carries:
+
+- ``name`` (str) — original filename
+- ``size`` (int) — byte size
+- ``type`` (str) — MIME type from the browser (e.g. ``"image/png"``)
+- ``encoding`` (str) — wire format of ``data``.  Currently always
+  ``"bytes"`` (``data`` is raw bytes); reserved for ``"base64"`` if a
+  future sender chooses to deliver the file body without binary
+  reassembly.
+- ``data`` (bytes or None) — file contents.  ``None`` on read error;
+  in that case an additional ``error`` field carries the message.
 
 .. code-block:: python
 
-   import base64
-
    def on_drop(payload):
        for f in payload["files"]:
+           if f["encoding"] != "bytes":
+               continue  # currently only "bytes" is emitted
            name = f["name"]
            size = f["size"]
-           mime = f["type"]
-           data_uri = f["data"]  # "data:<mime>;base64,<data>"
-
-           # Decode the file content
-           b64 = data_uri.split(",", 1)[1]
-           content = base64.b64decode(b64)
+           mime = f["type"]      # e.g. "image/png"
+           content = f["data"]   # bytes
            print(f"Received {name}: {len(content)} bytes")
 
    widget.on("drop-end", on_drop)
@@ -210,8 +217,7 @@ Example: File Drop Zone
 
    def on_drop(payload):
        f = payload["files"][0]
-       b64 = f["data"].split(",", 1)[1]
-       text = base64.b64decode(b64).decode("utf-8", errors="replace")
+       text = f["data"].decode("utf-8", errors="replace")
        textarea.set_text(text)
        drop_label.set_text(f"Loaded: {f['name']}")
 

pgwidgets_python-0.3.0/docs/utilities.rst

@@ -0,0 +1,81 @@
+Utilities
+=========
+
+The ``Widget`` base class exposes a few static utility methods that are
+useful when working with local files on the server side.
+
+.. code-block:: python
+
+   from pgwidgets.sync.widget import Widget   # or pgwidgets.async_.widget
+
+to_data_uri
+------------
+
+.. code-block:: python
+
+   Widget.to_data_uri(path)
+
+Read a local file, base64-encode its contents, and return a
+``data:<mime>;base64,…`` string.  The MIME type is guessed from the file
+extension (falls back to ``application/octet-stream``).
+
+The returned string can be passed directly to any widget method that
+expects a URL, such as ``set_image()``, ``set_icon()``, or
+``add_cursor()``.
+
+.. code-block:: python
+
+   # Load a local image into an Image widget
+   img.set_image(Widget.to_data_uri("/path/to/photo.png"))
+
+   # Set a button icon from a local file
+   btn.set_icon(Widget.to_data_uri("/path/to/icon.svg"))
+
+.. note::
+
+   Methods listed in the ``_FILE_ARG_METHODS`` set (currently
+   ``set_icon``, ``set_image``, and ``set_icon_gutter``) already detect
+   local file paths and convert them automatically.  Use
+   ``to_data_uri()`` explicitly when you need the data URI for other
+   purposes or want to cache/reuse it.
+
+
+Buffer
+------
+
+.. code-block:: python
+
+   from pgwidgets import Buffer
+
+   pixels = numpy_array.tobytes()            # 2048 * 2048 * 4 bytes
+   buf = Buffer(pixels,
+                shape=(2048, 2048, 4),
+                dtype="uint8")
+   viewer.load_buffer(buf, [2048, 2048], cache)
+
+A ``Buffer`` wraps raw ``bytes`` with ``shape`` and ``dtype``
+metadata, so a method receiving the buffer on the JavaScript side
+gets a properly-sized typed array (``Uint8Array``, ``Float32Array``,
+…) instead of a raw ``ArrayBuffer``.  Use it for image pixel data,
+scientific arrays, vertex buffers — anything where the receiver
+needs to know how to interpret the bytes without a hand-rolled
+convention per method.
+
+A ``Buffer`` always ships via the chunked binary transport
+(``binary-call-chunked`` + ``binary-chunk`` messages), so multi-
+megabyte payloads stream in 512 KiB chunks and don't block other
+WebSocket traffic.  ``shape`` and ``dtype`` ride on the announce
+header — see :doc:`architecture`.
+
+Supported dtypes:
+
+- ``"uint8"`` / ``"uint16"`` / ``"uint32"``
+- ``"int8"`` / ``"int16"`` / ``"int32"``
+- ``"float32"`` / ``"float64"``
+
+Methods that don't opt into ``Buffer`` keep receiving plain
+``bytes`` — :class:`Buffer` is purely additive.  Construction
+validates that the byte length equals
+``prod(shape) * dtype.itemsize``; pass ``shape=(len(data),)`` and
+``dtype="uint8"`` if you just want a flat byte buffer with a
+known length.

{pgwidgets_python-0.2.1 → pgwidgets_python-0.3.0}/docs/widgets.rst

@@ -140,6 +140,17 @@ Grid layout.
   ``append_column(widgets)``, ``delete_column(index)``
 - **Callbacks:** ``child-added``, ``child-removed``
 
+FixedLayout
+~~~~~~~~~~~
+
+Absolute-positioning container.  Each child is placed at a fixed
+``(x, y)`` pixel offset within the container and renders at its
+natural size unless ``resize()`` has been called on it.
+
+- **Options:** *(none)*
+- **Methods:** ``add_widget(child, x, y)``
+- **Callbacks:** ``child-added``, ``child-removed``
+
 Splitter
 ~~~~~~~~
 
@@ -415,24 +426,58 @@ TextSource
 
 Source code editor with line numbers, syntax tags, and gutter icons.
 
+Positions in the buffer are expressed as ``TextBufferRef`` instances —
+live references that track edits.  ``create_ref(offset, gravity)`` is
+the only place a caller deals in raw integer offsets; all other
+position-taking and position-returning methods on the public API use
+refs.
+
+.. note::
+
+   Refs are JS-side live objects.  When using ``TextSource`` over the
+   remote interface (pgwidgets-python proper), refs cannot currently
+   round-trip across the wire — a ref-handle protocol is planned for
+   a future release.  In the meantime, the ref-based API is fully
+   usable from JS-direct and pyodide contexts.
+
 - **Args:** ``text``
 - **Options:** ``wrap``, ``line_numbers``, ``icon_gutter``, ``editable``,
   ``font_family``, ``font_size``
 - **Methods:** ``set_text(text)``, ``get_text()``, ``get_length()``,
-  ``insert_text(offset, text, tags)``, ``delete_range(start, end)``,
+  ``get_text_range(start_ref, end_ref)``,
+  ``insert_text(ref, text, tags)``, ``delete_range(start_ref, end_ref)``,
   ``clear()``, ``set_editable(tf)``, ``set_wrap(mode)``,
   ``set_line_numbers(tf)``, ``set_icon_gutter(tf)``,
-  ``set_icon(line, icon_url)``, ``get_cursor()``, ``set_cursor(offset)``,
-  ``get_selection()``, ``set_selection(start, end)``,
+  ``set_icon(ref, icon_url)``, ``get_cursor()``, ``set_cursor(ref)``,
+  ``get_selection_range()``, ``set_selection_range(start_ref, end_ref)``,
   ``create_tag(name, attrs)``, ``remove_tag_def(name)``,
-  ``apply_tag(name, start, end)``, ``remove_tag(name, start, end)``,
-  ``get_tags_at(offset)``, ``create_ref(offset, gravity)``,
-  ``remove_ref(ref)``, ``undo()``, ``redo()``, ``can_undo()``,
-  ``can_redo()``, ``find(query, opts)``, ``find_all(query, opts)``,
-  ``replace(query, replacement, opts)``, ``scroll_to(ref_or_offset)``,
+  ``has_tag(name)``,
+  ``apply_tag(name, start_ref, end_ref)``,
+  ``remove_tag(name, start_ref, end_ref)``,
+  ``get_tags_at(ref)``, ``get_tags_range(start_ref, end_ref)``,
+  ``create_ref(offset, gravity)``, ``remove_ref(ref)``,
+  ``create_named_ref(name, offset, gravity)``,
+  ``get_named_ref(name)``, ``remove_named_ref(name)``,
+  ``get_ref_start()``, ``get_ref_end()``, ``get_ref_bounds()``,
+  ``get_ref_line_start(lineno)``, ``get_ref_line_end(lineno)``,
+  ``undo()``, ``redo()``, ``can_undo()``, ``can_redo()``,
+  ``find(query, opts)``, ``find_all(query, opts)``,
+  ``replace(query, replacement, opts)``, ``scroll_to_ref(ref)``,
   ``scroll_to_cursor()``
-- **Callbacks:** ``changed``, ``cursor_moved``, ``line_clicked``,
-  ``icon_clicked``
+- **Callbacks:** ``changed``, ``cursor_moved`` (fires with a fresh
+  ref), ``line_clicked``, ``icon_clicked`` (fires with
+  ``(line, ref)``)
+
+A ``TextBufferRef`` itself supports the following methods:
+
+- **Inspection:** ``get_offset()``, ``get_gravity()``, ``is_valid()``,
+  ``get_line()``, ``get_line_column()``
+- **Absolute position:** ``set_offset(offset)``, ``set_line(lineno)``,
+  ``to_ref(other)``, ``copy()``
+- **Relative movement:** ``to_line_start()``, ``to_line_end()``,
+  ``to_next_line()``, ``to_prev_line()``, ``to_next_char()``,
+  ``to_prev_char()`` (movement methods clamp at buffer boundaries
+  and are no-ops past them; mutating an invalidated ref raises)
 
 Selectors
 ---------
@@ -551,6 +596,12 @@ are pushed per second.  ``format`` is one of ``'jpeg'``, ``'png'``,
 The latest frame is also stored in widget state so it is replayed
 on reconnect.
 
+Payloads larger than ~1 MiB automatically use the *chunked* binary
+transport (``binary-call-chunked`` + per-chunk ``binary-chunk``
+messages) so the WebSocket can interleave control traffic while a
+large frame streams.  No API change for callers — pass ``bytes``
+and the framework picks the right transport.
+
 Canvas
 ~~~~~~
 

pgwidgets_python-0.3.0/examples/flask-multi-process/README.md

@@ -0,0 +1,72 @@
+# Flask multi-process pgwidgets demo
+
+One pgwidgets `Application` per visitor, each in a fresh OS process
+with its own WebSocket port.
+
+- **`server.py`** — Flask front-end.  Each request to `/` spawns a
+  child process running a fresh `Application`, waits for the child
+  to report its WebSocket port through a `multiprocessing.Queue`,
+  then returns an HTML page whose `RemoteInterface` connects back
+  to it.
+- **`user_app.py`** — The per-visitor `Application` definition.
+  The child itself binds an ephemeral TCP socket, hands it directly
+  to `Application(ws_sock=...)` (so the port is held continuously —
+  no race with another process), and reports the resulting port
+  back through the queue.  Edit the body of `setup(session)` to
+  build your UI.  Can also be run standalone (`python user_app.py`)
+  for quick UI debugging without Flask in the loop; the port is
+  auto-allocated and logged.
+
+## Run
+
+```
+pip install Flask pgwidgets-python pgwidgets-js
+python server.py
+# browse to http://localhost:5000/
+```
+
+Every browser tab triggers a brand-new process.  When the tab is
+closed (or the browser navigates away), the child waits a grace
+period — `IDLE_GRACE_SECONDS` in `user_app.py`, default 5 minutes —
+to absorb page refreshes, brief network drops, and the user
+closing/reopening a laptop, then exits.  Reconnecting within the
+grace window cancels the pending shutdown.
+
+### Listening on other interfaces
+
+By default Flask and each per-visitor WebSocket bind to
+``127.0.0.1`` (loopback only).  To accept connections from other
+machines:
+
+```
+python server.py --host 0.0.0.0 --port 8080
+```
+
+The bind interface and the WebSocket URL are decoupled — the
+browser is given a ``ws://`` URL derived from the same hostname it
+used to reach Flask, so the same server can be reached via
+``localhost``, by IP address, or by DNS name with no further
+configuration.
+
+## What the browser loads
+
+Each HTML response embeds the per-visitor WebSocket URL.  The
+pgwidgets-js bundle (`Widgets.js`, `Widgets.css`, the `modules/`
+subtree, icons) is served by Flask itself, from the pip-installed
+`pgwidgets-js` Python package — `pgwidgets_js.get_static_path()`
+returns the directory and a `/pgwidgets-js/<path>` route in
+`server.py` exposes it.  No CDN, no network dependency at runtime,
+and the version on the wire always matches the one in your venv.
+
+To point at an in-progress working copy of pgwidgets-js instead of
+the installed package, either ``pip install -e .`` from the
+pgwidgets-js source tree (so `get_static_path()` resolves to the
+working copy), or replace `PGWIDGETS_JS_ROOT` in `server.py` with
+a hard path to that tree's `static/` directory.
+
+## Caveats
+
+- **Flask debug mode is off.** The reloader spawns a second
+  process, which combined with `multiprocessing` can produce
+  surprising behavior on Windows / macOS.  Restart `server.py` by
+  hand after edits.