pgwidgets-python 0.2.1__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
 
@@ -91,6 +91,13 @@ class Session:
     _STATE_KEY_TO_SETTER = {v: k for k, v in SPECIAL_SETTERS.items()}
     # e.g. {"size": "resize"}
 
+    # Reverse map: state_key -> callback action that auto-syncs it
+    # (e.g. "size" -> "resize", "position" -> "move").  Used during
+    # state replay to skip keys that weren't actively opted into via
+    # _auto_sync_actions — those were captured passively for getter
+    # support but must not be replayed (would pin layout).
+    _STATE_KEY_TO_SYNC_ACTION = {v: k for k, v in STATE_SYNC_CALLBACKS.items()}
+
     # State keys handled by fixed-value methods (show/hide)
     _FIXED_STATE_KEYS = {}
     for _mname, (_key, _val) in FIXED_SETTERS.items():
@@ -118,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
@@ -187,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:
@@ -209,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 —
@@ -237,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)
             )
         )
@@ -267,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,
@@ -292,38 +341,54 @@ 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)
 
     def _dispatch_callback(self, wid, action, *args):
         """Dispatch a callback through the configured concurrency mode."""
-        if self._reconstructing:
-            return  # suppress callbacks during reconstruction
+        # Suppress callbacks during reconstruction — they are side
+        # effects of state replay, not user actions.  Exception: 'map'
+        # is a one-shot lifecycle event that the JS-side observers fire
+        # when a widget first gains a visible layout box; the timing
+        # can land inside the reconstruction window, and dropping it
+        # means the user's map handler never runs until a later layout
+        # change (e.g. window resize) triggers a re-fire.
+        if self._reconstructing and action != 'map':
+            return
 
         # Auto-sync: some callbacks carry state that should be reflected
         # in the Python-side widget (e.g. move -> position, resize -> size).
+        # We always *capture* the value so get_size()/get_position() return
+        # current values, but only *push* it to other browsers (and replay
+        # it on reconstruction) when the widget opted in via auto-sync.
+        # Otherwise a layout-determined size would replay as a literal
+        # resize(W, H) — pinning the widget to pixel dimensions and
+        # killing flex growth.
         state_key = STATE_SYNC_CALLBACKS.get(action)
         if state_key is not None:
             widget = self._widget_map.get(wid)
             if widget is not None:
+                auto = action in widget._auto_sync_actions
                 if len(args) == 1 and isinstance(args[0], dict):
                     d = args[0]
                     if "width" in d and "height" in d:
                         new_val = (d["width"], d["height"])
                         if widget._state.get(state_key) != new_val:
                             widget._state[state_key] = new_val
-                            self._push(wid, "resize",
-                                       d["width"], d["height"])
+                            if auto:
+                                self._push(wid, "resize",
+                                           d["width"], d["height"])
                 else:
                     new_val = tuple(args)
                     if widget._state.get(state_key) != new_val:
                         widget._state[state_key] = new_val
-                        setter = (self._STATE_KEY_TO_SETTER.get(state_key)
-                                  or f"set_{state_key}")
-                        self._push(wid, setter, *args)
+                        if auto:
+                            setter = (self._STATE_KEY_TO_SETTER.get(state_key)
+                                      or f"set_{state_key}")
+                            self._push(wid, setter, *args)
                 # If this widget wraps a child (e.g. MDISubWindow),
                 # propagate geometry into the parent's children options
                 # so reconstruction replays with the current pos/size.
@@ -639,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.
 
@@ -735,17 +863,37 @@ class Session:
             cls = self._widget_classes.get(cls_name, Widget) if cls_name else Widget
             widget = cls._from_existing(self, wid, cls_name or "Widget")
             self._widget_map[wid] = widget
-            # Auto-listen for state-syncing callbacks (move, resize)
-            # so position/size changes are tracked for reconstruction.
+            # Auto-listen for state-syncing callbacks (move, resize).
             # Register locally (sync) and send the listen message as
             # true fire-and-forget (no result awaited) since
-            # _resolve_return is not async.
+            # _resolve_return is not async.  For visual widgets we
+            # always listen for 'resize' so get_size() can return a
+            # current value, but we only mark the action as
+            # auto-syncing (which triggers push-to-peers and
+            # replay-on-reconstruction) when the widget defn opts in.
+            # Non-visual Callback-base objects (Timer, TextBufferRef,
+            # …) get nothing.
+            defn = WIDGETS.get(cls_name, {}) if cls_name else {}
+            opt_names_set = set(defn.get("options", []))
+            all_callbacks = defn.get("callbacks", [])
+            is_visual = defn.get("base") != "callback"
             for action in STATE_SYNC_CALLBACKS:
-                key = f"{wid}:{action}"
-                if key not in self._callbacks:
-                    self._callbacks[key] = [lambda wid, *a: None]
-                    self._fire_and_forget_listen(wid, action)
-                widget._auto_sync_actions.add(action)
+                req_opt = STATE_SYNC_REQUIRES_OPTION.get(action)
+                if req_opt is not None:
+                    opted_in = req_opt in opt_names_set
+                else:
+                    opted_in = action in all_callbacks
+                if not is_visual:
+                    continue
+                if action == "resize" or opted_in:
+                    key = f"{wid}:{action}"
+                    if key not in self._callbacks:
+                        self._callbacks[key] = [lambda wid, *a: None]
+                        self._fire_and_forget_listen(wid, action)
+                if opted_in:
+                    widget._auto_sync_actions.add(action)
+                elif action == "resize":
+                    widget._passive_sync_actions.add(action)
             return widget
         if isinstance(val, list):
             return [self._resolve_return(v) for v in val]
@@ -839,12 +987,23 @@ class Session:
                 await self._listen(new_widget._wid, act,
                                    lambda wid, *a: None)
                 new_widget._auto_sync_actions.add(act)
-        # Replay any state the proxy accumulated (e.g. set_tooltip)
+        # Replay any state the proxy accumulated (e.g. set_tooltip).
+        # Skip passively-captured auto-sync state (size, position): we
+        # capture those from callbacks so getters work, but replaying
+        # would pin the widget to layout-determined pixel dimensions
+        # (same logic as _reconstruct_widget).
+        user_set = getattr(old_widget, "_user_set_state", set())
+        auto = getattr(old_widget, "_auto_sync_actions", set())
         for key, value in old_widget._state.items():
             if key.startswith("_"):
                 continue
             if key in sync_keys:
                 continue
+            sync_action = self._STATE_KEY_TO_SYNC_ACTION.get(key)
+            if (sync_action is not None
+                    and key not in user_set
+                    and sync_action not in auto):
+                continue
             method_name = (self._STATE_KEY_TO_SETTER.get(key)
                            or f"set_{key}")
             if isinstance(value, tuple):
@@ -852,6 +1011,13 @@ class Session:
             else:
                 await self._call(new_widget._wid, method_name, value)
             new_widget._state[key] = value
+            # Propagate user-set / auto-sync membership to the new
+            # widget so subsequent reconstructions replay consistently.
+            if sync_action is not None:
+                if key in user_set:
+                    new_widget._user_set_state.add(key)
+                if sync_action in auto:
+                    new_widget._auto_sync_actions.add(sync_action)
 
     async def _ensure_reconstructed(self, widget):
         """Ensure a widget has been created on the JS side."""
@@ -1003,13 +1169,28 @@ class Session:
             if key.startswith("_"):
                 continue
 
+            # Skip auto-sync state (size, position) that came in
+            # passively via a callback (e.g. layout-determined size).
+            # We capture those so getters like get_size()/
+            # get_position() work, but replaying them would pin the
+            # widget to pixel dimensions and override flex/expanding
+            # layout.  Replay only if the user explicitly set the
+            # value, or if the widget opted into the sync action
+            # (e.g. an interactively-resizable widget).
+            sync_action = self._STATE_KEY_TO_SYNC_ACTION.get(key)
+            if (sync_action is not None
+                    and key not in widget._user_set_state
+                    and sync_action not in widget._auto_sync_actions):
+                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:
@@ -1047,10 +1228,13 @@ class Session:
         # _listen calls treat them as first-time registrations and
         # actually send the "listen" message to the browser.
         wid = widget._wid
+        passive = getattr(widget, "_passive_sync_actions", set())
         for action in list(saved_cbs.keys()):
             self._callbacks.pop(f"{wid}:{action}", None)
         for action in widget._auto_sync_actions:
             self._callbacks.pop(f"{wid}:{action}", None)
+        for action in passive:
+            self._callbacks.pop(f"{wid}:{action}", None)
 
         for action, entries in saved_cbs.items():
             for handler, extra_args, extra_kwargs, style in entries:
@@ -1067,6 +1251,13 @@ class Session:
             if action not in widget._registered_callbacks:
                 await self._listen(widget._wid, action,
                                    lambda wid, *a: None)
+        # Passive listeners (e.g. 'resize' for getter support on
+        # widgets that didn't opt into auto-sync).
+        for action in passive:
+            if (action not in widget._registered_callbacks
+                    and action not in widget._auto_sync_actions):
+                await self._listen(widget._wid, action,
+                                   lambda wid, *a: None)
 
     async def reconstruct(self):
         """Replay the entire widget tree to all connected browsers.
@@ -1204,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
@@ -1567,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/async_/widget.py

@@ -79,6 +79,16 @@ class Widget:
         self._constructor_options = {}
         self._registered_callbacks = {}
         self._auto_sync_actions = set()
+        # Actions we listen to passively for getter support
+        # (e.g. 'resize' on every visual widget so get_size() returns
+        # a current value), but that aren't in _auto_sync_actions and
+        # therefore don't push to peers or replay on reconstruction.
+        self._passive_sync_actions = set()
+        # State keys the user explicitly set via a setter call.
+        # Used during reconstruction to decide whether a state key
+        # should be replayed: passively-captured callback state
+        # (e.g. layout-determined size) is NOT in this set.
+        self._user_set_state = set()
         self._replay_calls = []
         self._add_seq = 0
 
@@ -196,6 +206,8 @@ class Widget:
         obj._constructor_options = {}
         obj._registered_callbacks = {}
         obj._auto_sync_actions = set()
+        obj._passive_sync_actions = set()
+        obj._user_set_state = set()
         obj._replay_calls = []
         obj._stale = False
         return obj
@@ -212,15 +224,31 @@ class Widget:
         opt_names_set = set(defn.get("options", []))
         all_callbacks = defn.get("callbacks", [])
 
-        # State-sync callbacks (move -> position, resize -> size)
+        # State-sync callbacks (move -> position, resize -> size).
+        # For visual widgets we always *listen* so getters like
+        # get_size() / get_position() can return current values.
+        # But we only add the action to _auto_sync_actions — which
+        # controls push-to-peers and replay-on-reconstruction — when
+        # the widget actually opted in (e.g. via the 'resizable' option
+        # or by declaring the callback in its defn).  This keeps
+        # layout-determined sizes from being replayed as literal
+        # resize() calls that would pin flex/expanding widgets.
+        is_visual = defn.get("base") != "callback"
         for action in STATE_SYNC_CALLBACKS:
             req_opt = STATE_SYNC_REQUIRES_OPTION.get(action)
-            if req_opt and req_opt not in opt_names_set:
-                continue
-            if req_opt is None and action not in all_callbacks:
+            opted_in = False
+            if req_opt is not None:
+                opted_in = req_opt in opt_names_set
+            else:
+                opted_in = action in all_callbacks
+            if not is_visual:
                 continue
-            await session._listen(wid, action, lambda wid, *a: None)
-            self._auto_sync_actions.add(action)
+            if action == "resize" or opted_in:
+                await session._listen(wid, action, lambda wid, *a: None)
+            if opted_in:
+                self._auto_sync_actions.add(action)
+            elif action == "resize":
+                self._passive_sync_actions.add(action)
 
         # Per-widget-class state sync (e.g. Slider "activated" -> value)
         cls_sync = WIDGET_CALLBACK_SYNC.get(js_class, {})
@@ -461,6 +489,9 @@ def _make_setter(method_name, param_names, state_key):
             self._state[state_key] = args[0]
         else:
             self._state[state_key] = args
+        # Mark as user-set so reconstruction knows to replay this key
+        # (callback-captured values for the same key don't get marked).
+        self._user_set_state.add(state_key)
         return await self._call(method_name, *args)
     method.__name__ = method_name
     method.__qualname__ = f"Widget.{method_name}"
@@ -473,6 +504,7 @@ def _make_fixed_setter(method_name, state_key, fixed_value):
     """Create a no-arg async method that sets a fixed state value (show/hide)."""
     async def method(self):
         self._state[state_key] = fixed_value
+        self._user_set_state.add(state_key)
         return await self._call(method_name)
     method.__name__ = method_name
     method.__qualname__ = f"Widget.{method_name}"

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)