Utilities

The Widget base class exposes a few static utility methods that are useful when working with local files on the server side.

from pgwidgets.sync.widget import Widget   # or pgwidgets.async_.widget

to_data_uri

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().

# 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

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 Architecture.

Supported dtypes:

• "uint8" / "uint16" / "uint32"

• "int8" / "int16" / "int32"

• "float32" / "float64"

Methods that don’t opt into Buffer keep receiving plain bytes — 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.