pgwidgets.sync¶

Synchronous API for pgwidgets.

Application¶

class pgwidgets.sync.application.Application(ws_port=9500, http_port=9501, host='127.0.0.1', http_server=True, concurrency_handling='per_session', max_sessions=1, logger=None)¶

Bases: object

Main entry point for a synchronous pgwidgets application.

Creates a WebSocket server for widget commands and optionally an HTTP server to serve the JS/CSS assets. Each browser connection gets its own Session.

Parameters:

ws_port (int) – WebSocket server port (default 9500).
http_port (int) – HTTP file server port (default 9501). Ignored if http_server=False.
host (str) – Bind address (default ‘127.0.0.1’).
http_server (bool) – Whether to start the built-in HTTP server (default True). Set to False if you are serving the pgwidgets static files from your own HTTP/HTTPS server (e.g. Flask, FastAPI, nginx).
concurrency_handling (str) –
How widget callbacks are dispatched. One of:

"per_session" (default)
Each session gets its own thread. Callbacks within a session are dispatched sequentially on that thread, but different sessions run concurrently. No locks needed within a session.

"serialized"
All callbacks from all sessions are dispatched on the main thread inside run(). Simple single-threaded model, but one slow callback blocks every session.

"concurrent"
Each callback fires on its own daemon thread. Maximum concurrency, but the caller must manage thread safety for any shared state.
max_sessions (int or None) – Maximum number of concurrent sessions (default 1). Set to None for unlimited. When the limit is reached, new connections are held until an existing session disconnects.
logger (logging.Logger or None) – Logger for status messages. If None (default), a null logger is used and no output is produced.

on_connect(handler)¶

The handler receives one argument: the Session object. Use it to build the UI for that session:

def on_connect(session):
    Widgets = session.get_widgets()
    top = Widgets.TopLevel(title="Hello")
    top.show()

app.on_connect(on_connect)

Can also be used as a decorator:

@app.on_connect
def setup(session):
    ...

on_disconnect(handler)¶

The handler receives one argument: the Session object. Can also be used as a decorator.

start()¶

Start the WebSocket server (and HTTP server if enabled).

Call this after construction and any customisation. Subclasses can override to add extra setup before or after the servers start.

property sessions¶: Dict of active sessions (session_id -> Session).

property url¶: URL to open in a browser to connect (built-in server only).

property static_path¶: Path to the pgwidgets static files directory. Useful when serving files from your own HTTP server.

property remote_html¶: Path to the remote.html connector page. Useful when serving from your own HTTP server.

set_favicon(path)¶

Set a custom favicon for the built-in HTTP server.

Call this before start() to override the default pgwidgets icon.

Parameters:: path (str or Path) – Path to an image file (SVG, PNG, ICO, etc.).

close()¶

Close all sessions and stop the application.

Closes every active session’s WebSocket, stops the HTTP server (if running), and signals run() to return.

run()¶

Start servers and block forever processing callbacks. Ctrl-C to exit.

Calls start() automatically if it hasn’t been called yet.

In serialized mode, callbacks are dispatched on this thread. In per_session and concurrent modes, callbacks run on other threads; this method simply sleeps.

Session¶

class pgwidgets.sync.application.Session(app, ws, session_id)¶

Bases: object

A single browser connection with its own widget tree.

Each browser tab that connects gets its own Session. The session owns the widget map, callback registry, and message-ID counter for that connection.

Parameters:

app (Application) – The owning Application.
ws (websockets.WebSocketServerProtocol) – The WebSocket connection for this session.
session_id (int) – Unique session identifier.

property id¶: Unique session identifier.

property app¶: The Application this session belongs to.

get_widgets()¶

Return a namespace with factory methods for all widget types.

Usage:: Widgets = session.get_widgets() btn = Widgets.Button(“Click me”) vbox = Widgets.VBox(spacing=8)

gui_do(func, *args, **kwargs)¶

Schedule a function to run on this session’s callback thread. Returns immediately without waiting for the result.

In serialized mode this queues on the shared main thread. In per_session mode this queues on this session’s thread. In concurrent mode this runs directly on the calling thread.

gui_call(func, *args, **kwargs)¶

Schedule a function to run on this session’s callback thread and block until it completes. Returns the function’s return value.

In serialized mode this queues on the shared main thread. In per_session mode this queues on this session’s thread. In concurrent mode this runs directly on the calling thread.

make_timer(duration=0)¶: Create a Timer (non-visual) and return its widget wrapper.

close()¶

Close this session’s WebSocket connection.

This triggers the normal disconnect cleanup: the on_disconnect callback fires, the session is removed from the Application, and the per-session thread (if any) is stopped.

Widget¶

class pgwidgets.sync.widget.Widget(session, wid, js_class)¶

Bases: object

Base class for all synchronous widget wrappers.

property session¶: The Session this widget belongs to.

property app¶: The Application this widget belongs to.

on(action, handler, *extra_args, **extra_kwargs)¶: Register a callback. The handler receives (*callback_args, *extra_args, **extra_kwargs) – no widget arg.

add_callback(action, handler, *extra_args, **extra_kwargs)¶: Register a callback. The handler receives (widget, *callback_args, *extra_args, **extra_kwargs).

add_cursor(name, url, hotspot_x, hotspot_y, size=None)¶: Register a named custom cursor. If url is a local file path it is read and converted to a data URI before sending.

destroy()¶: Destroy this widget: tear it down on the JS side and drop it from the Python-side registry so it can be garbage-collected.