pgwidgets-python 0.2.3__py3-none-any.whl → 0.3.0__py3-none-any.whl

pgwidgets/__init__.py

@@ -24,6 +24,8 @@ Version:
 
 from importlib.metadata import version as _pkg_version, PackageNotFoundError
 
+from pgwidgets.buffer import Buffer, is_buffer  # noqa: F401
+
 try:
     __version__ = _pkg_version("pgwidgets")
 except PackageNotFoundError:

pgwidgets/async_/application.py

@@ -30,7 +30,7 @@ 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,
-    BINARY_STATE_KEYS,
+    BINARY_STATE_KEYS, _send_binary_auto,
 )
 from pgwidgets.async_.widget import Widget, build_all_widget_classes
 
@@ -125,6 +125,9 @@ class Session:
 
         self._widget_classes = app._widget_classes
         self._transfers = {}     # transfer_id -> transfer state dict
+        # FIFO of binary-chunk JSON headers (encoding="binary") still
+        # awaiting their paired raw binary frame.
+        self._pending_binary_headers = []
         self._callback_source_ws = None  # ws that sent current callback
 
         self._reconstructing = False  # suppress callbacks during reconstruction
@@ -194,6 +197,19 @@ class Session:
     # -- Message handling --
 
     def _handle_message(self, data):
+        # Raw binary frames pair with the head of the binary-chunk
+        # JSON header FIFO (encoding="binary").  See the sync
+        # equivalent for the rationale.
+        if isinstance(data, (bytes, bytearray, memoryview)):
+            queue = self._pending_binary_headers
+            if not queue:
+                self._logger.warning(
+                    "Session %s: unexpected binary frame with no "
+                    "queued header (ignored).", self.id)
+                return
+            header = queue.pop(0)
+            self._handle_binary_chunk(header, bytes(data))
+            return
         msg = json.loads(data)
         if isinstance(msg, list):
             for m in msg:
@@ -216,8 +232,18 @@ class Session:
         elif msg_type == "viewport":
             self._screen_size = (msg.get("width", 0), msg.get("height", 0))
 
-        elif msg_type == "file-chunk":
-            self._handle_file_chunk(msg)
+        elif msg_type == "binary-chunk":
+            encoding = msg.get("encoding", "binary")
+            if encoding == "binary":
+                self._pending_binary_headers.append(msg)
+            elif encoding == "base64":
+                import base64 as _b64
+                payload = _b64.b64decode(msg.get("data") or "")
+                self._handle_binary_chunk(msg, payload)
+            else:
+                self._logger.warning(
+                    "Session %s: unknown binary-chunk encoding %r "
+                    "(ignored).", self.id, encoding)
 
         elif msg_type == "callback":
             # If the payload has a transfer_id, stash the metadata —
@@ -244,25 +270,40 @@ class Session:
             self._dispatch_callback(
                 msg["wid"], msg["action"], *msg.get("args", []))
 
-    def _handle_file_chunk(self, msg):
-        """Handle a file-chunk message: buffer data and fire callbacks."""
-        tid = msg["transfer_id"]
+    def _handle_binary_chunk(self, header, data):
+        """Buffer one chunk of an in-flight transfer.
+
+        ``header`` is the parsed binary-chunk JSON; ``data`` is the
+        chunk's raw bytes (paired binary frame, or decoded inline
+        base64).  See the sync equivalent for the full description.
+        """
+        tid = header["transfer_id"]
         transfer = self._transfers.get(tid)
         if transfer is None:
             return
 
-        fi = msg["file_index"]
-        fc = msg["file_count"]
+        fi = header.get("file_index", 0)
+        fc = header.get("file_count", 1)
+        ci = header["chunk_index"]
+        nc = header["num_chunks"]
         if fi not in transfer["file_data"]:
-            transfer["file_data"][fi] = []
-            transfer["num_chunks"][fi] = msg["num_chunks"]
-        transfer["file_data"][fi].append(msg["data"])
+            transfer["file_data"][fi] = [None] * nc
+            transfer["num_chunks"][fi] = nc
+        slot = transfer["file_data"][fi]
+        if 0 <= ci < len(slot):
+            slot[ci] = data
+        else:
+            self._logger.warning(
+                "Session %s: chunk_index %d out of range for "
+                "transfer_id %s (num_chunks=%d).",
+                self.id, ci, tid, nc)
+            return
 
         # Check if all files have received all their chunks.
         all_complete = (
             len(transfer["num_chunks"]) == fc
             and all(
-                len(transfer["file_data"][i]) >= transfer["num_chunks"][i]
+                None not in transfer["file_data"][i]
                 for i in range(fc)
             )
         )
@@ -274,16 +315,17 @@ class Session:
         for i, fmeta in enumerate(files_meta):
             fsize = fmeta.get("size", 0)
             total_bytes += fsize
-            nc = transfer["num_chunks"].get(i)
-            if nc:
-                received = len(transfer["file_data"].get(i, []))
-                transferred_bytes += fsize * received // nc
+            n = transfer["num_chunks"].get(i)
+            if n:
+                slots = transfer["file_data"].get(i, [])
+                received = sum(1 for s in slots if s is not None)
+                transferred_bytes += fsize * received // n
 
         progress_info = {
             "transfer_id": tid,
             "file_index": fi,
-            "chunk_index": msg["chunk_index"],
-            "num_chunks": msg["num_chunks"],
+            "chunk_index": ci,
+            "num_chunks": nc,
             "transferred_bytes": transferred_bytes,
             "total_bytes": total_bytes,
             "complete": all_complete,
@@ -299,8 +341,8 @@ class Session:
             # Reassemble file data and fire the original callback.
             payload = transfer["payload"]
             for i, file_meta in enumerate(payload["files"]):
-                file_meta["data"] = "".join(
-                    transfer["file_data"].get(i, []))
+                slots = transfer["file_data"].get(i, [])
+                file_meta["data"] = b"".join(slots)
             del self._transfers[tid]
             self._dispatch_callback(
                 transfer["wid"], action, payload)
@@ -662,6 +704,69 @@ class Session:
             task = asyncio.ensure_future(_pair(ws))
             task.add_done_callback(_drain_send_exception)
 
+    def _send_binary_chunked(self, wid, method, args, data,
+                             chunk_size=512 * 1024,
+                             shape=None, dtype=None):
+        """Fire-and-forget chunked binary call (async variant).
+
+        See the sync :meth:`Session._send_binary_chunked` for the full
+        description, including the optional ``shape``/``dtype`` that
+        promote the receiver's payload from a raw ``ArrayBuffer`` to
+        a typed array.  Each connection's chunks are scheduled as a
+        single coroutine so they ship atomically.
+        """
+        if not self._connections:
+            return
+        if not isinstance(data, (bytes, bytearray, memoryview)):
+            raise TypeError(
+                "_send_binary_chunked: data must be bytes-like, got "
+                + type(data).__name__)
+        data = bytes(data)
+        n = len(data)
+        if chunk_size <= 0:
+            raise ValueError("chunk_size must be positive")
+        num_chunks = max(1, (n + chunk_size - 1) // chunk_size)
+        msg_id = self._next_id
+        self._next_id += 1
+        transfer_id = self._next_id
+        self._next_id += 1
+        announce_obj = {
+            "type": "binary-call-chunked",
+            "id": msg_id,
+            "wid": wid,
+            "method": method,
+            "args": list(args),
+            "transfer_id": transfer_id,
+            "num_chunks": num_chunks,
+        }
+        if shape is not None:
+            announce_obj["shape"] = list(shape)
+        if dtype is not None:
+            announce_obj["dtype"] = dtype
+        announce = json.dumps(announce_obj, cls=JsonEncoder)
+        pairs = []
+        for ci in range(num_chunks):
+            start = ci * chunk_size
+            end = min(start + chunk_size, n)
+            header = json.dumps({
+                "type": "binary-chunk",
+                "transfer_id": transfer_id,
+                "chunk_index": ci,
+                "num_chunks": num_chunks,
+                "encoding": "binary",
+            }, cls=JsonEncoder)
+            pairs.append((header, data[start:end]))
+
+        async def _send_all(ws):
+            await ws.send(announce)
+            for hdr, payload in pairs:
+                await ws.send(hdr)
+                await ws.send(payload)
+
+        for ws in self._connections:
+            task = asyncio.ensure_future(_send_all(ws))
+            task.add_done_callback(_drain_send_exception)
+
     async def _listen(self, wid, action, handler):
         """Register a callback listener.
 
@@ -1079,12 +1184,13 @@ class Session:
                 continue
 
             # Binary-payload state (e.g. set_binary_image) replays via
-            # _send_binary so the bytes go in a raw frame, not embedded
-            # as base64 in JSON.
+            # _send_binary / _send_binary_chunked.  Large payloads
+            # switch to chunked transport automatically.
             if key in BINARY_STATE_KEYS:
                 method_name = BINARY_STATE_KEYS[key]
                 fmt, data = value
-                self._send_binary(widget._wid, method_name, [fmt], data)
+                _send_binary_auto(self, widget._wid, method_name,
+                                  [fmt], data)
                 continue
 
             if key in self._STATE_KEY_TO_SETTER:
@@ -1289,13 +1395,20 @@ class Application:
 
     def __init__(self, ws_port=9500, http_port=9501, host="127.0.0.1",
                  http_server=True, concurrency_handling="per_session",
-                 max_sessions=1, logger=None):
+                 max_sessions=1, logger=None, ws_sock=None):
         if concurrency_handling not in _CONCURRENCY_MODES:
             raise ValueError(
                 f"concurrency_handling must be one of "
                 f"{_CONCURRENCY_MODES!r}, got {concurrency_handling!r}")
         self._host = host
-        self._ws_port = ws_port
+        # ws_sock, if provided, is a bound TCP socket the WebSocket
+        # server should adopt directly — see the sync :class:`Application`
+        # for the rationale (TOCTOU-free port allocation).
+        self._ws_sock = ws_sock
+        if ws_sock is not None:
+            self._ws_port = ws_sock.getsockname()[1]
+        else:
+            self._ws_port = ws_port
         self._http_port = http_port
         self._use_http_server = http_server
         self._concurrency = concurrency_handling
@@ -1652,8 +1765,12 @@ class Application:
         self._logger.info(
             f"WebSocket on ws://{self._host}:{self._ws_port}")
 
-        self._ws_server = await websockets.serve(
-            self._ws_handler, self._host, self._ws_port)
+        if self._ws_sock is not None:
+            self._ws_server = await websockets.serve(
+                self._ws_handler, sock=self._ws_sock)
+        else:
+            self._ws_server = await websockets.serve(
+                self._ws_handler, self._host, self._ws_port)
 
     async def close(self):
         """Close all sessions and shut down the application.

pgwidgets/buffer.py

@@ -0,0 +1,125 @@
+"""Typed binary buffer descriptors for the remote interface.
+
+When a method on the browser side expects a typed n-dimensional array
+(image pixels, scientific data, vertex buffers, …) the Python side can
+wrap the raw bytes in a :class:`Buffer` so the receiver gets a typed
+view with shape/dtype information without each method re-implementing
+its own ad-hoc convention.
+
+Example::
+
+    from pgwidgets import Buffer
+
+    pixels = bytes(...)            # 2048 * 2048 * 4 bytes
+    buf = Buffer(pixels,
+                 shape=(2048, 2048, 4),
+                 dtype="uint8")
+    viewer.load_buffer(buf, [2048, 2048], cache)
+
+A widget method's binding can recognize :class:`Buffer` args and ship
+them via the chunked binary transport, attaching ``shape`` and
+``dtype`` to the chunk announce so the JavaScript receiver builds the
+correct typed array (``Uint8Array``, ``Float32Array``, …) before
+dispatching to the method.
+"""
+
+from typing import Sequence, Union
+
+
+# Subset of NumPy / DLPack dtype names mapped to the JavaScript
+# TypedArray constructor on the receiving side.
+_DTYPES = frozenset({
+    "uint8", "uint16", "uint32",
+    "int8", "int16", "int32",
+    "float32", "float64",
+})
+
+_DTYPE_BYTES = {
+    "uint8":   1,
+    "int8":    1,
+    "uint16":  2,
+    "int16":   2,
+    "uint32":  4,
+    "int32":   4,
+    "float32": 4,
+    "float64": 8,
+}
+
+
+class Buffer:
+    """Raw bytes plus shape + dtype, addressable as a typed array.
+
+    Parameters
+    ----------
+    data : bytes-like
+        ``bytes``, ``bytearray``, ``memoryview``, or anything that
+        exposes ``__bytes__`` / the buffer protocol.  Converted to
+        ``bytes`` at construction time.
+    shape : tuple of int
+        Logical dimensions of the array, e.g. ``(height, width, 4)``
+        for an RGBA8 image.  Each entry must be a positive integer.
+    dtype : str
+        One of ``"uint8"``, ``"uint16"``, ``"uint32"``, ``"int8"``,
+        ``"int16"``, ``"int32"``, ``"float32"``, ``"float64"``.
+        Default ``"uint8"``.
+
+    Raises
+    ------
+    TypeError
+        If ``data`` is not bytes-like.
+    ValueError
+        If ``dtype`` is unsupported, ``shape`` contains non-positive
+        entries, or the byte length disagrees with
+        ``prod(shape) * itemsize`` (rounded up for non-evenly divisible
+        cases).
+    """
+
+    __slots__ = ("data", "shape", "dtype")
+
+    def __init__(self,
+                 data: Union[bytes, bytearray, memoryview],
+                 shape: Sequence[int],
+                 dtype: str = "uint8") -> None:
+        if dtype not in _DTYPES:
+            raise ValueError(
+                f"Buffer: unsupported dtype {dtype!r}; "
+                f"supported: {sorted(_DTYPES)}")
+        try:
+            data = bytes(data)
+        except TypeError as e:
+            raise TypeError(
+                f"Buffer: data must be bytes-like, got "
+                f"{type(data).__name__}") from e
+        shape_tuple = tuple(int(d) for d in shape)
+        if not shape_tuple or any(d <= 0 for d in shape_tuple):
+            raise ValueError(
+                f"Buffer: shape must be a non-empty tuple of "
+                f"positive ints, got {shape!r}")
+        itemsize = _DTYPE_BYTES[dtype]
+        expected = itemsize
+        for d in shape_tuple:
+            expected *= d
+        if len(data) != expected:
+            raise ValueError(
+                f"Buffer: data length {len(data)} bytes does not "
+                f"match shape {shape_tuple} * dtype {dtype} "
+                f"(expected {expected} bytes)")
+        self.data = data
+        self.shape = shape_tuple
+        self.dtype = dtype
+
+    def __len__(self) -> int:
+        return len(self.data)
+
+    def __repr__(self) -> str:
+        return (f"Buffer(<{len(self.data)} bytes>, "
+                f"shape={self.shape}, dtype={self.dtype!r})")
+
+
+def is_buffer(obj) -> bool:
+    """Return True if *obj* is a :class:`Buffer` instance.
+
+    Convenience for code that branches on whether an argument carries
+    binary-payload metadata.
+    """
+    return isinstance(obj, Buffer)

pgwidgets/method_types.py

@@ -338,6 +338,34 @@ def _menuaction_get_state(self):
     """Alias for MenuAction.get_checked — keeps a single state key."""
     return self.get_checked()
 
+# Above this size (bytes), set_binary_image switches from the single-
+# frame _send_binary transport to the chunked _send_binary_chunked
+# transport.  Keeps small frames cheap and lets multi-megabyte frames
+# yield to other WebSocket traffic between chunks.
+_BINARY_CHUNK_THRESHOLD = 1 * 1024 * 1024  # 1 MiB
+
+
+def _send_binary_auto(session, wid, method, args, data):
+    """Pick single-frame or chunked transport based on payload size.
+
+    If ``data`` is a :class:`pgwidgets.Buffer`, its bytes ship via the
+    chunked transport (regardless of size) with ``shape`` and
+    ``dtype`` attached to the announce so the JS receiver constructs
+    a typed array.  Plain bytes-like input falls back to the size
+    heuristic (chunked above ~1 MiB, single-frame below).
+    """
+    from pgwidgets.buffer import Buffer  # local import to avoid cycle
+    if isinstance(data, Buffer):
+        session._send_binary_chunked(
+            wid, method, args, data.data,
+            shape=data.shape, dtype=data.dtype)
+        return
+    if len(data) > _BINARY_CHUNK_THRESHOLD:
+        session._send_binary_chunked(wid, method, args, data)
+    else:
+        session._send_binary(wid, method, args, data)
+
+
 def _image_set_binary_image(self, data, format="jpeg"):
     """Set the image from raw bytes via a WebSocket binary frame.
 
@@ -358,6 +386,10 @@ def _image_set_binary_image(self, data, format="jpeg"):
     that reconstruction after a browser reconnect re-sends the most
     recently set image.  Earlier set_image (URL-based) state is
     cleared since the two methods are mutually exclusive.
+
+    Large payloads (above ~1 MiB) automatically use the chunked
+    binary transport so the WebSocket can interleave other messages
+    while the image streams.
     """
     if not isinstance(data, (bytes, bytearray, memoryview)):
         raise TypeError(
@@ -365,8 +397,8 @@ def _image_set_binary_image(self, data, format="jpeg"):
     data = bytes(data)
     self._state.pop("image", None)
     self._state["binary_image"] = (format, data)
-    self._session._send_binary(
-        self._wid, "set_binary_image", [format], data)
+    _send_binary_auto(self._session, self._wid,
+                      "set_binary_image", [format], data)
 
 # State keys whose value is a (format, bytes) tuple that must be
 # replayed via _send_binary instead of _call during reconstruction.

pgwidgets/sync/application.py

@@ -33,7 +33,7 @@ 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,
-    BINARY_STATE_KEYS,
+    BINARY_STATE_KEYS, _send_binary_auto,
 )
 
 _CONCURRENCY_MODES = ("serialized", "per_session", "concurrent")
@@ -169,6 +169,11 @@ class Session:
 
         self._widget_classes = app._widget_classes
         self._transfers = {}     # transfer_id -> transfer state dict
+        # FIFO of binary-chunk JSON headers (encoding="binary") still
+        # awaiting their paired raw binary frame.  Each connection's
+        # send order on the JS side is single-threaded, so a simple
+        # FIFO suffices on the receive side too.
+        self._pending_binary_headers = []
         self._callback_source_ws = None  # ws that sent current callback
 
         self._reconstructing = False  # suppress callbacks during reconstruction
@@ -273,6 +278,20 @@ class Session:
     # -- Message handling --
 
     def _handle_message(self, data):
+        # Raw binary frames are chunk payloads — pair with the head of
+        # the pending-binary FIFO (a list of binary-chunk JSON headers
+        # whose encoding == "binary").  This is symmetric with the
+        # JS-side intake.
+        if isinstance(data, (bytes, bytearray, memoryview)):
+            queue = self._pending_binary_headers
+            if not queue:
+                self._logger.warning(
+                    "Session %s: unexpected binary frame with no "
+                    "queued header (ignored).", self.id)
+                return
+            header = queue.pop(0)
+            self._handle_binary_chunk(header, bytes(data))
+            return
         msg = json.loads(data)
         if isinstance(msg, list):
             for m in msg:
@@ -293,8 +312,20 @@ class Session:
         elif msg_type == "viewport":
             self._screen_size = (msg.get("width", 0), msg.get("height", 0))
 
-        elif msg_type == "file-chunk":
-            self._handle_file_chunk(msg)
+        elif msg_type == "binary-chunk":
+            # Either reserves the next binary frame (encoding="binary")
+            # or carries an inline base64 payload (encoding="base64").
+            encoding = msg.get("encoding", "binary")
+            if encoding == "binary":
+                self._pending_binary_headers.append(msg)
+            elif encoding == "base64":
+                import base64 as _b64
+                payload = _b64.b64decode(msg.get("data") or "")
+                self._handle_binary_chunk(msg, payload)
+            else:
+                self._logger.warning(
+                    "Session %s: unknown binary-chunk encoding %r "
+                    "(ignored).", self.id, encoding)
 
         elif msg_type == "callback":
             # If the payload has a transfer_id, stash the metadata —
@@ -321,25 +352,45 @@ class Session:
             self._dispatch_callback(
                 msg["wid"], msg["action"], *msg.get("args", []))
 
-    def _handle_file_chunk(self, msg):
-        """Handle a file-chunk message: buffer data and fire callbacks."""
-        tid = msg["transfer_id"]
+    def _handle_binary_chunk(self, header, data):
+        """Buffer one chunk of an in-flight transfer.
+
+        ``header`` is the parsed binary-chunk JSON; ``data`` is the
+        chunk's raw bytes (either from the paired binary WebSocket
+        frame or decoded from an inline base64 ``data`` field).
+
+        For file-upload transfers (drag-drop, FileDialog), the header
+        also carries ``file_index`` / ``file_count`` so multiple files
+        can be reassembled in parallel.  For other future server-bound
+        chunked transports, those fields can be omitted.
+        """
+        tid = header["transfer_id"]
         transfer = self._transfers.get(tid)
         if transfer is None:
             return
 
-        fi = msg["file_index"]
-        fc = msg["file_count"]
+        fi = header.get("file_index", 0)
+        fc = header.get("file_count", 1)
+        ci = header["chunk_index"]
+        nc = header["num_chunks"]
         if fi not in transfer["file_data"]:
-            transfer["file_data"][fi] = []
-            transfer["num_chunks"][fi] = msg["num_chunks"]
-        transfer["file_data"][fi].append(msg["data"])
+            transfer["file_data"][fi] = [None] * nc
+            transfer["num_chunks"][fi] = nc
+        slot = transfer["file_data"][fi]
+        if 0 <= ci < len(slot):
+            slot[ci] = data
+        else:
+            self._logger.warning(
+                "Session %s: chunk_index %d out of range for "
+                "transfer_id %s (num_chunks=%d).",
+                self.id, ci, tid, nc)
+            return
 
         # Check if all files have received all their chunks.
         all_complete = (
             len(transfer["num_chunks"]) == fc
             and all(
-                len(transfer["file_data"][i]) >= transfer["num_chunks"][i]
+                None not in transfer["file_data"][i]
                 for i in range(fc)
             )
         )
@@ -351,16 +402,17 @@ class Session:
         for i, fmeta in enumerate(files_meta):
             fsize = fmeta.get("size", 0)
             total_bytes += fsize
-            nc = transfer["num_chunks"].get(i)
-            if nc:
-                received = len(transfer["file_data"].get(i, []))
-                transferred_bytes += fsize * received // nc
+            n = transfer["num_chunks"].get(i)
+            if n:
+                slots = transfer["file_data"].get(i, [])
+                received = sum(1 for s in slots if s is not None)
+                transferred_bytes += fsize * received // n
 
         progress_info = {
             "transfer_id": tid,
             "file_index": fi,
-            "chunk_index": msg["chunk_index"],
-            "num_chunks": msg["num_chunks"],
+            "chunk_index": ci,
+            "num_chunks": nc,
             "transferred_bytes": transferred_bytes,
             "total_bytes": total_bytes,
             "complete": all_complete,
@@ -376,8 +428,8 @@ class Session:
             # Reassemble file data and fire the original callback.
             payload = transfer["payload"]
             for i, file_meta in enumerate(payload["files"]):
-                file_meta["data"] = "".join(
-                    transfer["file_data"].get(i, []))
+                slots = transfer["file_data"].get(i, [])
+                file_meta["data"] = b"".join(slots)
             del self._transfers[tid]
             self._dispatch_callback(
                 transfer["wid"], action, payload)
@@ -718,6 +770,91 @@ class Session:
                 continue
             fut.add_done_callback(_drain_send_exception)
 
+    def _send_binary_chunked(self, wid, method, args, data,
+                             chunk_size=512 * 1024,
+                             shape=None, dtype=None):
+        """Fire-and-forget chunked binary call.
+
+        Splits ``data`` (bytes) into ``chunk_size`` chunks and sends
+        them as a ``binary-call-chunked`` announce followed by N
+        (``binary-chunk`` JSON + raw binary frame) pairs.  The JS side
+        reassembles into a single ``ArrayBuffer`` and dispatches as
+        ``widget[method](buffer, *args)``.
+
+        When ``shape`` and ``dtype`` are provided, they are attached to
+        the announce header and the JS receiver constructs a typed
+        array (``Uint8Array``, ``Float32Array``, …) instead of a raw
+        ``ArrayBuffer`` before dispatch.  This is what :class:`Buffer`
+        arguments end up doing.
+
+        All chunks for a single transfer ship atomically on each
+        connection (one coroutine per connection) so they can't
+        interleave with other binary sends from another thread.
+        """
+        if not self._connections:
+            return
+        if not isinstance(data, (bytes, bytearray, memoryview)):
+            raise TypeError(
+                "_send_binary_chunked: data must be bytes-like, got "
+                + type(data).__name__)
+        data = bytes(data)
+        n = len(data)
+        if chunk_size <= 0:
+            raise ValueError("chunk_size must be positive")
+        num_chunks = max(1, (n + chunk_size - 1) // chunk_size)
+        with self._lock:
+            msg_id = self._next_id
+            self._next_id += 1
+            transfer_id = self._next_id
+            self._next_id += 1
+        announce_obj = {
+            "type": "binary-call-chunked",
+            "id": msg_id,
+            "wid": wid,
+            "method": method,
+            "args": list(args),
+            "transfer_id": transfer_id,
+            "num_chunks": num_chunks,
+        }
+        if shape is not None:
+            announce_obj["shape"] = list(shape)
+        if dtype is not None:
+            announce_obj["dtype"] = dtype
+        announce = json.dumps(announce_obj, cls=JsonEncoder)
+        # Pre-build chunk headers + slices so JSON encoding cost is
+        # paid once even if multiple browsers are connected.
+        pairs = []
+        for ci in range(num_chunks):
+            start = ci * chunk_size
+            end = min(start + chunk_size, n)
+            header = json.dumps({
+                "type": "binary-chunk",
+                "transfer_id": transfer_id,
+                "chunk_index": ci,
+                "num_chunks": num_chunks,
+                "encoding": "binary",
+            }, cls=JsonEncoder)
+            pairs.append((header, data[start:end]))
+
+        async def _send_all(ws):
+            await ws.send(announce)
+            for header, payload in pairs:
+                await ws.send(header)
+                await ws.send(payload)
+
+        for ws in self._connections:
+            coro = _send_all(ws)
+            try:
+                fut = asyncio.run_coroutine_threadsafe(coro,
+                                                       self._app._loop)
+            except RuntimeError as e:
+                self._logger.warning(
+                    "Session %s: loop refused chunked-binary coroutine: %r",
+                    self.id, e)
+                coro.close()
+                continue
+            fut.add_done_callback(_drain_send_exception)
+
     def _listen(self, wid, action, handler):
         """Register a callback listener.
 
@@ -1219,12 +1356,14 @@ class Session:
                 continue
 
             # Binary-payload state (e.g. set_binary_image) replays via
-            # _send_binary so the bytes go in a raw frame, not embedded
-            # as base64 in JSON.
+            # _send_binary / _send_binary_chunked so the bytes go in
+            # raw frame(s), not embedded as base64 in JSON.  Large
+            # payloads switch to chunked transport automatically.
             if key in BINARY_STATE_KEYS:
                 method_name = BINARY_STATE_KEYS[key]
                 fmt, data = value
-                self._send_binary(widget._wid, method_name, [fmt], data)
+                _send_binary_auto(self, widget._wid, method_name,
+                                  [fmt], data)
                 continue
 
             if key in self._STATE_KEY_TO_SETTER:
@@ -1466,13 +1605,24 @@ class Application:
 
     def __init__(self, ws_port=9500, http_port=9501, host="127.0.0.1",
                  http_server=True, concurrency_handling="per_session",
-                 max_sessions=1, logger=None):
+                 max_sessions=1, logger=None, ws_sock=None):
         if concurrency_handling not in _CONCURRENCY_MODES:
             raise ValueError(
                 f"concurrency_handling must be one of "
                 f"{_CONCURRENCY_MODES!r}, got {concurrency_handling!r}")
         self._host = host
-        self._ws_port = ws_port
+        # ws_sock, if provided, is a bound TCP socket the WebSocket
+        # server should adopt directly.  This removes the TOCTOU race
+        # that would otherwise exist between "find a free port" and
+        # "bind that port" — the caller binds, hands the socket in,
+        # and we never release the port between the two steps.
+        # ``ws_port`` is read back from the socket so logging /
+        # introspection still report a useful value.
+        self._ws_sock = ws_sock
+        if ws_sock is not None:
+            self._ws_port = ws_sock.getsockname()[1]
+        else:
+            self._ws_port = ws_port
         self._http_port = http_port
         self._use_http_server = http_server
         self._concurrency = concurrency_handling
@@ -1595,9 +1745,14 @@ class Application:
         self._loop.run_until_complete(self._serve_ws())
 
     async def _serve_ws(self):
-        async with websockets.serve(self._ws_handler, self._host,
-                                    self._ws_port):
-            await asyncio.Future()
+        if self._ws_sock is not None:
+            async with websockets.serve(self._ws_handler,
+                                        sock=self._ws_sock):
+                await asyncio.Future()
+        else:
+            async with websockets.serve(self._ws_handler, self._host,
+                                        self._ws_port):
+                await asyncio.Future()
 
     async def _ws_handler(self, ws):
         # Init handshake: send init, receive ack which may contain

{pgwidgets_python-0.2.3.dist-info → pgwidgets_python-0.3.0.dist-info}/METADATA

@@ -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.dist-info → pgwidgets_python-0.3.0.dist-info}/RECORD

@@ -1,20 +1,21 @@
-pgwidgets/__init__.py,sha256=fKKHAt9GxLbficihVyImWsqrnQvdQZQAmeGaRUF8cBE,857
+pgwidgets/__init__.py,sha256=z6QFxTtjwnduH-s0zT8u_GJb0rT7OZsgPawMIlIzfQE,919
 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=S5V6EvJ9DZnSQaiaEhPkAuCtqrlHde5wj16TZd0vHvQ,16327
+pgwidgets/method_types.py,sha256=E_f0CQtDwWKgiPmIPGEftm3OXvntErAY4JZH0C7Dwuo,17699
 pgwidgets/async_/Widgets.py,sha256=vld2xkvusBBEVbhbezaJsjBRRj3L7c17Up0pOVs8PGo,723
 pgwidgets/async_/__init__.py,sha256=rXB-v9XRrYt1imYuYikhkzIyiRqaYhlTpQei2LHaQ18,564
-pgwidgets/async_/application.py,sha256=mab8nRl7dNwnvNx64F0RapIJvJXy4HW_eJ1Bbuhw83w,69612
+pgwidgets/async_/application.py,sha256=xLt7ZF7jgRYKT5-L95sahohT4Omq2TfW7y8V1f6GM9g,74443
 pgwidgets/async_/widget.py,sha256=H27v7AzHNg5obzr2e8UyOyj2lbGfWhEhZUrIDqrZNbg,37612
 pgwidgets/extras/__init__.py,sha256=AXUmFtnn4RSlp6pJX6z55j-m_29VmfzpYIjQvAy7pO0,325
 pgwidgets/extras/file_browser.py,sha256=PWzJltjQZbmsD1ykbbC2xJ6ErEkJj7KafhmVkd9q9Ac,16963
 pgwidgets/sync/Widgets.py,sha256=7SaocMVMzFHhi51pjuEAr47Wez90b_a61kDbiv0jOfM,706
 pgwidgets/sync/__init__.py,sha256=SF5RTAvtu8BbYBWzpiCPipy6DJzNXf6nqk9xdvwxUhQ,542
-pgwidgets/sync/application.py,sha256=a1Xu5VRif9WKHxMWvPN3oyTqjPsrdw54Smp4Vz16ObY,80309
+pgwidgets/sync/application.py,sha256=0xZDEywx7L7vUe1QAs29iufIqqvmSzOLeu9QQIGiSj0,87160
 pgwidgets/sync/widget.py,sha256=tQDkCOkcevDrGnG4LhBf69law82-UB1fF-r08GUZPSE,37913
-pgwidgets_python-0.2.3.dist-info/licenses/LICENSE.md,sha256=LoM3fMTiMnQuHRCJghdjOtjnCrL8soBpu2PFk24Xvyg,1528
-pgwidgets_python-0.2.3.dist-info/METADATA,sha256=e5O9EkVS7VKRrgwxNwtKgLOcs6emH7hpkFqyfJOKAUE,4568
-pgwidgets_python-0.2.3.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-pgwidgets_python-0.2.3.dist-info/top_level.txt,sha256=wwL6fBq0gU-JwzlM6TdduY1qYpu39ysqnnbQT-1bqAs,10
-pgwidgets_python-0.2.3.dist-info/RECORD,,
+pgwidgets_python-0.3.0.dist-info/licenses/LICENSE.md,sha256=LoM3fMTiMnQuHRCJghdjOtjnCrL8soBpu2PFk24Xvyg,1528
+pgwidgets_python-0.3.0.dist-info/METADATA,sha256=LtcjQx8O8cbpQ_1HcXVm8Jpo7UyFLfVkPCEe8fEmJIY,4568
+pgwidgets_python-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pgwidgets_python-0.3.0.dist-info/top_level.txt,sha256=wwL6fBq0gU-JwzlM6TdduY1qYpu39ysqnnbQT-1bqAs,10
+pgwidgets_python-0.3.0.dist-info/RECORD,,