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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.2.3
+Version: 0.3.1
 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.1}/docs/WhatsNew.rst

@@ -1,6 +1,185 @@
 What's New
 ==========
 
+Recent changes — since ``v0.3.0``
+---------------------------------
+
+Custom fonts: ``Application.register_font`` / ``set_default_font``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two new methods on ``Application`` let the Python side ship
+custom font files to the browser and apply a document-wide
+default font.
+
+.. code-block:: python
+
+   app.register_font('Roboto', '/path/to/Roboto-Regular.ttf')
+   app.register_font('Roboto', '/path/to/Roboto-Bold.ttf',
+                     weight='bold')
+   app.set_default_font('Roboto', size=13)
+
+* ``register_font(family, source, *, weight, style)`` -- stores
+  the font bytes in an in-memory registry keyed by a monotonic
+  id; the built-in HTTP server exposes them at
+  ``/_pgwidgets/font/<id>`` with ``Cache-Control: immutable``.
+  Accepts paths (``str`` / ``os.PathLike``) or raw ``bytes``.
+* ``set_default_font(family, *, size, weight, style)`` --
+  writes ``--pg-default-font-{family,size,weight,style}`` CSS
+  variables on ``:root`` via a managed ``<style>`` element on
+  the JS side.  The base widget stylesheet consumes them with
+  safe fallbacks so apps that never opt in see no change in
+  rendering.
+
+Both methods broadcast to every connected session immediately
+and replay the entire registry to every new / reconnecting
+session before ``on_connect`` / ``reconstruct`` runs.  That
+guarantees a widget that's reconstructed with
+``set_font(family, ...)`` always finds the face already
+declared on the JS side, even after a full page reload.
+
+The JS handler normalises descriptive TTF weight names
+(``thin``, ``light``, ``medium``, ``semibold``, ``extrabold``,
+``black``, ``heavy``, ...) to the numeric CSS values per the
+CSS Fonts spec, so a font registry that knows weights by their
+metadata name (e.g. Ginga's ``font_asst``) can pass weights
+straight through.
+
+The matching sync- and async-backend API are identical; the
+async variant schedules sends via
+``asyncio.run_coroutine_threadsafe`` so ``register_font`` is
+callable from outside the event loop.
+
+See :doc:`sync` / :doc:`async` for the full API description.
+
+Flask multi-process example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``examples/flask-multi-process`` is a new end-to-end demo of
+running pgwidgets-python behind Flask + gunicorn + nginx, with
+one OS process per browser session.  Highlights:
+
+* ``Application`` accepts ``ws_sock=`` and a session can be
+  pre-warmed in the worker process before the browser opens
+  its WebSocket -- the worker spawns, runs the user-app's
+  ``build_ui`` against an empty session, and then waits for
+  the WS handshake.
+* Session-aware routing so a Flask front-end can hand each
+  browser tab off to a dedicated worker by session ID.
+* Dead-child reaping (``waitpid(WNOHANG)``) to avoid zombie
+  worker processes piling up.
+* The user app is a Python class (``app.build_ui(session)``),
+  so worker pre-warming, multi-tab fanout, and reconstruction
+  reuse the same entry point.
+* The gunicorn / nginx layer serves the bundled pgwidgets-js
+  static assets from the pip-installed package (no separate
+  jsdelivr fetch needed).
+
+See ``examples/flask-multi-process/README.md`` for the full
+production stack walkthrough.
+
+file_browser: ``col_key`` on row-activated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``pgwidgets.extras.file_browser`` matches the JS-side
+TreeView/TableView ``activated`` callback signature change:
+``FileBrowser._on_row_activated`` now receives ``col_key`` as
+the 4th argument, so handlers that double-click a file can see
+which column they hit.  Existing handlers (3-arg) keep working.
+
+``_resolve_kwargs``: skipped-positional kwargs
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The kwarg resolver used by every generated widget method now
+allows a caller to skip a positional argument and supply the
+next one by keyword.  For example, with a method declared as
+``set_color(bg=None, fg=None)``, callers may now write
+``label.set_color(fg="red")`` directly instead of
+``label.set_color(None, "red")``.  Previously the resolver
+would reject the keyword-only form for parameters that
+preceded any supplied keyword.
+
+method_types: TreeView colour + cell-selection methods classified as ACTION
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Internal: the four ``set_*_color`` overrides and the new
+``select_cell`` / ``select_cells`` / ``clear_cell_selection``
+methods are now ACTION-typed, so the wrapper layer dispatches
+each call straight through to the JS side instead of trying to
+collapse them into a single ``_state`` slot.  Matters for
+reconstruction-replay; rarely matters for application code.
+
+----
+
+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.1}/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.1}/docs/async.rst

@@ -56,6 +56,29 @@ Running
 
 ``await app.close()`` shuts down all sessions and causes ``run()`` to return.
 
+Custom fonts
+~~~~~~~~~~~~
+
+Same ``register_font`` / ``set_default_font`` API as the sync
+backend (see :doc:`sync`); both are plain sync methods that
+schedule the broadcast onto the event loop via
+``asyncio.run_coroutine_threadsafe``, so they're safe to call
+from both inside and outside the loop.
+
+.. code-block:: python
+
+   app.register_font('Roboto', '/path/to/Roboto-Regular.ttf')
+   app.register_font('Roboto', '/path/to/Roboto-Bold.ttf',
+                     weight='bold')
+   app.set_default_font('Roboto', size=13)
+
+Bytes are kept in memory on the ``Application`` and served by
+the built-in HTTP server at ``/_pgwidgets/font/<id>``.  Fonts
+are replayed to every new and reconnecting session before
+``on_connect`` / ``reconstruct`` runs, so widgets reconstructed
+with ``set_font(family, ...)`` always find the face already
+declared.
+
 Session
 -------
 

{pgwidgets_python-0.2.3 → pgwidgets_python-0.3.1}/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.2.3 → pgwidgets_python-0.3.1}/docs/sync.rst

@@ -71,6 +71,52 @@ Running
 
 ``app.close()`` shuts down all sessions and stops the servers.
 
+Custom fonts
+~~~~~~~~~~~~
+
+Two methods on ``Application`` push custom font files to the
+browser and apply a document-wide default font.  Both broadcast
+to every connected session immediately, and replay the entire
+registry + default font to every new / reconnecting session
+*before* ``on_connect`` / ``reconstruct`` runs -- so any widget
+that takes ``set_font(family, ...)`` always finds the face
+already declared on the JS side.
+
+.. code-block:: python
+
+   # Register one or more faces for a family
+   app.register_font('Roboto', '/path/to/Roboto-Regular.ttf')
+   app.register_font('Roboto', '/path/to/Roboto-Bold.ttf',
+                     weight='bold')
+   app.register_font('Roboto', '/path/to/Roboto-Italic.ttf',
+                     style='italic')
+
+   # Apply a document-wide default
+   app.set_default_font('Roboto', size=13)
+
+   # Later use it on a single widget (or anywhere CSS sees it)
+   label.set_font('Roboto', 14)
+
+* ``source`` is a path (``str`` / ``os.PathLike``) or raw
+  ``bytes``.  Accepted formats: ``.ttf``, ``.otf``, ``.woff``,
+  ``.woff2`` -- the Content-Type is set from the extension.
+* ``weight`` accepts CSS keywords, numeric strings, *and*
+  common TTF metadata names (``thin``, ``light``, ``medium``,
+  ``semibold``, ``extrabold``, ``black``, ``heavy``, etc.) --
+  the JS handler normalises descriptive names to numeric CSS
+  values per the CSS Fonts spec.
+* ``style`` accepts ``'normal'``, ``'italic'``, or
+  ``'oblique'``; synonyms (``'roman'``, ``'slanted'``) are
+  normalised too.
+* ``set_default_font(family=None)`` clears the override.
+
+Bytes are served from ``/_pgwidgets/font/<id>`` by the built-in
+HTTP server with ``Cache-Control: immutable``; behind Flask /
+nginx the same route is served from the Python process.
+
+See also the JS-side write-up at :ref:`custom-fonts` in the
+pgwidgets-js documentation.
+
 Session
 -------
 

pgwidgets_python-0.3.1/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.1}/docs/web-servers.rst

@@ -276,6 +276,14 @@ Flask
    if __name__ == "__main__":
        web.run(host="0.0.0.0", port=8000)
 
+For a production-style stack -- gunicorn workers, an nginx
+reverse proxy, one OS process per browser session, and
+session-aware routing -- see ``examples/flask-multi-process``.
+That example also demonstrates pre-warming the per-session
+worker with a Python-class user app before the browser opens
+its WebSocket, and reaping dead child workers so zombies don't
+accumulate.
+
 
 Apache
 ------

{pgwidgets_python-0.2.3 → pgwidgets_python-0.3.1}/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
 ~~~~~~