Skip to content

Commit fa4f243

Browse files
committed
Merge remote-tracking branch 'origin/dev' into master-4.5.0
2 parents c673687 + 00b8ed6 commit fa4f243

51 files changed

Lines changed: 711 additions & 144 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.ai/ARCHITECTURE.md‎

Lines changed: 44 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -727,7 +727,7 @@ Special handling for Colab:
727727
- `prevent_initial_callbacks` - Skip callbacks on load (default: `False`)
728728
- `background_callback_manager` - DiskcacheManager or CeleryManager
729729
- `on_error` - Global callback error handler
730-
- `shared_storage` - Cross-process state + pub/sub backend (default: `LocalSharedStorage`). Pass `None` to disable, or a `BaseSharedStorage` subclass/instance to swap. See [Shared Storage](#shared-storage).
730+
- `shared_storage` - Cross-process state + pub/sub backend (default: off). Pass `LocalSharedStorage` to enable, or a `BaseSharedStorage` subclass/instance to swap. See [Shared Storage](#shared-storage).
731731

732732
**WebSocket Callbacks:**
733733
- `websocket_callbacks` - Enable WebSocket for all callbacks (default: `False`). Requires FastAPI backend.
@@ -820,7 +820,9 @@ channel. Unlike `dcc.Store` (which lives in the browser), shared storage lives
820820
on the server and lets callbacks running in different workers see the same keys
821821
and topics without standing up an external service like Redis.
822822

823-
Enabled by default on every app. It starts lazily on first use, so it costs
823+
Opt-in: off unless the app passes `shared_storage=` or `DASH_SHARED_STORAGE`
824+
is set, so existing deployments do not grow a socket owner or a streaming
825+
downlink on upgrade. Once enabled it starts lazily on first use, so it costs
824826
nothing until touched.
825827

826828
### Accessing It
@@ -836,13 +838,21 @@ def handler(n):
836838
return store.get("clicks", 0)
837839

838840
# Or off the app directly:
839-
app = dash.Dash()
841+
app = dash.Dash(shared_storage=dash.LocalSharedStorage)
840842
app.shared_storage.set("key", {"any": "json-compatible value"})
841843
```
842844

843845
Values (and published messages) must be **JSON-compatible** — dict / list / str
844846
/ int / float / bool / None — the same constraint as `dcc.Store` and callback
845-
outputs. Messages are encoded with `msgspec` (msgpack), a hard dependency.
847+
outputs. Messages are encoded with `msgspec` (msgpack) from the
848+
`dash[shared_storage]` extra (also pulled in by `dash[diskcache]` and
849+
`dash[redis]`). Without it, `LocalSharedStorage` in `"memory"` mode still works
850+
and its socket transport falls back to stdlib JSON (both ends run the same
851+
install, so they always agree). JSON turns non-string dict keys into strings and
852+
cannot carry `bytes`, so keep values strictly JSON-shaped. Everything that
853+
writes encoded bytes somewhere lasting (the persistent modes, Diskcache, Redis)
854+
raises an `ImportError` naming the extra that brings it instead, so a stored
855+
format never depends on what happens to be installed.
846856

847857
### API
848858

@@ -895,7 +905,7 @@ more than one container/pod (see [Deployment Topology](#deployment-topology-and-
895905
896906
| Backend | Backing store | Reaches | Extra |
897907
|---------|---------------|---------|-------|
898-
| `LocalSharedStorage` *(default)* | in-memory, owner-elected socket | one **container** (all its workers) | none |
908+
| `LocalSharedStorage` | in-memory, owner-elected socket | one **container** (all its workers) | none (`dash[shared_storage]` for the persistent modes) |
899909
| `DiskcacheSharedStorage` | a `diskcache.Cache` | one **host** (all processes sharing the dir) | `dash[diskcache]` |
900910
| `RedisSharedStorage` | Redis (Streams for pub/sub) | **any** process/container/pod | `dash[redis]` |
901911
@@ -909,14 +919,21 @@ from dash._shared_storage import (
909919
LocalSharedStorage, DiskcacheSharedStorage, RedisSharedStorage,
910920
)
911921
912-
Dash(shared_storage=LocalSharedStorage) # default
922+
Dash() # disabled (default)
923+
Dash(shared_storage=LocalSharedStorage)
913924
Dash(shared_storage=DiskcacheSharedStorage(directory="/tmp/ss"))
914925
Dash(shared_storage=RedisSharedStorage(url="redis://host:6379"))
915-
Dash(shared_storage=None) # disabled
916926
```
917927
918928
When disabled, accessing `app.shared_storage` / `dash.ctx.shared_storage`
919-
raises `SharedStorageError`.
929+
raises `SharedStorageError`. Streaming callbacks over HTTP need it: server setup
930+
raises `StreamCallbackError` naming them (`_validate.validate_stream_callbacks`),
931+
so an app cannot stream on a fallback locally and then break once deployed.
932+
WebSocket streaming callbacks (`websocket_callbacks=True` or `websocket=True`
933+
on a backend with `websocket_capability`, i.e. FastAPI or Quart) send frames on
934+
the socket and do not need it; on Flask those flags change nothing and the check
935+
still applies. Browsers without `SharedWorker` do not use the WebSocket
936+
transport and stream over HTTP, one connection per stream.
920937
921938
**`LocalSharedStorage`** — in-memory, no external service. On first use every
922939
worker races to become the single **owner** for the machine by binding a stable
@@ -993,7 +1010,7 @@ subscriptions likewise poll without blocking and sleep on the loop.
9931010
9941011
### Deployment Topology and Shared Storage
9951012
996-
The default `LocalSharedStorage` is **per-container**: its socket/loopback
1013+
`LocalSharedStorage` is **per-container**: its socket/loopback
9971014
election only reaches processes in the same network + filesystem namespace.
9981015
9991016
- **Single process / single pod** (e.g. Plotly Cloud apps): fine — one owner,
@@ -1009,16 +1026,16 @@ election only reaches processes in the same network + filesystem namespace.
10091026
A hosting platform can switch the backend without editing the app through
10101027
`DASH_SHARED_STORAGE` (`_shared_storage/_env.py`), read only when the app did
10111028
not pass `shared_storage=` (the default is a sentinel, so an explicit argument,
1012-
`None` included, always wins): `local`, `none`, `diskcache:///abs/path`, or a
1013-
`redis://` / `rediss://` URL. A `key_prefix` query parameter on the Redis URL
1014-
(`redis://host/0?key_prefix=myapp`) sets `RedisSharedStorage(key_prefix=)` and
1015-
is stripped before the URL reaches redis-py; the diskcache path is
1016-
percent-decoded. `cluster://` is reserved and raises; anything else raises
1017-
`InvalidConfig` at construction, without echoing the value (it can hold
1018-
credentials). The value becomes a zero-argument
1019-
factory, so nothing is built or connected until `app.shared_storage` is first
1020-
read, but a missing extra (`dash[redis]`, `dash[diskcache]`) fails at
1021-
construction with the backend's own `ImportError`.
1029+
`None` included, always wins): `local`, `none` (same as unset or empty),
1030+
`diskcache:///abs/path`, or a `redis://` / `rediss://` URL. A `key_prefix` query
1031+
parameter on the Redis URL (`redis://host/0?key_prefix=myapp`) sets
1032+
`RedisSharedStorage(key_prefix=)` and is stripped before the URL reaches
1033+
redis-py; the diskcache path is percent-decoded. `cluster://` is reserved and
1034+
raises; anything else raises `InvalidConfig` at construction, without echoing
1035+
the value (it can hold credentials). The value becomes a zero-argument factory,
1036+
so nothing is built or connected until `app.shared_storage` is first read, but a
1037+
missing extra (`dash[redis]`, `dash[diskcache]`, `dash[shared_storage]`) fails
1038+
at construction with the backend's own `ImportError`.
10221039
10231040
### Custom and Out-of-Tree Backends
10241041
@@ -1039,12 +1056,13 @@ and returns a `Subscription` (`__iter__` / `__aiter__` / `close`) that raises
10391056
top-level `dash`; the poll-loop helpers (`PollResult`, the polling subscription)
10401057
are private and not part of the contract.
10411058
1042-
Core only ships backends whose dependency is already a Dash extra (`msgspec`
1043-
base; `dash[diskcache]`; `dash[redis]`). Anything needing a heavier dependency
1044-
belongs **out of tree** behind this same interface — e.g. a Postgres backend
1045-
(`LISTEN`/`NOTIFY` for push pub/sub + a table for KV and replay) lives in its own
1046-
package so a `psycopg` connection is never pulled into Dash core. It plugs in the
1047-
same way as a built-in: `Dash(shared_storage=PostgresSharedStorage(...))`.
1059+
Core only ships backends whose dependency is already a Dash extra
1060+
(`dash[shared_storage]`; `dash[diskcache]`; `dash[redis]`). Anything needing a
1061+
heavier dependency belongs **out of tree** behind this same interface — e.g. a
1062+
Postgres backend (`LISTEN`/`NOTIFY` for push pub/sub + a table for KV and
1063+
replay) lives in its own package so a `psycopg` connection is never pulled into
1064+
Dash core. It plugs in the same way as a built-in:
1065+
`Dash(shared_storage=PostgresSharedStorage(...))`.
10481066
10491067
### Module Layout
10501068
@@ -1412,7 +1430,7 @@ with an empty result on the terminal frame.
14121430
14131431
### Multiplexed downlink and the stream SharedWorker
14141432
1415-
When the app has a shared-storage backend (the default `LocalSharedStorage`),
1433+
When the app has a shared-storage backend (opt-in, see Shared Storage),
14161434
HTTP streams do not each hold their own response. The callback's POST carries
14171435
`streamConnection: {requestId}` and returns a fast ack; a *pump*
14181436
(`dash/_stream_hub.py`) drives the generator as an asyncio task and publishes

‎.github/dependabot.yml‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -217,6 +217,14 @@ updates:
217217
patterns:
218218
- "*"
219219
ignore:
220+
# Majors across these build helpers and fixtures (eslint 10, prettier 3,
221+
# webpack-cli 7, react-jsx-parser 2, ...) break the build or the pinned
222+
# eslint 8 / prettier 2 toolchain. Take minors and patches only.
223+
- dependency-name: "*"
224+
update-types: ["version-update:semver-major"]
225+
# dash-jupyterlab supports JupyterLab 2, 3 and 4 via a wide range;
226+
# Dependabot narrows it to the latest 4.x and the lockfile bump breaks tsc.
227+
- dependency-name: "@jupyterlab/*"
220228
# react-docgen is pinned for legacy metadata extraction (extract-meta.js uses
221229
# the react-docgen 5 API) and must never be updated.
222230
- dependency-name: "react-docgen"
@@ -260,15 +268,14 @@ updates:
260268
# jupyterlab is pinned <4.0.0: jupyterlab 4.x ships jlpm as Yarn Berry, which
261269
# cannot consume @plotly/dash-jupyterlab's Yarn 1 lockfile and breaks the build.
262270
#
263-
# black >=25.12.0 and pylint >=4.0.0 require Python >=3.10 and cannot install
264-
# on the 3.9 CI jobs (Dash still supports Python 3.9). Upgrading either past
265-
# its last 3.9-compatible release (black 25.11.0, pylint 3.3.9) also forces a
266-
# repo-wide reformat / lint-fix pass, so linter bumps are done deliberately,
267-
# not via Dependabot.
271+
# Linters are held entirely. black >=25.12.0, pylint >=4.0.0 and flake8
272+
# >=7.4.0 require Python >=3.10 and cannot install on the 3.9 CI jobs (Dash
273+
# still supports Python 3.9). Even the last 3.9-compatible black / pylint
274+
# force a repo-wide reformat / lint-fix pass, so linter bumps are done
275+
# deliberately, not via Dependabot.
268276
ignore:
269277
- dependency-name: "jupyterlab"
270278
versions: [">=4.0.0"]
271279
- dependency-name: "black"
272-
versions: [">=25.12.0"]
273280
- dependency-name: "pylint"
274-
versions: [">=4.0.0"]
281+
- dependency-name: "flake8"

‎.github/workflows/post-test-status.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,7 +82,7 @@ jobs:
8282
const sha = context.payload.workflow_run.head_sha;
8383
const statusContext = 'percy/dash';
8484
85-
const { data: { statuses } } = await github.rest.repos.getCombinedStatus({
85+
const { data: { statuses } } = await github.rest.repos.getCombinedStatusForRef({
8686
owner,
8787
repo,
8888
ref: sha,

0 commit comments

Comments
 (0)