PyPI - shiny-plotly - Versions diffs - 0.3.1__tar.gz → 0.3.3__tar.gz - Mend

shiny-plotly 0.3.1tar.gz → 0.3.3tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (39) hide show

{shiny_plotly-0.3.1 → shiny_plotly-0.3.3}/.gitignore RENAMED Viewed

@@ -7,3 +7,4 @@ __pycache__/
 .pytest_cache/
 .ruff_cache/
 tmp/
+site/

{shiny_plotly-0.3.1 → shiny_plotly-0.3.3}/CHANGELOG.md RENAMED Viewed

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
+## [0.3.3](https://github.com/rvben/shiny-plotly/compare/v0.3.2...v0.3.3) - 2026-08-21
+### Added
+- A themed chart takes its color mode from the nearest ancestor that carries `data-bs-theme`, itself included, instead of from `<html>` alone. Bootstrap honors the attribute on any element, so `ui.div(..., data_bs_theme="dark")` around part of a page now themes the charts inside it while the rest of the page follows the page mode. The observer watches the whole subtree, so the attribute can be set on a container after the charts are drawn; that is all a control of your own needs to drive the mode, and the README carries the recipe.
+- A warning, said once per process, when `plotly.min.js` is served gzipped because `brotli` is not installed: it names the size being served and the roughly 17% brotli would save. Without it a deployment has no way to notice, since the bundle is compressed, cached and immutable either way, just bigger. Silence it with `logging.getLogger("shiny_plotly").setLevel(logging.ERROR)`.
+- README: what each chart on a page costs to draw, and that Shiny suspends outputs hidden in an inactive `ui.nav_panel`, so charts in tabs are drawn when their tab is first opened rather than on load.
+### Changed
+- Every app serves plotly.min.js compressed and immutable from its first request, with no call of its own: importing `shiny_plotly` wraps `shiny.App.__init__`, so the route is added as each app is built, Core and Express alike. Until now it arrived with the first session, which is after the page load that opened that session had already pulled 4.9 MB from Shiny's static mount with no `Cache-Control` at all; the background compression now starts while the app is being built instead of when the first visitor is already waiting. `enable_compressed_plotly_js(app)` stays for an app constructed before the import, `SHINY_PLOTLY_NO_COMPRESS=1` still leaves Shiny's static serving untouched, and a failure to install the route is logged rather than raised: it can never keep an app from being built.
+- The templates behind `@render_plotly(theme=...)` travel once per session instead of once per figure. A template is about 6.5 kB, and every chart on a page usually shares one pair, so the first themed value carries the pair and every value afterwards names it by content hash: a page of ten charts sends about 13 kB of templates instead of 135 kB. Two outputs on different themes each send their own pair, a module shares the cache with the page around it, and a reconnecting browser gets a new session and so a fresh copy. A render with no session to cache against (a value produced outside a session, or Express's stub session before it connects) still carries its templates inline.
+## [0.3.2](https://github.com/rvben/shiny-plotly/compare/v0.3.1...v0.3.2) - 2026-08-20
+### Added
+- Three more forwardable events: `doubleclick` arrives as a running count of plot-area double-clicks (plotly hands the event no data; the count's change invalidates the input); `legendclick` and `legenddoubleclick` arrive as the clicked trace's `curve_number`, `expanded_index`, `name` and pre-toggle `visible`, plus `label` for trace types whose legend items are labels. The default toggle and isolate behaviors still happen.
+- `examples/streaming_app.py`: a live rolling window fed by `extend_traces`, with a pause switch and a window slider; a browser test drives the example file itself and proves the stream flows and pauses.
+- A live demo at https://rvben.github.io/shiny-plotly/: `examples/shinylive/app.py` grew into a two-tab showcase (a streaming figure, click and box-select events, a dark mode toggle), deployed to GitHub Pages by a workflow that builds the site from the checkout's own wheel (`make site`) and gates the deploy on a headless Chromium watching both tabs render (`make site-check`). The committed example still installs from PyPI, so `uvx shinylive export examples/shinylive site` keeps working as documented.
 ## [0.3.1](https://github.com/rvben/shiny-plotly/compare/v0.3.0...v0.3.1) - 2026-08-20
 ### Added

{shiny_plotly-0.3.1 → shiny_plotly-0.3.3}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: shiny-plotly
-Version: 0.3.1
+Version: 0.3.3
 Summary: Render plotly figures in Shiny for Python with plain plotly.js, without the shinywidgets layer.
 Project-URL: Homepage, https://github.com/rvben/shiny-plotly
 Project-URL: Repository, https://github.com/rvben/shiny-plotly
@@ -38,6 +38,8 @@ Render [plotly](https://plotly.com/python/) figures in [Shiny for Python](https:
 [![PyPI](https://img.shields.io/pypi/v/shiny-plotly)](https://pypi.org/project/shiny-plotly/)
 [![CI](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml/badge.svg)](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml)
+**[Try the live demo](https://rvben.github.io/shiny-plotly/)**: a streaming figure and forwarded plotly events, running entirely in your browser through shinylive.
 ```python
 from shiny_plotly import output_plotly, render_plotly
@@ -204,6 +206,12 @@ The rules mirror `output_widget`:
 Plotly alone re-measures a graph only on window resize. `shiny-plotly` ships a small helper script (`shiny-plotly.js`, loaded with every output) that observes each graph's container with a `ResizeObserver`, so a card that changes size without a window resize, for example when a sibling output renders below it, or when a sidebar collapses, re-lays the graph out. The same helper purges a graph once it leaves the document, which releases the window listener and layout state plotly would otherwise keep.
+### Many charts on one page
+Drawing a plotly figure costs the browser a fixed amount of main-thread work per graph, tens of milliseconds for a small one on a current desktop, and the browser draws them one after another. On a dashboard of a dozen charts that per-chart work, not the bytes on the wire, is what the first second is spent on, and it is plotly's own cost: the same figure drawn from shinywidgets or from a static `to_html` export costs the same.
+The lever is drawing fewer charts at once. Shiny suspends an output that is hidden, so charts inside `ui.navset_tab` panels or `ui.accordion` sections are not rendered at all until their panel is shown, and each panel then pays only for its own charts. Charts that must all be visible are better served by fewer, denser figures (subplots in one graph div) than by many small ones.
 ### Dark mode
 Plotly does not follow Bootstrap's color mode by itself. `theme="auto"` makes the figure follow it in the browser, with no server round-trip:
@@ -227,7 +235,40 @@ def sales():
 def sales(): ...
 ```
-How it works: both templates travel with the figure, their `paper_bgcolor` and `plot_bgcolor` made transparent so the card's own background shows through in both modes (backgrounds set on the figure's layout still win). The browser applies the mode's template before the first draw and switches it with `Plotly.relayout` when the mode flips, so the switch is instant and works even while the server is busy. The mode is `data-bs-theme` on `<html>`, which is what `ui.input_dark_mode()` maintains, or the OS `prefers-color-scheme` on a page without that attribute. A template the figure baked in through `layout.template` is dropped for themed outputs; use `theme=None` (the default) where the figure's own template should stand.
+How it works: both templates get their `paper_bgcolor` and `plot_bgcolor` made transparent, so the card's own background shows through in both modes (backgrounds set on the figure's layout still win). The browser applies the mode's template before the first draw and switches it with `Plotly.relayout` when the mode flips, so the switch is instant and works even while the server is busy. A template the figure baked in through `layout.template` is dropped for themed outputs; use `theme=None` (the default) where the figure's own template should stand.
+A template is about 6.5 kB of JSON, so it is sent **once per session** rather than once per render: the first themed value of a session brings the templates over their own message, and every value after it names them by content hash. A dashboard of twelve charts on one theme therefore pays for the theme once, and a re-render of a small figure is not dominated by a template that has not changed. Two outputs whose templates are equal share the copy automatically; nothing has to be declared.
+The mode comes from `data-bs-theme` on the **nearest ancestor of the output that sets one**. Usually that is `<html>`, which is what `ui.input_dark_mode()` maintains, and a page without the attribute anywhere follows the OS `prefers-color-scheme`. Because the lookup is per output, a container can theme the charts inside it against the rest of the page:
+```python
+ui.div(
+    ui.card(output_plotly("preview")),  # always dark, whatever the page does
+    data_bs_theme="dark",
+)
+```
+**Driving the mode yourself.** The attribute is the whole contract, so anything that sets it switches the charts: no shiny-plotly API is involved. To drive it from your own control, write it and the graphs follow on the next frame:
+```python
+app_ui = ui.page_fluid(
+    ui.input_switch("night", "Night mode"),
+    ui.tags.script("""
+        Shiny.addCustomMessageHandler("color-mode", function (message) {
+          document.documentElement.setAttribute("data-bs-theme", message.mode);
+        });
+    """),
+    ui.card(output_plotly("sales")),
+)
+@reactive.effect
+async def _apply_mode():
+    mode = "dark" if input.night() else "light"
+    await session.send_custom_message("color-mode", {"mode": mode})
+```
+The same holds in reverse: a page that already themes itself (a CSS framework, a cookie read at startup, `ui.input_dark_mode()` in a nav bar) needs nothing added, and a chart rendered while the attribute is already `dark` comes up dark on its first draw rather than flashing light first.
 The manual alternative, picking the template on the server, still works and is the way to vary anything beyond the template per mode. Give the dark mode switch an id and read it in the render function; flipping the switch then re-renders the figure through `Plotly.react`:
@@ -247,7 +288,7 @@ def sales():
 ### Events back to Shiny
-`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Four are available: `click`, `hover`, `selected` and `relayout`.
+`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Seven are available: `click`, `doubleclick`, `hover`, `selected`, `relayout`, `legendclick` and `legenddoubleclick`.
 ```python
 @render_plotly(events=("click", "selected"))
@@ -270,6 +311,9 @@ What arrives is plotly's own event data, cut to what serializes, the same way Da
 | `hover` | `{"points": [...]}` while over a point, `None` once the pointer leaves; debounced (100 ms) |
 | `selected` | `{"points": [...], "range": {"x": [..], "y": [..]}}` for a box, `lassoPoints` for a lasso; `None` after a double-click deselect; above `max_event_points` the points give way to `point_count` (below) |
 | `relayout` | plotly's relayout data as is: `{"xaxis.range[0]": ..., "xaxis.range[1]": ...}` after a zoom or pan, `{"xaxis.autorange": True, ...}` after a reset, `{"dragmode": "pan"}` from the mode bar, `{"autosize": True}` after a resize |
+| `doubleclick` | a running count of double-clicks on the plot area (the gesture that resets the axes); plotly hands the event no data, and the count's change is what invalidates the input |
+| `legendclick` | `{"curve_number": 1, "expanded_index": 1, "name": "beta", "visible": True}` for the trace whose legend item was clicked, `visible` as it stood before the click's toggle (`True` or `"legendonly"`); trace types whose legend items are labels (pie, funnelarea) add `label`; fires on every click, and the default toggle still happens |
+| `legenddoubleclick` | same value as `legendclick`; the default isolate-this-trace behavior still happens |
 Each point carries plotly's scalar fields for that trace type (`curveNumber`, `pointNumber`, `pointIndex`, `x`, `y`, `z`, `text`, `label`, `value`, `lat`, `lon`, ...) plus `customdata` (as a plain list, also when it was a numpy array), `bbox` and `pointNumbers` when present. `input.<id>_<event>()` raises a silent exception until the event has fired once, so check `is_set()` when the output should show something before that.
@@ -312,15 +356,14 @@ The value is never silently cut: `points` is a full list or `None`, and `point_c
 For anything else, `post_script` runs once, after the first figure is drawn, with `{plot_id}` replaced by the graph div's id. Re-renders go through `Plotly.react` into the same graph div, so handlers attached either way stay attached and are never stacked.
 ```python
-LEGEND_TO_INPUT = """
-document.getElementById('{plot_id}').on('plotly_legendclick', function (ev) {
-    Shiny.setInputValue('legend', ev.curveNumber, {priority: 'event'});
-    return true;  // let plotly toggle the trace as usual
+ANNOTATION_TO_INPUT = """
+document.getElementById('{plot_id}').on('plotly_clickannotation', function (ev) {
+    Shiny.setInputValue('annotation', ev.index, {priority: 'event'});
 });
 """
-@render_plotly(post_script=LEGEND_TO_INPUT)
+@render_plotly(post_script=ANNOTATION_TO_INPUT)
 def scatter(): ...
 ```
@@ -361,39 +404,38 @@ async def _highlight():
 The values go through plotly's encoder, so numpy arrays, pandas columns and datetimes work. The id is namespaced inside a module, like the output. An update reaches the figure that is drawn at that moment; one sent while the output has no figure (its first render is still running, it sits in a hidden tab, it shows an error or was emptied by `None`) is held and applied, in order, right after the output's next draw. A re-render replaces the figure, updates included, with what the render function returns: the server stays the source of truth, and a figure that should keep its streamed points across a re-render builds them in from server-side state.
+A runnable version of the streaming pattern, with a pause switch and a window slider, is `examples/streaming_app.py`.
 ### Lower level
 - `fig_to_ui(fig, div_id=None, *, height, width, figurewidget_margins, config, post_script)` returns a `TagList` holding the plotly.js dependency, the helper dependency and a `<div class="shiny-plotly">` that draws the figure with `Plotly.newPlot` (plotly's own `to_html` fragment). Use it from a plain `@render.ui` that composes a figure with other UI, or from any htmltools context. Each render draws a fresh graph; an output that is only a figure is better served by `render_plotly`.
 - `plotly_js()` is the `HTMLDependency` for plotly.js, served from the installed `plotly` wheel at `/lib/plotly-<version>/plotly.min.js`. Every `output_plotly` and every `fig_to_ui` fragment carries it, so it is optional; add it to the page UI when the first figure is inserted later (`ui.insert_ui`, a `@render.ui` that starts empty) and the bundle should load with the page.
 - `shiny_plotly_js()` is the helper's dependency. Every output and fragment carries it too.
 - `FIGUREWIDGET_MARGINS` is the `{"l": 16, "t": 32, "r": 16, "b": 16}` mapping.
-- `enable_compressed_plotly_js(app)` turns on compressed, immutable serving of plotly.js for a `shiny.App` before its first session (see below).
+- `enable_compressed_plotly_js(app)` adds compressed, immutable serving of plotly.js to a `shiny.App` explicitly. Every app built after `shiny_plotly` is imported already has it; this is the way in for one that was constructed before the import (see below).
 - `extend_traces`, `restyle` and `relayout` take an optional `session=` when called outside the current session's context.
 `render_plotly` needs `output_plotly`; it is an output binding, not a `render.ui`, so `ui.output_ui(id)` does not draw it.
 ### plotly.js on the wire
-Shiny serves HTML dependencies from a plain static mount: no compression, no `Cache-Control`. `plotly.min.js` is 4.9 MB, so once the first session of a process has rendered a figure, `shiny-plotly` adds a route in front of that mount for the bundle's exact path (`/lib/plotly-<version>/plotly.min.js`) that serves it pre-compressed (brotli when the `brotli` package is installed, gzip otherwise; 1.2 MB or 1.5 MB on the wire) with `Cache-Control: public, max-age=31536000, immutable`, `Vary: Accept-Encoding` and an `ETag` per encoding. The URL is keyed by the plotly version, so a browser fetches each version once. Compression runs once per process, in a background thread; until it has finished the route serves the raw file with the same headers.
+Shiny serves HTML dependencies from a plain static mount: no compression, no `Cache-Control`. `plotly.min.js` is 4.9 MB, so `shiny-plotly` adds a route in front of that mount for the bundle's exact path (`/lib/plotly-<version>/plotly.min.js`) that serves it pre-compressed (brotli when the `brotli` package is installed, gzip otherwise; 1.2 MB or 1.5 MB on the wire) with `Cache-Control: public, max-age=31536000, immutable`, `Vary: Accept-Encoding` and an `ETag` per encoding. The URL is keyed by the plotly version, so a browser fetches each version once. Compression runs once per process, in a background thread; until it has finished the route serves the raw file with the same headers.
 ```sh
 uv add "shiny-plotly[brotli]"  # optional: brotli instead of gzip
 ```
-Two things to know. The page load that starts the very first session of a process has already asked for the bundle before the route exists, so that one visitor gets the raw file from Shiny's mount; everyone after gets the compressed one. A Core app can close that gap by enabling the route as soon as the `App` exists:
+Without it the process logs one warning saying which encoding it is serving and what brotli would save, so a deployment can see it is shipping the larger bundle; `logging.getLogger("shiny_plotly").setLevel(logging.ERROR)` silences it.
-```python
-from shiny_plotly import enable_compressed_plotly_js
+The route asks nothing of the app. Importing `shiny_plotly` wraps `shiny.App.__init__`, so every app built afterwards has it, Core and Express alike, and the compression starts while the app is still being built rather than when someone first visits it. The timing is the whole point: the browser asks for plotly.js while the page is loading, well before the session that page opens exists, so a route that waited for a session would arrive one visitor too late, and that visitor would take 4.9 MB with no `Cache-Control` at all.
-app = App(app_ui, server)
-enable_compressed_plotly_js(app)
-```
+An app constructed before `shiny_plotly` is imported is the one case the constructor cannot reach; `enable_compressed_plotly_js(app)` adds the route to it, and returns `False` if it is already there.
-And if a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment; `enable_compressed_plotly_js` then returns `False` and adds nothing.
+If a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment: no route is added, and `enable_compressed_plotly_js` returns `False`.
 ### Shinylive
-Apps using `shiny-plotly` run under [Shinylive](https://shiny.posit.co/py/get-started/shinylive.html) (pyodide in the browser) as well; list `shiny-plotly` in the app's `requirements.txt` next to `plotly`. There is no HTTP server in the browser and pyodide cannot start threads, so the compression route above stands down under pyodide (`enable_compressed_plotly_js` returns `False`); everything else, rendering, events, in-place updates and themes, is browser-side already. Verified against a real `shinylive export`; `examples/shinylive/` is a ready-to-export app.
+Apps using `shiny-plotly` run under [Shinylive](https://shiny.posit.co/py/get-started/shinylive.html) (pyodide in the browser) as well; list `shiny-plotly` in the app's `requirements.txt` next to `plotly`. There is no HTTP server in the browser and pyodide cannot start threads, so the compression route above stands down under pyodide (`enable_compressed_plotly_js` returns `False`); everything else, rendering, events, in-place updates and themes, is browser-side already. Verified against a real `shinylive export`; `examples/shinylive/` is a ready-to-export app, and its deployed copy is the [live demo](https://rvben.github.io/shiny-plotly/). The Pages workflow builds that demo from the current checkout's wheel (`make site`) and deploys only after a headless Chromium has watched both tabs render (`make site-check`).
 ## Examples
@@ -402,6 +444,7 @@ uv run --with shiny-plotly shiny run examples/core_app.py     # fill, margins, a
 uv run --with shiny-plotly shiny run examples/express_app.py  # the Express flavor
 uv run --with shiny-plotly shiny run examples/dark_app.py     # theme="auto" and a custom (light, dark) pair
 uv run --with shiny-plotly shiny run examples/events_app.py   # box selections over a 50k-point trace
+uv run --with shiny-plotly shiny run examples/streaming_app.py # a rolling window fed by extend_traces
 uvx shinylive export examples/shinylive site                  # the same package, running in the browser
 ```

{shiny_plotly-0.3.1 → shiny_plotly-0.3.3}/README.md RENAMED Viewed

@@ -7,6 +7,8 @@ Render [plotly](https://plotly.com/python/) figures in [Shiny for Python](https:
 [![PyPI](https://img.shields.io/pypi/v/shiny-plotly)](https://pypi.org/project/shiny-plotly/)
 [![CI](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml/badge.svg)](https://github.com/rvben/shiny-plotly/actions/workflows/ci.yml)
+**[Try the live demo](https://rvben.github.io/shiny-plotly/)**: a streaming figure and forwarded plotly events, running entirely in your browser through shinylive.
 ```python
 from shiny_plotly import output_plotly, render_plotly
@@ -173,6 +175,12 @@ The rules mirror `output_widget`:
 Plotly alone re-measures a graph only on window resize. `shiny-plotly` ships a small helper script (`shiny-plotly.js`, loaded with every output) that observes each graph's container with a `ResizeObserver`, so a card that changes size without a window resize, for example when a sibling output renders below it, or when a sidebar collapses, re-lays the graph out. The same helper purges a graph once it leaves the document, which releases the window listener and layout state plotly would otherwise keep.
+### Many charts on one page
+Drawing a plotly figure costs the browser a fixed amount of main-thread work per graph, tens of milliseconds for a small one on a current desktop, and the browser draws them one after another. On a dashboard of a dozen charts that per-chart work, not the bytes on the wire, is what the first second is spent on, and it is plotly's own cost: the same figure drawn from shinywidgets or from a static `to_html` export costs the same.
+The lever is drawing fewer charts at once. Shiny suspends an output that is hidden, so charts inside `ui.navset_tab` panels or `ui.accordion` sections are not rendered at all until their panel is shown, and each panel then pays only for its own charts. Charts that must all be visible are better served by fewer, denser figures (subplots in one graph div) than by many small ones.
 ### Dark mode
 Plotly does not follow Bootstrap's color mode by itself. `theme="auto"` makes the figure follow it in the browser, with no server round-trip:
@@ -196,7 +204,40 @@ def sales():
 def sales(): ...
 ```
-How it works: both templates travel with the figure, their `paper_bgcolor` and `plot_bgcolor` made transparent so the card's own background shows through in both modes (backgrounds set on the figure's layout still win). The browser applies the mode's template before the first draw and switches it with `Plotly.relayout` when the mode flips, so the switch is instant and works even while the server is busy. The mode is `data-bs-theme` on `<html>`, which is what `ui.input_dark_mode()` maintains, or the OS `prefers-color-scheme` on a page without that attribute. A template the figure baked in through `layout.template` is dropped for themed outputs; use `theme=None` (the default) where the figure's own template should stand.
+How it works: both templates get their `paper_bgcolor` and `plot_bgcolor` made transparent, so the card's own background shows through in both modes (backgrounds set on the figure's layout still win). The browser applies the mode's template before the first draw and switches it with `Plotly.relayout` when the mode flips, so the switch is instant and works even while the server is busy. A template the figure baked in through `layout.template` is dropped for themed outputs; use `theme=None` (the default) where the figure's own template should stand.
+A template is about 6.5 kB of JSON, so it is sent **once per session** rather than once per render: the first themed value of a session brings the templates over their own message, and every value after it names them by content hash. A dashboard of twelve charts on one theme therefore pays for the theme once, and a re-render of a small figure is not dominated by a template that has not changed. Two outputs whose templates are equal share the copy automatically; nothing has to be declared.
+The mode comes from `data-bs-theme` on the **nearest ancestor of the output that sets one**. Usually that is `<html>`, which is what `ui.input_dark_mode()` maintains, and a page without the attribute anywhere follows the OS `prefers-color-scheme`. Because the lookup is per output, a container can theme the charts inside it against the rest of the page:
+```python
+ui.div(
+    ui.card(output_plotly("preview")),  # always dark, whatever the page does
+    data_bs_theme="dark",
+)
+```
+**Driving the mode yourself.** The attribute is the whole contract, so anything that sets it switches the charts: no shiny-plotly API is involved. To drive it from your own control, write it and the graphs follow on the next frame:
+```python
+app_ui = ui.page_fluid(
+    ui.input_switch("night", "Night mode"),
+    ui.tags.script("""
+        Shiny.addCustomMessageHandler("color-mode", function (message) {
+          document.documentElement.setAttribute("data-bs-theme", message.mode);
+        });
+    """),
+    ui.card(output_plotly("sales")),
+)
+@reactive.effect
+async def _apply_mode():
+    mode = "dark" if input.night() else "light"
+    await session.send_custom_message("color-mode", {"mode": mode})
+```
+The same holds in reverse: a page that already themes itself (a CSS framework, a cookie read at startup, `ui.input_dark_mode()` in a nav bar) needs nothing added, and a chart rendered while the attribute is already `dark` comes up dark on its first draw rather than flashing light first.
 The manual alternative, picking the template on the server, still works and is the way to vary anything beyond the template per mode. Give the dark mode switch an id and read it in the render function; flipping the switch then re-renders the figure through `Plotly.react`:
@@ -216,7 +257,7 @@ def sales():
 ### Events back to Shiny
-`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Four are available: `click`, `hover`, `selected` and `relayout`.
+`events=` names the plotly events to forward; each arrives as `input.<id>_<event>`, namespaced like the output inside a module. Seven are available: `click`, `doubleclick`, `hover`, `selected`, `relayout`, `legendclick` and `legenddoubleclick`.
 ```python
 @render_plotly(events=("click", "selected"))
@@ -239,6 +280,9 @@ What arrives is plotly's own event data, cut to what serializes, the same way Da
 | `hover` | `{"points": [...]}` while over a point, `None` once the pointer leaves; debounced (100 ms) |
 | `selected` | `{"points": [...], "range": {"x": [..], "y": [..]}}` for a box, `lassoPoints` for a lasso; `None` after a double-click deselect; above `max_event_points` the points give way to `point_count` (below) |
 | `relayout` | plotly's relayout data as is: `{"xaxis.range[0]": ..., "xaxis.range[1]": ...}` after a zoom or pan, `{"xaxis.autorange": True, ...}` after a reset, `{"dragmode": "pan"}` from the mode bar, `{"autosize": True}` after a resize |
+| `doubleclick` | a running count of double-clicks on the plot area (the gesture that resets the axes); plotly hands the event no data, and the count's change is what invalidates the input |
+| `legendclick` | `{"curve_number": 1, "expanded_index": 1, "name": "beta", "visible": True}` for the trace whose legend item was clicked, `visible` as it stood before the click's toggle (`True` or `"legendonly"`); trace types whose legend items are labels (pie, funnelarea) add `label`; fires on every click, and the default toggle still happens |
+| `legenddoubleclick` | same value as `legendclick`; the default isolate-this-trace behavior still happens |
 Each point carries plotly's scalar fields for that trace type (`curveNumber`, `pointNumber`, `pointIndex`, `x`, `y`, `z`, `text`, `label`, `value`, `lat`, `lon`, ...) plus `customdata` (as a plain list, also when it was a numpy array), `bbox` and `pointNumbers` when present. `input.<id>_<event>()` raises a silent exception until the event has fired once, so check `is_set()` when the output should show something before that.
@@ -281,15 +325,14 @@ The value is never silently cut: `points` is a full list or `None`, and `point_c
 For anything else, `post_script` runs once, after the first figure is drawn, with `{plot_id}` replaced by the graph div's id. Re-renders go through `Plotly.react` into the same graph div, so handlers attached either way stay attached and are never stacked.
 ```python
-LEGEND_TO_INPUT = """
-document.getElementById('{plot_id}').on('plotly_legendclick', function (ev) {
-    Shiny.setInputValue('legend', ev.curveNumber, {priority: 'event'});
-    return true;  // let plotly toggle the trace as usual
+ANNOTATION_TO_INPUT = """
+document.getElementById('{plot_id}').on('plotly_clickannotation', function (ev) {
+    Shiny.setInputValue('annotation', ev.index, {priority: 'event'});
 });
 """
-@render_plotly(post_script=LEGEND_TO_INPUT)
+@render_plotly(post_script=ANNOTATION_TO_INPUT)
 def scatter(): ...
 ```
@@ -330,39 +373,38 @@ async def _highlight():
 The values go through plotly's encoder, so numpy arrays, pandas columns and datetimes work. The id is namespaced inside a module, like the output. An update reaches the figure that is drawn at that moment; one sent while the output has no figure (its first render is still running, it sits in a hidden tab, it shows an error or was emptied by `None`) is held and applied, in order, right after the output's next draw. A re-render replaces the figure, updates included, with what the render function returns: the server stays the source of truth, and a figure that should keep its streamed points across a re-render builds them in from server-side state.
+A runnable version of the streaming pattern, with a pause switch and a window slider, is `examples/streaming_app.py`.
 ### Lower level
 - `fig_to_ui(fig, div_id=None, *, height, width, figurewidget_margins, config, post_script)` returns a `TagList` holding the plotly.js dependency, the helper dependency and a `<div class="shiny-plotly">` that draws the figure with `Plotly.newPlot` (plotly's own `to_html` fragment). Use it from a plain `@render.ui` that composes a figure with other UI, or from any htmltools context. Each render draws a fresh graph; an output that is only a figure is better served by `render_plotly`.
 - `plotly_js()` is the `HTMLDependency` for plotly.js, served from the installed `plotly` wheel at `/lib/plotly-<version>/plotly.min.js`. Every `output_plotly` and every `fig_to_ui` fragment carries it, so it is optional; add it to the page UI when the first figure is inserted later (`ui.insert_ui`, a `@render.ui` that starts empty) and the bundle should load with the page.
 - `shiny_plotly_js()` is the helper's dependency. Every output and fragment carries it too.
 - `FIGUREWIDGET_MARGINS` is the `{"l": 16, "t": 32, "r": 16, "b": 16}` mapping.
-- `enable_compressed_plotly_js(app)` turns on compressed, immutable serving of plotly.js for a `shiny.App` before its first session (see below).
+- `enable_compressed_plotly_js(app)` adds compressed, immutable serving of plotly.js to a `shiny.App` explicitly. Every app built after `shiny_plotly` is imported already has it; this is the way in for one that was constructed before the import (see below).
 - `extend_traces`, `restyle` and `relayout` take an optional `session=` when called outside the current session's context.
 `render_plotly` needs `output_plotly`; it is an output binding, not a `render.ui`, so `ui.output_ui(id)` does not draw it.
 ### plotly.js on the wire
-Shiny serves HTML dependencies from a plain static mount: no compression, no `Cache-Control`. `plotly.min.js` is 4.9 MB, so once the first session of a process has rendered a figure, `shiny-plotly` adds a route in front of that mount for the bundle's exact path (`/lib/plotly-<version>/plotly.min.js`) that serves it pre-compressed (brotli when the `brotli` package is installed, gzip otherwise; 1.2 MB or 1.5 MB on the wire) with `Cache-Control: public, max-age=31536000, immutable`, `Vary: Accept-Encoding` and an `ETag` per encoding. The URL is keyed by the plotly version, so a browser fetches each version once. Compression runs once per process, in a background thread; until it has finished the route serves the raw file with the same headers.
+Shiny serves HTML dependencies from a plain static mount: no compression, no `Cache-Control`. `plotly.min.js` is 4.9 MB, so `shiny-plotly` adds a route in front of that mount for the bundle's exact path (`/lib/plotly-<version>/plotly.min.js`) that serves it pre-compressed (brotli when the `brotli` package is installed, gzip otherwise; 1.2 MB or 1.5 MB on the wire) with `Cache-Control: public, max-age=31536000, immutable`, `Vary: Accept-Encoding` and an `ETag` per encoding. The URL is keyed by the plotly version, so a browser fetches each version once. Compression runs once per process, in a background thread; until it has finished the route serves the raw file with the same headers.
 ```sh
 uv add "shiny-plotly[brotli]"  # optional: brotli instead of gzip
 ```
-Two things to know. The page load that starts the very first session of a process has already asked for the bundle before the route exists, so that one visitor gets the raw file from Shiny's mount; everyone after gets the compressed one. A Core app can close that gap by enabling the route as soon as the `App` exists:
+Without it the process logs one warning saying which encoding it is serving and what brotli would save, so a deployment can see it is shipping the larger bundle; `logging.getLogger("shiny_plotly").setLevel(logging.ERROR)` silences it.
-```python
-from shiny_plotly import enable_compressed_plotly_js
+The route asks nothing of the app. Importing `shiny_plotly` wraps `shiny.App.__init__`, so every app built afterwards has it, Core and Express alike, and the compression starts while the app is still being built rather than when someone first visits it. The timing is the whole point: the browser asks for plotly.js while the page is loading, well before the session that page opens exists, so a route that waited for a session would arrive one visitor too late, and that visitor would take 4.9 MB with no `Cache-Control` at all.
-app = App(app_ui, server)
-enable_compressed_plotly_js(app)
-```
+An app constructed before `shiny_plotly` is imported is the one case the constructor cannot reach; `enable_compressed_plotly_js(app)` adds the route to it, and returns `False` if it is already there.
-And if a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment; `enable_compressed_plotly_js` then returns `False` and adds nothing.
+If a reverse proxy in front of the app does its own compression and caching, or you want Shiny's static serving untouched for any reason, set `SHINY_PLOTLY_NO_COMPRESS=1` in the app's environment: no route is added, and `enable_compressed_plotly_js` returns `False`.
 ### Shinylive
-Apps using `shiny-plotly` run under [Shinylive](https://shiny.posit.co/py/get-started/shinylive.html) (pyodide in the browser) as well; list `shiny-plotly` in the app's `requirements.txt` next to `plotly`. There is no HTTP server in the browser and pyodide cannot start threads, so the compression route above stands down under pyodide (`enable_compressed_plotly_js` returns `False`); everything else, rendering, events, in-place updates and themes, is browser-side already. Verified against a real `shinylive export`; `examples/shinylive/` is a ready-to-export app.
+Apps using `shiny-plotly` run under [Shinylive](https://shiny.posit.co/py/get-started/shinylive.html) (pyodide in the browser) as well; list `shiny-plotly` in the app's `requirements.txt` next to `plotly`. There is no HTTP server in the browser and pyodide cannot start threads, so the compression route above stands down under pyodide (`enable_compressed_plotly_js` returns `False`); everything else, rendering, events, in-place updates and themes, is browser-side already. Verified against a real `shinylive export`; `examples/shinylive/` is a ready-to-export app, and its deployed copy is the [live demo](https://rvben.github.io/shiny-plotly/). The Pages workflow builds that demo from the current checkout's wheel (`make site`) and deploys only after a headless Chromium has watched both tabs render (`make site-check`).
 ## Examples
@@ -371,6 +413,7 @@ uv run --with shiny-plotly shiny run examples/core_app.py     # fill, margins, a
 uv run --with shiny-plotly shiny run examples/express_app.py  # the Express flavor
 uv run --with shiny-plotly shiny run examples/dark_app.py     # theme="auto" and a custom (light, dark) pair
 uv run --with shiny-plotly shiny run examples/events_app.py   # box selections over a 50k-point trace
+uv run --with shiny-plotly shiny run examples/streaming_app.py # a rolling window fed by extend_traces
 uvx shinylive export examples/shinylive site                  # the same package, running in the browser
 ```

{shiny_plotly-0.3.1 → shiny_plotly-0.3.3}/examples/core_app.py RENAMED Viewed

@@ -9,7 +9,7 @@ from itertools import accumulate
 import plotly.graph_objects as go
 from shiny import App, Inputs, Outputs, Session, reactive, render, ui
-from shiny_plotly import enable_compressed_plotly_js, extend_traces, output_plotly, render_plotly
+from shiny_plotly import extend_traces, output_plotly, render_plotly
 app_ui = ui.page_sidebar(
     ui.sidebar(
@@ -99,6 +99,3 @@ def server(input: Inputs, output: Outputs, session: Session):
 app = App(app_ui, server)
-# Optional: serve plotly.js compressed from the very first request instead of from the
-# first session on (see README, "plotly.js on the wire").
-enable_compressed_plotly_js(app)

shiny_plotly-0.3.3/examples/shinylive/app.py ADDED Viewed

@@ -0,0 +1,114 @@
+"""The live demo behind https://rvben.github.io/shiny-plotly/, running in the browser.
+The whole app runs in the browser via pyodide: no server. Two tabs show the package's
+two sides. Stream draws one empty figure and feeds it through ``extend_traces``, one
+small message per tick, no re-render. Explore forwards plotly's click and box-select
+events to Shiny inputs. Both figures follow the page's color mode via ``theme="auto"``
+and the toggle in the corner.
+Export this directory to a static site and serve it:
+    uvx shinylive export examples/shinylive site
+    python -m http.server 8000 -d site
+That installs the released package from PyPI (requirements.txt); the deployed demo is
+built by ``make site``, which installs the wheel from the current checkout instead.
+"""
+import random
+from datetime import datetime
+import plotly.graph_objects as go
+from shiny import App, Inputs, Outputs, Session, reactive, render, ui
+from shiny_plotly import extend_traces, output_plotly, render_plotly
+TICK_SECONDS = 0.5
+CLUSTERS = {"alpha": (0.0, 0.0), "beta": (3.0, 2.0), "gamma": (1.0, 4.0)}
+app_ui = ui.page_fillable(
+    ui.div(
+        ui.tags.b("shiny-plotly"),
+        ui.span("plotly figures in Shiny for Python, without shinywidgets", class_="text-muted"),
+        ui.div(ui.input_dark_mode(), class_="ms-auto"),
+        class_="d-flex align-items-center gap-3",
+    ),
+    ui.navset_card_underline(
+        ui.nav_panel(
+            "Stream",
+            ui.layout_columns(
+                ui.input_switch("run", "Stream", value=True),
+                ui.input_slider("window", "Window (points)", min=50, max=500, value=200, step=50),
+                col_widths=(3, 9),
+            ),
+            output_plotly("stream"),
+        ),
+        ui.nav_panel(
+            "Explore",
+            output_plotly("explore"),
+            ui.layout_columns(ui.output_text("clicked"), ui.output_text("picked")),
+        ),
+    ),
+    title="shiny-plotly demo",
+)
+def server(input: Inputs, output: Outputs, session: Session):
+    # Per-session: each visitor gets their own stream.
+    state = {"a": 20.0, "b": 50.0}
+    @render_plotly(theme="auto")
+    def stream():
+        fig = go.Figure(
+            [
+                go.Scatter(x=[], y=[], mode="lines", name="sensor a"),
+                go.Scatter(x=[], y=[], mode="lines", name="sensor b"),
+            ]
+        )
+        return fig.update_layout(uirevision="keep")
+    @reactive.effect
+    async def _tick():
+        reactive.invalidate_later(TICK_SECONDS)
+        if not input.run():
+            return
+        now = datetime.now()
+        state["a"] += random.uniform(-1.0, 1.0)
+        state["b"] += random.uniform(-2.0, 2.0)
+        # One column of new values per trace; max_points keeps the rolling window.
+        await extend_traces(
+            "stream",
+            {"x": [[now], [now]], "y": [[state["a"]], [state["b"]]]},
+            max_points=input.window(),
+        )
+    @render_plotly(theme="auto", events=("click", "selected"))
+    def explore():
+        rng = random.Random(7)
+        fig = go.Figure()
+        for name, (cx, cy) in CLUSTERS.items():
+            fig.add_scatter(
+                x=[cx + rng.gauss(0, 0.8) for _ in range(40)],
+                y=[cy + rng.gauss(0, 0.8) for _ in range(40)],
+                mode="markers",
+                name=name,
+            )
+        # Select mode from the start, so a plain drag is a box selection.
+        return fig.update_layout(dragmode="select")
+    @render.text
+    def clicked():
+        if not input.explore_click.is_set():
+            return "Click a point."
+        point = input.explore_click()["points"][0]
+        name = list(CLUSTERS)[point["curveNumber"]]
+        return f"Clicked {name} at ({point['x']:.2f}, {point['y']:.2f})."
+    @render.text
+    def picked():
+        if not input.explore_selected.is_set() or input.explore_selected() is None:
+            return "Drag a box to select points."
+        return f"{len(input.explore_selected()['points'])} points selected."
+app = App(app_ui, server)

shiny_plotly-0.3.3/examples/streaming_app.py ADDED Viewed

@@ -0,0 +1,69 @@
+"""Streaming example: a live rolling window fed by extend_traces, no re-render.
+The figure is drawn once, empty; every point after that arrives through
+``extend_traces``, which appends in the browser and drops the oldest points past the
+window. Nothing re-renders, so the stream costs one small message per tick and a zoom
+or pan the user dragged stays where they put it. The switch pauses the stream; the
+slider resizes the window from the next tick on.
+Run with:  uv run --with shiny-plotly shiny run examples/streaming_app.py
+"""
+import random
+from datetime import datetime
+import plotly.graph_objects as go
+from shiny import App, Inputs, Outputs, Session, reactive, ui
+from shiny_plotly import extend_traces, output_plotly, render_plotly
+TICK_SECONDS = 0.25
+app_ui = ui.page_fillable(
+    ui.layout_columns(
+        ui.input_switch("run", "Stream", value=True),
+        ui.input_slider("window", "Window (points)", min=50, max=1000, value=300, step=50),
+        col_widths=(3, 9),
+    ),
+    ui.card(
+        ui.card_header("Two sensors, one point per tick"),
+        output_plotly("stream"),
+        full_screen=True,
+    ),
+    title="shiny-plotly streaming",
+)
+def server(input: Inputs, output: Outputs, session: Session):
+    # Per-session: each visitor gets their own stream.
+    state = {"a": 20.0, "b": 50.0}
+    @render_plotly(theme="auto")
+    def stream():
+        fig = go.Figure(
+            [
+                go.Scatter(x=[], y=[], mode="lines", name="sensor a"),
+                go.Scatter(x=[], y=[], mode="lines", name="sensor b"),
+            ]
+        )
+        return fig.update_layout(uirevision="keep")
+    @reactive.effect
+    async def _tick():
+        reactive.invalidate_later(TICK_SECONDS)
+        if not input.run():
+            return
+        now = datetime.now()
+        state["a"] += random.uniform(-1.0, 1.0)
+        state["b"] += random.uniform(-2.0, 2.0)
+        # One column of new values per trace; max_points keeps the rolling window. Sent
+        # while the first (empty) figure is still on its way, the update is held in the
+        # browser and applied right after the draw, so nothing is lost at startup.
+        await extend_traces(
+            "stream",
+            {"x": [[now], [now]], "y": [[state["a"]], [state["b"]]]},
+            max_points=input.window(),
+        )
+app = App(app_ui, server)

{shiny_plotly-0.3.1 → shiny_plotly-0.3.3}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 [project]
 name = "shiny-plotly"
-version = "0.3.1"
+version = "0.3.3"
 description = "Render plotly figures in Shiny for Python with plain plotly.js, without the shinywidgets layer."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -58,6 +58,7 @@ dev = [
   "pytest-playwright>=0.9.0",
   "numpy>=1.26",
   "brotli>=1.1",
+  "shinylive-check>=0.1.0",
 ]
 # uv's default cache keys for a local build are the metadata files only, so a source-only
@@ -85,7 +86,7 @@ target-version = "py310"
 select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
 [tool.pyright]
-include = ["src", "tests", "examples", "bench"]
+include = ["src", "tests", "examples", "bench", "tools"]
 pythonVersion = "3.10"
 typeCheckingMode = "standard"

{shiny_plotly-0.3.1 → shiny_plotly-0.3.3}/src/shiny_plotly/__init__.py RENAMED Viewed

@@ -3,7 +3,7 @@
 from ._deps import __version__, plotly_js, shiny_plotly_js
 from ._html import FIGUREWIDGET_MARGINS, fig_to_ui
 from ._render import DEFAULT_MAX_EVENT_POINTS, output_plotly, render_plotly
-from ._serve import enable_compressed_plotly_js
+from ._serve import enable_compressed_plotly_js, enable_for_new_apps
 from ._update import (
     add_traces,
     delete_traces,
@@ -32,3 +32,8 @@ __all__ = (
     "shiny_plotly_js",
     "update",
 )
+# From here on every app serves plotly.min.js compressed and immutable, from its first
+# request, with no call of its own; the compression starts while the app is being built.
+# SHINY_PLOTLY_NO_COMPRESS=1 in the environment leaves Shiny's static serving untouched.
+enable_for_new_apps()

shiny-plotly 0.3.1__tar.gz → 0.3.3__tar.gz

shiny-plotly 0.3.1tar.gz → 0.3.3tar.gz