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

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

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

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

@@ -1,6 +1,76 @@
 What's New
 ==========
 
+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``
 ---------------------------------
 

{pgwidgets_python-0.2.3 → 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.3 → 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.3 → pgwidgets_python-0.3.0}/docs/widgets.rst

@@ -596,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.

pgwidgets_python-0.3.0/examples/flask-multi-process/server.py

@@ -0,0 +1,203 @@
+"""Flask + pgwidgets-python multi-process demo.
+
+Each visitor to ``/`` is served a fresh pgwidgets Application
+running in its own OS process with its own WebSocket port — so
+sessions are fully isolated, and a slow handler in one session
+can't block another.
+
+Architecture::
+
+    browser   ┌─────────────────────┐    HTTP /          ┌─────────────┐
+       ──────▶│  Flask (port 5000)  │ ─────────────────▶│   user_app  │
+              │  picks ws_port      │    spawn Process   │   process 1 │
+              │  spawns child       │  ◀───────────── ws on 35211 ─────┘
+              │  returns HTML       │                    ┌─────────────┐
+              └─────────────────────┘                    │   user_app  │
+                                                         │   process 2 │
+              (one child per request)               ws on 41922 ────────┘
+
+Run::
+
+    pip install Flask pgwidgets-python
+    python server.py
+    # browse to http://localhost:5000/
+
+Each browser tab triggers a fresh per-visitor process.
+"""
+
+import argparse
+import logging
+import multiprocessing
+import queue as _queue_mod
+import sys
+from pathlib import Path
+
+import pgwidgets_js
+from flask import (Flask, render_template_string, request,
+                   send_from_directory)
+
+# Make the sibling user_app.py importable regardless of the
+# directory ``server.py`` is launched from.  multiprocessing.spawn
+# (the macOS / Windows default) re-imports the target's module in
+# the child process, so the path must already be set up before
+# Process.start() is called.
+sys.path.insert(0, str(Path(__file__).parent))
+
+from user_app import build_app   # noqa: E402  (import after sys.path tweak)
+
+# Directory containing the bundled pgwidgets-js static assets
+# (Widgets.js, Widgets.css, modules/, icons/, …).  Served from
+# Flask so the page does not depend on a CDN being reachable.
+PGWIDGETS_JS_ROOT = pgwidgets_js.get_static_path()
+
+
+# -- Flask boilerplate -----------------------------------------------
+
+app = Flask(__name__)
+log = logging.getLogger("flask-demo.server")
+
+# Bind interface for both Flask and the per-visitor WebSocket
+# children.  Set by main() from --host; module-level default so
+# ``flask run server`` / WSGI runners still work without CLI args.
+_BIND_HOST = "127.0.0.1"
+
+# Loaded HTML template — embeds the per-visitor WebSocket URL.
+# pgwidgets-js is served from the local pip-installed package via
+# the /pgwidgets-js/<path> route below, so the page doesn't depend
+# on network access to a CDN and always matches whatever version
+# of pgwidgets-js is pinned in your environment.
+HTML_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>pgwidgets demo</title>
+  <link rel="stylesheet" href="/pgwidgets-js/Widgets.css">
+  <script type="importmap">
+    {"imports": {"pgwidgets": "/pgwidgets-js/Widgets.js"}}
+  </script>
+  <style>body { margin: 0; }</style>
+</head>
+<body>
+  <script type="module">
+    import { Widgets } from "pgwidgets";
+    new Widgets.RemoteInterface(Widgets, {
+        url: "ws://{{ ws_host }}:{{ ws_port }}",
+    });
+  </script>
+</body>
+</html>
+"""
+
+
+# Keep references to spawned processes so they aren't garbage-
+# collected (Process.__del__ doesn't kill the child, but we still
+# want a tidy registry for shutdown).  Production code should also
+# reap idle children based on whether their pgwidgets Application
+# has any live connections.
+_children = []
+
+
+@app.route("/")
+def index():
+    """Spawn a fresh per-visitor Application and return the HTML.
+
+    Port allocation happens inside the child: it binds an ephemeral
+    TCP socket, holds it, and reports the port back through a
+    ``Queue``.  The bound socket is then handed straight to
+    ``Application(ws_sock=…)``, so the port is never released
+    between "discover" and "use" — no TOCTOU race with any other
+    process.
+
+    The WebSocket *bind* interface is whatever ``--host`` was set
+    to (default 127.0.0.1).  The WebSocket *URL* given to the
+    browser is derived from ``request.host`` — i.e. whichever
+    hostname/IP the browser used to reach Flask — so the same
+    server can be reached as ``localhost``, by IP, or by DNS name
+    without configuration.
+    """
+    comm_queue = multiprocessing.Queue()
+    child = multiprocessing.Process(
+        target=build_app, args=(comm_queue, _BIND_HOST), daemon=True,
+        name="pgwidgets-app",
+    )
+    child.start()
+    _children.append(child)
+
+    try:
+        ws_port = comm_queue.get(timeout=5.0)
+    except _queue_mod.Empty:
+        log.error("child pid=%d did not report its port within timeout",
+                  child.pid)
+        return ("pgwidgets app process failed to start.  "
+                "Check the server log.", 503)
+
+    # Extract hostname portion of the Host header (e.g.
+    # "example.com:5000" -> "example.com").  rsplit handles literal
+    # IPv4 + port; IPv6 hosts (``[::1]:5000``) aren't preserved here
+    # — extend with urllib.parse.urlsplit if you need them.
+    ws_host = request.host.rsplit(":", 1)[0] if ":" in request.host \
+        else request.host
+
+    log.info("child pid=%d bound on %s:%d, browser will connect to %s:%d",
+             child.pid, _BIND_HOST, ws_port, ws_host, ws_port)
+    return render_template_string(HTML_TEMPLATE,
+                                  ws_host=ws_host, ws_port=ws_port)
+
+
+@app.route("/pgwidgets-js/<path:filename>")
+def pgwidgets_js_static(filename):
+    """Serve pgwidgets-js's bundled static assets from the pip-
+    installed copy.  The Widgets.js entry point uses relative imports
+    (``./modules/Widget.js`` etc.), so the entire subtree has to be
+    reachable under one URL prefix — ``send_from_directory`` handles
+    that correctly out of the box."""
+    return send_from_directory(PGWIDGETS_JS_ROOT, filename)
+
+
+@app.route("/favicon.ico")
+def favicon():
+    """Return an empty 204 so the browser stops 404-ing on every page."""
+    return ("", 204)
+
+
+def _shutdown_children():
+    """Best-effort cleanup of spawned children on Flask exit."""
+    for p in _children:
+        if p.is_alive():
+            p.terminate()
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="Flask + pgwidgets-python multi-process demo.")
+    parser.add_argument(
+        "--host", default="127.0.0.1",
+        help="Interface to bind both Flask and the per-visitor "
+             "WebSocket children on.  Use 0.0.0.0 to accept "
+             "connections from other machines, or a specific NIC IP "
+             "to restrict to one interface.  (default: 127.0.0.1)")
+    parser.add_argument(
+        "--port", type=int, default=5000,
+        help="HTTP port for Flask.  WebSocket ports are allocated "
+             "ephemerally per visitor.  (default: 5000)")
+    args = parser.parse_args()
+
+    _BIND_HOST = args.host
+
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(levelname)s %(name)s: %(message)s",
+    )
+    log.info("Flask serving on http://%s:%d  (WebSocket bind: %s)",
+             args.host, args.port, args.host)
+
+    # ``debug=False`` is important: Flask's reloader spawns two
+    # processes (parent + reloader child) and that confuses
+    # multiprocessing on some platforms.  For interactive editing,
+    # restart the script manually.
+    try:
+        app.run(host=args.host, port=args.port, debug=False)
+    finally:
+        _shutdown_children()