pgwidgets-python 0.3.0__tar.gz → 0.3.2__tar.gz

{pgwidgets_python-0.3.0 → pgwidgets_python-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgwidgets-python
-Version: 0.3.0
+Version: 0.3.2
 Summary: Python bindings for the pgwidgets JavaScript widget library
 Author: PGWidgets Developers
 License: BSD-3-Clause

{pgwidgets_python-0.3.0 → pgwidgets_python-0.3.2}/docs/WhatsNew.rst

@@ -1,6 +1,149 @@
 What's New
 ==========
 
+Recent changes — since ``v0.3.0``
+---------------------------------
+
+``Application.open_url``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A new method asks the connected browser(s) to open a URL in a new
+tab/window (``window.open``):
+
+.. code-block:: python
+
+   app.open_url('https://example.com/')
+
+This opens the link in the *user's* browser rather than on the host
+running Python.  It is a fire-and-forget, per-session broadcast (like
+``set_default_font``) and is available on both the sync and async
+``Application``.  (Note: a browser popup blocker may suppress it if
+the originating user-activation has lapsed.)
+
+Containers report their children: ``get_children``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``Frame``, ``Expander``, ``TopLevel`` and ``Page`` (single-child
+containers) and the menu / toolbar widgets ``Menu``, ``MenuBar`` and
+``ToolBar`` are now container widgets, so their generated wrappers
+expose the container method set -- ``get_children`` / ``num_children``
+/ ``remove`` / ``remove_widget`` / ``remove_all``.  ``get_children()``
+returns the contained widgets (a 0- or 1-element list for the
+single-child containers; the menu actions / submenus / toolbar items
+for the menu/toolbar widgets).
+
+TreeView / TableView: ``set_row_spacing`` / ``set_column_spacing``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Two new methods set the vertical (row) and horizontal (column) cell
+padding (in pixels).  ``set_row_spacing(0)`` yields tight rows.
+
+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``
 ---------------------------------
 

{pgwidgets_python-0.3.0 → pgwidgets_python-0.3.2}/docs/async.rst

@@ -56,6 +56,33 @@ 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.
+
+``open_url(url)`` is also available (same as the sync backend; see
+:doc:`sync`) -- it asks the connected browser(s) to open ``url`` in a
+new tab via ``window.open``.
+
 Session
 -------
 

{pgwidgets_python-0.3.0 → pgwidgets_python-0.3.2}/docs/sync.rst

@@ -71,6 +71,65 @@ 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.
+
+Opening a URL in the browser
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: python
+
+   app.open_url('https://example.com/')
+
+``open_url(url)`` asks the connected browser(s) to open ``url`` in a
+new tab/window (``window.open``) -- i.e. in the *user's* browser, not
+on the host running Python.  It is a fire-and-forget, per-session
+broadcast.  (A browser popup blocker may suppress it if the
+user-activation from the originating click has already lapsed.)
+
 Session
 -------
 

{pgwidgets_python-0.3.0 → pgwidgets_python-0.3.2}/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.3.0 → pgwidgets_python-0.3.2}/docs/widgets.rst

@@ -631,6 +631,7 @@ Hierarchical tree/list display.
   ``select_all(state)``,
   ``set_column_width(col_key, width)``,
   ``set_optimal_column_widths()``,
+  ``set_row_spacing(px)``, ``set_column_spacing(px)``,
   ``sort_by_column(col_key, ascending)``, ``scroll_to_path(path)``,
   ``scroll_to_end()``, ``get_column_count()``, ``get_row_count()``,
   ``set_show_grid(tf)``, ``set_show_row_numbers(tf)``,
@@ -815,6 +816,11 @@ Browser file open/save dialog.
 Menus and Toolbars
 ------------------
 
+``MenuBar``, ``Menu`` and ``ToolBar`` are container widgets: the menu
+actions, submenus and toolbar items they hold are reported by
+``get_children()`` / ``num_children()`` (separators and spacers
+excluded).
+
 MenuBar
 ~~~~~~~
 

pgwidgets_python-0.3.2/examples/flask-multi-process/README.md

@@ -0,0 +1,262 @@
+# Flask multi-process pgwidgets demo
+
+One pgwidgets `Application` per visitor, each in a fresh OS process
+with its own WebSocket port.  Returning visitors (refresh, bookmark,
+second tab pointed at the same URL) are routed back to their
+original process so pgwidgets-python's session-reconstruct path can
+bring the UI back exactly where it was.
+
+- **`server.py`** — Flask front-end.  For each new visitor, spawns
+  a child process running a fresh `Application` and returns an HTML
+  page whose `RemoteInterface` connects to that child's WebSocket
+  port.  Keeps a `(session_id, token) → (port, process)` registry
+  so subsequent visits carrying matching credentials in the URL
+  re-attach to the existing child instead of spawning a new one.
+- **`user_app.py`** — The per-visitor `Application` definition.
+  Subclass `PGFlaskApp` and override `build_gui(session)` to build
+  your UI; the surrounding machinery (socket binding, idle-grace
+  self-shutdown, reporting credentials back to the parent) stays
+  the same.  The child itself binds an ephemeral TCP socket and
+  hands it directly to `Application(ws_sock=...)` — the port is
+  held continuously, no TOCTOU race with another process.  Can
+  also be run standalone (`python user_app.py`) for quick UI
+  debugging without Flask in the loop; the port is auto-allocated
+  and logged.
+
+## Run
+
+```
+pip install Flask pgwidgets-python pgwidgets-js
+python server.py
+# browse to http://localhost:5000/
+```
+
+A *new* visitor (no credentials on the URL) triggers a brand-new
+process.  A *returning* visitor whose URL still carries
+`?session=N&token=ABC` from a previous visit is routed back to the
+existing child for that session, if it's still alive — so a
+refresh, a bookmark, or a second tab opened to the same URL all
+re-attach to the same Application, and pgwidgets-python's session-
+reconstruct path can restore the UI to where it was left.
+
+When the last browser closes (or navigates away), the child waits
+a grace period — `IDLE_GRACE_SECONDS` in `user_app.py`, default
+5 minutes — to absorb page refreshes, brief network drops, and
+the user closing/reopening a laptop, then exits.  A reconnect
+within the grace window cancels the pending shutdown.
+
+### Session routing
+
+The parent keeps a `(session_id, token) → (ws_port, process)`
+registry.  The wire protocol between parent and child is a single
+tagged message:
+
+```
+("ready", ws_port, session_id, token)
+```
+
+sent by the child once, **before** `app.run()` blocks.  The child
+pre-creates a session via `Application.create_session()` and
+builds the UI on it before any browser arrives — so by the time
+the parent responds to the visitor, the credentials are already
+known and the UI is already constructed.  The HTTP handler
+embeds those credentials in the HTML response (via an inline
+`history.replaceState` that runs before the pgwidgets-js module
+script) so the browser's WebSocket handshake lands directly on
+the pre-built session and pgwidgets-python's reconstruct path
+replays the state.
+
+`/` flow:
+
+- credentials present in the URL (a refresh / bookmark / shared
+  link) **and** match an alive child → render HTML pointed at the
+  existing child;
+- credentials missing → spawn a new child, read its `ready`
+  message, register `(session_id, token) → (port, process)`, and
+  render HTML that embeds those credentials onto the URL so the
+  next handshake re-attaches.
+
+The registry is opportunistically cleaned along with the child-
+reaper (any entry whose `Process` is no longer alive is dropped),
+so dead-child credentials don't linger.
+
+### Why pre-create the session
+
+Two reasons:
+
+1. **One round-trip.**  Without prewarm, the child has no
+   credentials until the first browser handshake (where
+   `_ws_handler` creates the session), so the parent can't embed
+   them in the HTML.  You'd either redirect (`302 → /?session=…`)
+   or wait for the credentials before responding.  Prewarm makes
+   the credentials known synchronously at spawn time.
+2. **State preserved across the first refresh.**  Once the
+   credentials are baked onto the URL, a refresh lands the
+   browser on the *same* Application; `do_reconstruct` replays
+   whatever the UI has accumulated by then.  Without prewarm, the
+   first visit creates a session lazily and the credentials only
+   appear on the URL *after* the WebSocket has shaken hands —
+   leaving a small window where a very fast refresh would have
+   spawned a fresh process.
+
+### Try it (verify the reconnect path)
+
+1. Browse to `http://localhost:5000/`.  The URL bar immediately
+   updates to include `?session=…&token=…` — that's the inline
+   `replaceState` baking the pre-warmed session's credentials
+   onto the URL before the pgwidgets-js module loads.
+2. Interact with the demo UI (click the button so the label
+   changes to "Clicked!", say).
+3. **Refresh the tab.**  The label should still say "Clicked!" —
+   you've landed on the *same* Application process, and its
+   session reconstruct path has rebuilt the UI exactly where it
+   was.  Confirm in DevTools → Network → WS that the WebSocket
+   URL's port is unchanged.
+4. Open the same URL (with the session/token query) in a *second*
+   tab.  It joins the same Application — clicking the button in
+   either tab updates the label in both (multi-browser sync).
+
+### Listening on other interfaces
+
+By default Flask and each per-visitor WebSocket bind to
+``127.0.0.1`` (loopback only).  To accept connections from other
+machines:
+
+```
+python server.py --host 0.0.0.0 --port 8080
+```
+
+The bind interface and the WebSocket URL are decoupled — the
+browser is given a ``ws://`` URL derived from the same hostname it
+used to reach Flask, so the same server can be reached via
+``localhost``, by IP address, or by DNS name with no further
+configuration.
+
+## Production deployment (gunicorn + nginx)
+
+The bundled `gunicorn.conf.py` and `nginx.conf` upgrade the demo
+from Flask's dev server to a more production-shaped stack:
+
+```
+pip install gunicorn
+PGW_BIND_HOST=0.0.0.0 gunicorn -c gunicorn.conf.py server:app
+```
+
+Then point nginx at it — see the comments at the top of
+`nginx.conf` for placement (`sites-available` + symlink into
+`sites-enabled`, then `nginx -t && systemctl reload nginx`).
+
+### `PGW_BIND_HOST` (env var)
+
+Under gunicorn there's no CLI to pass `--host` through, so the
+per-visitor WebSocket bind interface is read from the
+`PGW_BIND_HOST` environment variable (default `127.0.0.1`).  Set
+it to `0.0.0.0` to accept connections from other machines.
+
+### Single gunicorn worker — non-negotiable
+
+`gunicorn.conf.py` sets `workers = 1`.  That's a *correctness*
+requirement, not a tuning knob: the `(session_id, token) →
+(port, Process)` registry lives in worker-local memory, so
+multiple workers would each maintain an independent registry
+and nginx would happily route a returning visitor's refresh to
+a worker that has never heard of them — spawning a duplicate
+child process every time.
+
+Concurrency at the Flask layer comes from the worker's thread
+pool (`gthread` + `threads = 16` by default).  The real work —
+the per-visitor pgwidgets sessions — runs in *separate
+subprocesses* anyway, so a single Flask worker isn't a
+bottleneck for typical demo workloads.  If you outgrow it, the
+right upgrade is to **externalise the registry**: a shared
+Redis hash, a SQLite file with file-locking, or a small RPC
+service.  That lets you raise `workers` to whatever you need.
+
+### nginx ↔ gunicorn ↔ child processes
+
+```
+                      ┌── 80/443 ──── nginx ─── 8000 ─── gunicorn ─── server.py (1 worker)
+   browser  ───┤                                                              │
+                      └── ws://host:<child-port>  ────────────────────────────┘
+                                                          (per-visitor subprocesses
+                                                           bound on ephemeral ports)
+```
+
+nginx reverse-proxies the HTML page and the `/pgwidgets-js/`
+static assets to gunicorn.  The per-visitor WebSocket
+connections **do not flow through nginx** — each child process
+binds its own ephemeral TCP port and the browser connects to it
+directly.  Two practical consequences:
+
+1. The application host must have the child's port range
+   reachable from wherever your users connect (public internet,
+   VPN, internal LAN, …).  `multiprocessing.Process` gets a
+   random ephemeral port from the OS by default; if you need a
+   bounded firewall range, change `user_app.py:build_app` to
+   bind from a fixed pool instead.
+2. TLS termination at nginx here covers HTTP only.  An HTTPS
+   page that tries to open a plain `ws://` WebSocket runs into
+   browser mixed-content blocking — so for HTTPS deployments
+   you'd usually want to route WebSockets through a TLS-
+   terminating proxy as well.  See the "WebSocket note" at the
+   bottom of `nginx.conf` for the rough shape of that change.
+
+### Subprocess start method
+
+`server.py` calls `multiprocessing.set_start_method("spawn",
+force=True)` at module load.  Forking child processes from a
+gunicorn worker drags the worker's file descriptors, signal
+handlers, and thread state into every child — flaky.  Spawn
+re-execs a fresh Python interpreter for each child, which is
+what `user_app.py` is written for anyway (it re-imports itself
+in the child).
+
+## What the browser loads
+
+Each HTML response embeds the per-visitor WebSocket URL.  The
+pgwidgets-js bundle (`Widgets.js`, `Widgets.css`, the `modules/`
+subtree, icons) is served by Flask itself, from the pip-installed
+`pgwidgets-js` Python package — `pgwidgets_js.get_static_path()`
+returns the directory and a `/pgwidgets-js/<path>` route in
+`server.py` exposes it.  No CDN, no network dependency at runtime,
+and the version on the wire always matches the one in your venv.
+
+To point at an in-progress working copy of pgwidgets-js instead of
+the installed package, either ``pip install -e .`` from the
+pgwidgets-js source tree (so `get_static_path()` resolves to the
+working copy), or replace `PGWIDGETS_JS_ROOT` in `server.py` with
+a hard path to that tree's `static/` directory.
+
+## Caveats
+
+- **Flask debug mode is off.** The reloader spawns a second
+  process, which combined with `multiprocessing` can produce
+  surprising behavior on Windows / macOS.  Restart `server.py` by
+  hand after edits.
+- **Trust model for the routing token.** The registry trusts the
+  `token` URL query parameter as proof of session identity — the
+  same threat model pgwidgets-python's `_ws_handler` uses for
+  WebSocket-level reconnect.  Anyone who can read a session URL
+  can re-attach to that session.  Tokens are randomly generated
+  and long enough that guessing is impractical, but URL theft
+  (shared link, browser-history snoop, server log) lets the
+  thief in.  Don't expose this demo unmodified on the open
+  internet without thinking through how URLs leak in your
+  context.
+- **Reaper is request-driven, not periodic.** A child that has
+  self-terminated after the idle grace will sit as a zombie until
+  the next `/` request triggers `_reap_dead_children()`.  Fine for
+  a demo; for an idle production server you'd add a periodic
+  background reaper (e.g. a `threading.Timer` chain).
+- **Single-message-per-tag protocol.** The child sends `("port", …)`
+  once and `("creds", …)` once.  If you extend the demo to update
+  state in the parent over time, switch to a clear schema and
+  document it (and consider replacing the `Queue` with a `Pipe` or
+  a small RPC layer).
+- **Per-worker registry under gunicorn.** The
+  `(session_id, token) → (port, Process)` registry is in-memory
+  inside the gunicorn worker, so the bundled `gunicorn.conf.py`
+  pins `workers = 1`.  Raising the worker count silently breaks
+  session re-attach (every refresh routed to a fresh worker
+  spawns a duplicate child).  See "Production deployment" above
+  for the upgrade path (externalised registry).

pgwidgets_python-0.3.2/examples/flask-multi-process/gunicorn.conf.py

@@ -0,0 +1,76 @@
+"""Gunicorn config for the flask-multi-process pgwidgets demo.
+
+Run with::
+
+    PGW_BIND_HOST=0.0.0.0 gunicorn -c gunicorn.conf.py server:app
+
+Key constraint — *one worker only*.
+======================================
+
+This demo keeps a per-process in-memory registry of
+``(session_id, token) -> (port, Process)`` so a returning visitor
+(refresh, bookmark, second tab) re-attaches to their *existing*
+child process within the idle grace period.
+
+That registry is local to the gunicorn worker that handles the
+request.  If we ran multiple workers, each would have an
+independent registry — and the moment nginx routed a refresh to
+a different worker than the one that spawned the original child,
+the demo would silently spawn a duplicate process.
+
+So ``workers = 1`` is not a tuning knob; it's a correctness
+requirement.  Concurrency comes from:
+
+  * the worker's thread pool below (``gthread`` + ``threads = N``),
+    so multiple HTTP requests can be served at once even though
+    one of them is briefly blocked waiting on a child's
+    "ready" message; and
+  * the per-visitor subprocesses themselves — those do the
+    actual pgwidgets work and run independently of the Flask
+    layer.
+
+If you need a multi-worker Flask layer, the upgrade path is to
+externalise the registry (Redis, SQLite, etc.) so every worker
+shares it.  That's a bigger change; see the README.
+"""
+
+import os
+
+# ----- Bind ----------------------------------------------------
+# Where gunicorn listens for HTTP.  Behind nginx the default
+# loopback bind is fine and most secure.
+bind = os.environ.get("PGW_GUNICORN_BIND", "127.0.0.1:8000")
+
+# ----- Concurrency --------------------------------------------
+# See the docstring — *do not* increase ``workers`` without
+# externalising the registry.
+workers = 1
+worker_class = "gthread"
+threads = int(os.environ.get("PGW_GUNICORN_THREADS", "16"))
+
+# Don't ``preload_app``.  Each worker (we only have one) should
+# import ``server.py`` itself, so ``multiprocessing.set_start_method``
+# runs in the same process that later spawns children.  Preloading
+# would run the imports in the gunicorn master and then fork the
+# worker — for start_method=spawn it doesn't matter much, but
+# avoiding it keeps the model simpler to reason about.
+preload_app = False
+
+# ----- Timeouts -----------------------------------------------
+# The ``/`` handler waits up to 5 s on a child's ``ready`` message
+# (see ``server.py:index``).  The default gunicorn worker timeout
+# is 30 s, which already covers that — but bump it a little so a
+# slow first-time import (e.g. cold-start of a per-visitor app
+# with a heavy import graph) doesn't get the worker killed.
+timeout = 60
+
+# Keep gthread workers around long enough to absorb the burst of
+# requests when many visitors hit at once.
+graceful_timeout = 30
+keepalive = 5
+
+# ----- Logging ------------------------------------------------
+# Send to stdout/stderr so journald / Docker pick it up naturally.
+accesslog = "-"
+errorlog = "-"
+loglevel = os.environ.get("PGW_GUNICORN_LOGLEVEL", "info")