Provider
A table loaded asynchronously, from a URL or a load function, for the components inside it.
Static preview; loading the interactive plot
import hmplot as hm
# Palmer penguins, from vega-datasets on a CDN that allows any page to fetch it.
with hm.Provider(url="https://cdn.jsdelivr.net/npm/vega-datasets@2/data/penguins.json", format="json") as penguins:
with hm.Plot(height=300, axes2d=True):
hm.Points(x="Beak Length (mm)", y="Beak Depth (mm)")
penguins
Usage
A Provider is a Data scope whose table is loaded asynchronously. Give it a source — a load(context) function, or { load, requestKey } — or a url with {name} placeholders (fetchJSON and fetchCSV build the same sources), and the explicit params the load depends on. It loads when it mounts and whenever params change to a new request key, after debounce (150 ms) so a dragged slider loads once it pauses. Downstream, a new result is an ordinary Data value change: transforms re-run, keyed updates animate, and selections follow key.
While a load runs, the previous result stays on screen, and a newer request aborts the one in flight (its signal fires; a result that still arrives is dropped). Going back to the params on screen loads nothing. A failed load keeps the previous result, shows the error and calls onerror. refreshInterval polls: ticks never overlap a load, pause while the page is hidden, and a result with an unchanged version (an ETag for the fetch helpers) publishes nothing. The children mount with the first result, or at once with initial.
whenSettled() and every export of a Plot below wait for a load already requested, but not for future refresh ticks, and not for Providers elsewhere on the page. In Python scenes, assigning provider.params returns at once and the plot keeps rendering while the browser loads; when_settled() and the exports wait for it. Exported HTML embeds the last result (snapshot, the default) or loads when opened (snapshot=False).
bind:this gives a ProviderHandle: refresh() loads the same params again and resolves once the result is shown (or found unchanged), whenSettled() waits for the loads already requested, subscribe(listener) reports its status as a transform’s (pending while it loads, and its error), and getResult() returns the ProviderResult on screen: data as the load returned it, its version, request key and revision. getSelection(), getBrush(), getHover(), getOffsets(), resetOffsets() and applyOffsets() act on its table as a Data’s do. In Python, await provider.refresh() loads again.
In Svelte markup, pass a URL template as a JavaScript string, url={"/data/{year}.csv"}: in a quoted attribute Svelte would read {year} as an expression. See docs/PROVIDERS.md for the lifecycle, static sites, REST APIs and exports.