pgwidgets-python 0.2.3__py3-none-any.whl → 0.3.1__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

@@ -16,6 +16,7 @@ import logging
 import mimetypes
 import signal
 import secrets
+import threading
 import traceback
 from http.server import SimpleHTTPRequestHandler
 from pathlib import Path
@@ -30,13 +31,22 @@ 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
 
 _CONCURRENCY_MODES = ("serialized", "per_session", "concurrent")
 
 
+# MIME types for the font formats register_font accepts.
+_FONT_MIME = {
+    ".ttf":   "font/ttf",
+    ".otf":   "font/otf",
+    ".woff":  "font/woff",
+    ".woff2": "font/woff2",
+}
+
+
 class _Namespace:
     """Holds widget factory methods as attributes (W.Button, W.Label, etc.)."""
     pass
@@ -125,6 +135,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 +207,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 +242,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 +280,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 +325,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 +351,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 +714,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 +1194,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 +1405,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
@@ -1315,6 +1438,13 @@ class Application:
         self._session_semaphore = None  # initialized in start()
         self._cb_lock = None         # for "serialized" mode
 
+        # Custom-font registry — see sync.application for details.
+        self._fonts = []
+        self._fonts_by_id = {}
+        self._next_font_id = 1
+        self._default_font = None
+        self._font_lock = threading.Lock()
+
         self._run_future = None      # set in run(), cancelled by close()
         self._httpd = None           # HTTP server instance
 
@@ -1380,6 +1510,104 @@ class Application:
         self._widget_classes[name] = cls
         return cls
 
+    # ----- Custom font registration ---------------------------
+    #
+    # API matches the sync backend; see ``sync.application`` for
+    # full docstrings.  The async variant schedules sends on the
+    # event loop via ``asyncio.run_coroutine_threadsafe`` so the
+    # method is safe to call from outside the loop (e.g. from the
+    # ``on_connect`` callback running on a worker thread).
+
+    def register_font(self, family, source, *,
+                      weight="normal", style="normal"):
+        if isinstance(source, (bytes, bytearray, memoryview)):
+            data = bytes(source)
+            mime = "font/ttf"
+        else:
+            p = Path(source)
+            data = p.read_bytes()
+            mime = _FONT_MIME.get(p.suffix.lower(), "font/ttf")
+        with self._font_lock:
+            font_id = self._next_font_id
+            self._next_font_id += 1
+            entry = {
+                "id": font_id,
+                "family": str(family),
+                "weight": str(weight),
+                "style": str(style),
+                "bytes": data,
+                "mime": mime,
+            }
+            self._fonts.append(entry)
+            self._fonts_by_id[font_id] = entry
+        msg = self._font_register_msg(entry)
+        self._broadcast_font_msg(msg)
+        return font_id
+
+    def set_default_font(self, family, *, size=None,
+                         weight=None, style=None):
+        if family is None:
+            self._default_font = None
+        else:
+            self._default_font = {
+                "family": str(family),
+                "size":   None if size is None else float(size),
+                "weight": None if weight is None else str(weight),
+                "style":  None if style is None else str(style),
+            }
+        self._broadcast_font_msg(self._font_default_msg())
+
+    def _font_register_msg(self, entry):
+        return {
+            "type": "register-font",
+            "id": entry["id"],
+            "family": entry["family"],
+            "weight": entry["weight"],
+            "style": entry["style"],
+            "url": f"/_pgwidgets/font/{entry['id']}",
+        }
+
+    def _font_default_msg(self):
+        return {
+            "type": "set-default-font",
+            "font": self._default_font,
+        }
+
+    def _broadcast_font_msg(self, msg):
+        loop = getattr(self, "_loop", None) or asyncio.get_event_loop()
+        for session in list(self._sessions.values()):
+            try:
+                asyncio.run_coroutine_threadsafe(
+                    session._send(dict(msg)), loop)
+            except Exception:
+                pass
+
+    async def _replay_fonts_to_session(self, session):
+        """Push the registry + default font to a session before
+        any user code runs.  ``await``-ed from ``_on_session_open``
+        so the JS side has loaded faces (or at least dispatched
+        the load) before reconstruct / on_connect fires."""
+        with self._font_lock:
+            fonts = list(self._fonts)
+            default = self._default_font
+        for entry in fonts:
+            try:
+                await session._send(self._font_register_msg(entry))
+            except Exception:
+                pass
+        if default is not None:
+            try:
+                await session._send(self._font_default_msg())
+            except Exception:
+                pass
+
+    def _get_font_bytes(self, font_id):
+        with self._font_lock:
+            entry = self._fonts_by_id.get(font_id)
+        if entry is None:
+            return None, None
+        return entry["bytes"], entry["mime"]
+
     @property
     def sessions(self):
         """Dict of active sessions (session_id -> Session)."""
@@ -1490,6 +1718,10 @@ class Application:
 
         if is_reconnect:
             async def do_reconstruct():
+                # Replay the font registry before reconstruct() so
+                # any widget reconstructed with ``set_font(...)``
+                # finds the face already declared.
+                await self._replay_fonts_to_session(session)
                 self._logger.info(
                     f"Session {session.id}: reconstructing UI.")
                 session._reconstructing = True
@@ -1502,10 +1734,16 @@ class Application:
             asyncio.ensure_future(do_reconstruct())
         else:
             self._logger.info(f"Session {session.id} connected.")
-            if self._on_connect:
-                result = self._on_connect(session)
-                if hasattr(result, "__await__"):
-                    asyncio.ensure_future(result)
+            async def do_connect():
+                # Replay fonts before the user callback so any
+                # widget the user builds with ``set_font(family,
+                # ...)`` sees the face already declared.
+                await self._replay_fonts_to_session(session)
+                if self._on_connect:
+                    result = self._on_connect(session)
+                    if hasattr(result, "__await__"):
+                        await result
+            asyncio.ensure_future(do_connect())
 
         try:
             async for message in ws:
@@ -1586,6 +1824,7 @@ class Application:
         favicon_path = self._favicon_path
         ws_host = self._host
         ws_port = self._ws_port
+        app = self
 
         class Handler(SimpleHTTPRequestHandler):
             def __init__(self, *a, **kw):
@@ -1594,6 +1833,27 @@ class Application:
             def do_GET(self):
                 # Strip query string for path matching (e.g. /?session=1)
                 path = self.path.split("?")[0]
+                # Custom-font registry: see sync.application for
+                # the matching implementation.
+                if path.startswith("/_pgwidgets/font/"):
+                    try:
+                        font_id = int(path.rsplit("/", 1)[-1])
+                    except ValueError:
+                        self.send_error(404)
+                        return
+                    data, mime = app._get_font_bytes(font_id)
+                    if data is None:
+                        self.send_error(404)
+                        return
+                    self.send_response(200)
+                    self.send_header("Content-Type", mime)
+                    self.send_header("Content-Length", str(len(data)))
+                    self.send_header(
+                        "Cache-Control", "public, max-age=31536000, immutable")
+                    self.send_header("Access-Control-Allow-Origin", "*")
+                    self.end_headers()
+                    self.wfile.write(data)
+                    return
                 if path == "/" or path == "/index.html":
                     html = remote_html.read_text(encoding="utf-8")
                     inject = (
@@ -1652,8 +1912,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/async_/widget.py

@@ -446,6 +446,11 @@ def _resolve_kwargs(method_name, param_names, args, kwargs):
     are bundled into a dict for that parameter (e.g.
     ``add_widget(child, title="Tab 1")`` becomes
     ``add_widget(child, {"title": "Tab 1"})``).
+
+    Skipped-positional kwargs are supported: a call like
+    ``set_color(fg='red')`` against ``param_names = ['bg', 'fg']``
+    fills the omitted ``bg`` slot with ``None`` (the JS-side
+    default) instead of erroring out.
     """
     if not kwargs:
         return args
@@ -456,7 +461,10 @@ def _resolve_kwargs(method_name, param_names, args, kwargs):
         if name in kwargs:
             merged.append(kwargs.pop(name))
         else:
-            break
+            # Leave a placeholder so subsequent kwargs can land in
+            # later positions.  The JS side reads omitted args as
+            # null / default, which matches ``None`` here.
+            merged.append(None)
     if kwargs and param_names and param_names[-1] == "options":
         # Bundle remaining kwargs into the options dict
         opts_idx = len(param_names) - 1

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/extras/file_browser.py

@@ -352,8 +352,13 @@ class FileBrowser(Callbacks):
                 self._navigate_to(d)
                 self._name_entry.set_text(os.path.basename(path))
 
-    def _on_row_activated(self, values, path):
-        """Double-click on a row."""
+    def _on_row_activated(self, values, path, col_key=None):
+        """Double-click on a row.
+
+        ``col_key`` (TableView ≥ this rev) reports which cell was
+        clicked; unused here since the browser only cares about
+        the row's filename, but the arg has to be in the signature
+        or the new 3-arg dispatch raises TypeError."""
         name = values.get("name", "")
         if name == "..":
             self._go_up()