All docs
Tool.deliver
declares an export step — a Table in, a file written or a ViewerPayload out
deliver(fn=None, *, outputs=None, graph_outputs=None, overrides=None, override_mode="replace")
Returns _StepFactory — call it to build a wired delivery-step node
Parameters#
| name | type | default | description |
|---|---|---|---|
outputs |
list[str] |
None |
named output ports for a delivery that also forwards data |
graph_outputs |
dict |
None |
{name: type} read-only scalars set via ctx.set_output(...), excluded from the cache key |
overrides |
str |
None |
make this a drop-in variant of another package's node |
override_mode |
str |
"replace" |
"replace" wins the overridden identity by default; "coexist" keeps both addable |
Contract#
A deliver takes a Table input port and either performs a side effect (returns None) or
returns a ViewerPayload to show a result. The return annotation
decides which: -> None is a pure side effect; -> ViewerPayload (or a subclass — LayerPayload /
ChartPayload / LegendPayload) makes it a viewer-delivering step. A ViewerPayload return is only
valid on @tool.deliver.
Example#
Write a file — a side effect that returns nothing:
@tool.deliver
def to_csv(t: Table, path: str) -> None:
t.write_csv(path)
Show a result — return a payload; the framework persists it, stamps entity_id / step_id, and
emits its topic to every View that watches the entity:
@tool.deliver
def points(t: Table) -> LayerPayload:
return LayerPayload(kind="points", tables={"path": t}, style={"color": "grade"})
Notes#
On a returned payload the framework writes each of the payload's tables to Parquet, persists a
*_payload.json sidecar (reconstructed generically on reopen), and emits the payload's topic — you
never hand-roll ctx.emit("viewer/..."). A viewer-delivering step also gains three optional "Viewer"
routing parameters (layer / view / target). A StepContext parameter may be injected for
ctx.output_dir / ctx.emit; a Context parameter is rejected. override_mode is "replace"
(default) or "coexist".
See also#
API: load · shape · ViewerPayload · Context
Guides: Deliver steps · Rendering & payloads