[cpsievert]

@render_pygwalker renders PyGWalker's Tableau-style drag-and-drop explorer as a Shiny output. Return a pandas DataFrame (a polars one works when the installed pygwalker can read it — see below), or a widget from pygwalker.api.anywidget.walk() to pass PyGWalker options like theme_key. The explorer computes in the Python process, fills its card or container (scrolling instead of clipping when the container is shorter than its ~750px UI), and re-renders reactively — see examples/pygwalker for a dataset switcher.

Part of #278.

Security model

PyGWalker runs the SQL its browser sends on DuckDB's process-wide default connection, shared by every PyGWalker widget in the process under one fixed view name. A Shiny app can't safely expose that as-is, so this renderer:

• Requires the connection to be locked down before rendering (enable_external_access = false + lock_configuration = true), raising with instructions otherwise. This blocks SQL that reaches the server's filesystem or network.
• Validates visitor SQL (get_datas, batch_get_datas_by_sql, export_dataframe_by_sql) with sqlglot: only single SELECT statements against the widget's own data. Without this, any visitor could persist DDL in the shared in-memory database for every other visitor to read, or query anything else registered on the connection.
• Rejects the actions that can't be made safe: open_in_desktop (shells out to the server's gw:// handler) and upload_spec_to_cloud with a visitor-supplied Kanaries token (it would overwrite the server's stored credentials).

Residual caveats, documented in the docstring: the shared connection/table namespace and register-then-query timing mean per-user data isolation is not a hard boundary, and expensive queries block every session while they run. The explorer is best suited to trusted users; per-widget isolation requested upstream at Kanaries/pygwalker#747.

Compatibility

• Works with pygwalker 0.4.9.13+, verified against the current release (0.5.0.1) and main (0.6.0rc0), which renames the widget class (_WalkerWidget → WalkerAnyWidget) and moves some internals; detection and hardening handle both.
• Polars frames are accepted when the installed pygwalker can read them: every release so far trips over dtype groups polars 1.0 removed, but the fix is merged upstream and due in 0.6 — the renderer probes for it, so polars starts working automatically when a fixed pygwalker is installed, and gives a df.to_pandas() hint until then.
• No comm changes needed; PyGWalker's anywidget API works over the existing custom-message transport.

Notes

• Privacy: PyGWalker's update check and anonymous usage events are on by default (Python process and browser). Call pygwalker.GlobalVarManager.set_privacy("offline") to disable both; the docstring and example mention this.
• The widget has no interaction traits, so there's nothing to reactive_read(); the browser→Python round trip is tested by counting pyg_request messages.
• The pygwalker extra lists duckdb and sqlglot explicitly since apps and shinywidgets import them directly.

Verification

• 43 unit tests pass against both pygwalker 0.5.0.1 and main (0.6.0rc0), plus pyright and format checks.
• 7 Playwright tests (renders cleanly, fill measurement, explicit heights, Python round trip, re-render lifecycle) pass, confirming the SQL validation doesn't break legitimate explorer traffic.
• Example app smoke-tested with a dataset switch.

Known limitations

• The Playwright tests need network access for leaflet.css from unpkg (subresource integrity hash, can't be stubbed). Banner images are stubbed.