Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Use generated event types throughout the host stream (#11332)

Trevor Manz557461ffc234
diff --git a/marimo/_core/executions.py b/marimo/_core/executions.py
index 8c28c5ac38..0a9a785cd1 100644
--- a/marimo/_core/executions.py
+++ b/marimo/_core/executions.py
@@ -5,7 +5,7 @@ from __future__ import annotations
from copy import deepcopy
from dataclasses import dataclass, field
-from typing import TYPE_CHECKING, Literal
+from typing import TYPE_CHECKING
from msgspec.structs import replace
@@ -56,7 +56,7 @@ class _Result:
class Removed:
"""A current record that a transition removed."""
- kind: Literal["execution", "console", "display", "variable"]
+ record_type: type[protocol.Execution | protocol.Console | protocol.Display]
id: str
run_id: protocol.RunId | None
@@ -497,13 +497,13 @@ class Executions:
run_id = result.execution.run_id
changes: list[Removed] = [
Removed(
- "console" if isinstance(item, protocol.Console) else "display",
+ type(item),
item.id,
run_id,
)
for item in result.outputs.values()
]
- changes.append(Removed("execution", execution_id, run_id))
+ changes.append(Removed(protocol.Execution, execution_id, run_id))
self._forget_result(execution_id)
return changes
diff --git a/marimo/_core/host.py b/marimo/_core/host.py
index 9441ed9ab6..910c4cc029 100644
--- a/marimo/_core/host.py
+++ b/marimo/_core/host.py
@@ -11,16 +11,24 @@ from dataclasses import dataclass
from time import monotonic
from typing import TYPE_CHECKING
-from marimo._core import protocol
+from marimo._core import protocol, protocol_events
from marimo._core.errors import NotFound
from marimo._core.notebook import Notebook
from marimo._core.run_log import RetentionPolicy, RunLog
-from marimo._core.stream import Event, Listener, Sink, Stream, message
+from marimo._core.stream import (
+ Listener,
+ RoutedEvent,
+ Sink,
+ Stream,
+ snapshot_event,
+)
if TYPE_CHECKING:
from collections.abc import Collection, Iterator, Sequence
from contextlib import AbstractContextManager
+ from marimo._core.protocol_events import Body
+
NotebookInitializer = Callable[
[protocol.Notebook, Sink], Notebook | Awaitable[Notebook]
@@ -50,7 +58,7 @@ class _NotebookSink(Sink):
def deferred(self) -> AbstractContextManager[None]:
return self._stream.deferred()
- def _append(self, event: Event) -> Event:
+ def _append(self, event: RoutedEvent) -> RoutedEvent:
if not self.active:
return event
with self._stream.deferred():
@@ -77,10 +85,13 @@ class _NotebookRecords(Mapping[str, protocol.Notebook]):
return len(self._records)
-def _identity(event: Event) -> tuple[str, str]:
- assert event.kind is not None
- body = getattr(event.data, event.kind)
- return event.name, getattr(body, "id", None) or body.notebook_id
+def _identity(event: RoutedEvent) -> tuple[type[Body], str]:
+ assert isinstance(event.event, protocol_events.RecordEvent)
+ body = protocol_events.body(event.event)
+ assert not isinstance(body, (protocol.Host, protocol.Custom))
+ if isinstance(body, (protocol.Document, protocol.Analysis)):
+ return type(body), body.notebook_id
+ return type(body), body.id
class Host:
@@ -179,7 +190,7 @@ class Host:
if entry.sink is not None:
entry.sink.active = False
self._stream.remove(
- "notebook",
+ protocol.Notebook,
record.id,
notebook_id=record.id,
request_id=request_id,
@@ -236,13 +247,11 @@ class Host:
# The initial state joins the stream the way later changes do,
# so the run history sees every run from its first event.
with self._stream.deferred():
- for event in notebook._snapshot():
- assert event.kind is not None
- body = getattr(event.data, event.kind)
+ for body, run_id in notebook._records():
sink.publish(
body,
notebook_id=notebook.id,
- run_id=event.run_id,
+ run_id=run_id,
)
if self._entries.get(notebook_id) is not entry:
raise NotFound(f"no notebook {notebook_id}")
@@ -259,25 +268,21 @@ class Host:
def _snapshot(
self, notebook_id: protocol.NotebookId | None = None
- ) -> list[Event]:
+ ) -> list[RoutedEvent]:
"""Return catalog or notebook state with retained run history."""
if notebook_id is not None:
records = [self._records[notebook_id]]
- events: list[Event] = []
+ events: list[RoutedEvent] = []
else:
records = list(self._records.values())
- events = [Event("host", message(self._host))]
- events.extend(
- Event("project", message(p)) for p in self._projects.values()
- )
+ events = [snapshot_event(self._host)]
+ events.extend(snapshot_event(p) for p in self._projects.values())
for record in records:
- events.append(
- Event("notebook", message(record), notebook_id=record.id)
- )
+ events.append(snapshot_event(record, notebook_id=record.id))
entry = self._entries[record.id]
if entry.notebook is None:
continue
- seen: set[tuple[str, str]] = set()
+ seen: set[tuple[type[Body], str]] = set()
for event in [
*entry.notebook._snapshot(),
*entry.log.snapshot(),
@@ -295,7 +300,7 @@ class Host:
notebook_id: str | None = None,
types: Collection[str] | None = None,
run_id: str | None = None,
- ) -> list[Event]:
+ ) -> list[RoutedEvent]:
"""Return a snapshot or replay followed by `ready`.
A cursor requests the events after it. An unavailable cursor returns
@@ -306,13 +311,18 @@ class Host:
if notebook_id not in self._records:
raise NotFound(f"no notebook {notebook_id}")
scope = self._records[notebook_id].id
- ready = Event("ready", id=self._stream.last_id)
+ ready = RoutedEvent(
+ protocol.ReadyEvent(data={}, id=str(self._stream.last_id))
+ )
if cursor is None:
events = self._snapshot(scope)
else:
missed = self._stream.since(cursor)
if missed is None:
- events = [Event("reset"), *self._snapshot(scope)]
+ events = [
+ RoutedEvent(protocol.ResetEvent(data={})),
+ *self._snapshot(scope),
+ ]
else:
events = [e for e in missed if e.visible_in(notebook_id)]
return [e for e in [*events, ready] if e.wanted(types, run_id)]
@@ -334,7 +344,7 @@ class Host:
) -> Callable[[], None]:
"""Subscribe to matching events and return an unsubscribe function."""
- def filtered(event: Event) -> None:
+ def filtered(event: RoutedEvent) -> None:
if event.visible_in(notebook_id) and event.wanted(types, run_id):
listener(event)
diff --git a/marimo/_core/notebook.py b/marimo/_core/notebook.py
index 8d03364da4..6615010edd 100644
--- a/marimo/_core/notebook.py
+++ b/marimo/_core/notebook.py
@@ -16,10 +16,10 @@ from marimo._core.document import Stale
from marimo._core.errors import Conflict, EditConflict, NoRuntime, NotFound
from marimo._core.executions import Executions, Released, Removed
from marimo._core.ids import mint
-from marimo._core.stream import Event, Kind, kind_of, message, utcnow
+from marimo._core.stream import RoutedEvent, snapshot_event, utcnow
if TYPE_CHECKING:
- from collections.abc import Callable, Mapping, Sequence
+ from collections.abc import Callable, Iterator, Mapping, Sequence
from marimo._core.analysis import Analyzer
from marimo._core.document import (
@@ -28,7 +28,8 @@ if TYPE_CHECKING:
DocumentCell,
)
from marimo._core.executions import Change
- from marimo._core.stream import Body, Sink
+ from marimo._core.protocol_events import Body, RemovableBody, SnapshotBody
+ from marimo._core.stream import Sink
LOGGER = logging.getLogger(__name__)
@@ -275,7 +276,7 @@ class Notebook:
self._apply(
self.executions.remove_cell(protocol.CellId(cell_id))
)
- self._remove("cell", cell_id, request_id)
+ self._remove(protocol.Cell, cell_id, request_id)
record = self._refresh()
if record is not None:
self._publish(record, request_id)
@@ -421,7 +422,7 @@ class Notebook:
assert self._runtime is not None
self._apply(self.executions.interrupt())
runtime, self._runtime = self._runtime, None
- self._remove("runtime", runtime.id, self._runtime_request)
+ self._remove(protocol.Runtime, runtime.id, self._runtime_request)
self._runtime_request = None
# ---- runs ----------------------------------------------------------
@@ -492,7 +493,7 @@ class Notebook:
"""Remove an attachment if it exists."""
attachment = self._attachments.pop(attachment_id, None)
if attachment is not None:
- self._remove("attachment", attachment.id, None)
+ self._remove(protocol.Attachment, attachment.id, None)
# ---- backend updates -----------------------------------------------
@@ -583,35 +584,31 @@ class Notebook:
# ---- stream --------------------------------------------------------
- def _snapshot(self) -> list[Event]:
- """Return current state as events in dependency order."""
- bodies: list[Body] = [
- *(self._cell_record(cell) for cell in self.document),
- self._document_record,
- ]
+ def _records(self) -> Iterator[tuple[SnapshotBody, protocol.RunId | None]]:
+ """Current records in dependency order, borrowed until publication."""
+ for cell in self.document:
+ yield self._cell_record(cell), None
+ yield self._document_record, None
if self._analysis is not None:
- bodies.append(self._analysis)
+ yield self._analysis, None
if self._runtime is not None:
- bodies.append(self._runtime)
- bodies.extend(self._attachments.values())
- events = [
- Event(kind_of(body), message(body), notebook_id=self.id)
- for body in bodies
- ]
- executions = self.executions
- for record in executions._records():
- run_id = executions.run_id_of(record)
- events.append(
- Event(
- kind_of(record),
- message(
- record, request_id=executions.snapshot_request(run_id)
- ),
- notebook_id=self.id,
- run_id=run_id,
- )
+ yield self._runtime, None
+ for attachment in self._attachments.values():
+ yield attachment, None
+ for record in self.executions._records():
+ yield record, self.executions.run_id_of(record)
+
+ def _snapshot(self) -> list[RoutedEvent]:
+ """Return current state as events in dependency order."""
+ return [
+ snapshot_event(
+ record,
+ request_id=self.executions.snapshot_request(run_id),
+ notebook_id=self.id,
+ run_id=run_id,
)
- return events
+ for record, run_id in self._records()
+ ]
def _dispose(self, *, request_id: str | None = None) -> None:
"""Close the notebook and remove its state, children first.
@@ -627,7 +624,7 @@ class Notebook:
self.detach(attachment_id)
if self._runtime is not None:
runtime, self._runtime = self._runtime, None
- self._remove("runtime", runtime.id, request_id)
+ self._remove(protocol.Runtime, runtime.id, request_id)
def _publish(self, body: Body, request_id: str | None) -> None:
self.sink.publish(
@@ -638,12 +635,12 @@ class Notebook:
def _remove(
self,
- kind: Kind,
+ record_type: type[RemovableBody],
object_id: str,
request_id: str | None,
) -> None:
self.sink.remove(
- kind,
+ record_type,
object_id,
notebook_id=self.id,
request_id=request_id,
@@ -662,7 +659,7 @@ class Notebook:
request_id = executions.request_id(run_id)
if isinstance(change, Removed):
self.sink.remove(
- change.kind,
+ change.record_type,
change.id,
notebook_id=self.id,
run_id=run_id,
diff --git a/marimo/_core/protocol_events.py b/marimo/_core/protocol_events.py
new file mode 100644
index 0000000000..0b4f5e55ff
--- /dev/null
+++ b/marimo/_core/protocol_events.py
@@ -0,0 +1,612 @@
+# Copyright 2026 Marimo. All rights reserved.
+# AUTO-GENERATED FILE — DO NOT EDIT.
+# Generated from protocols/host/openapi.yaml.
+# Regenerate with `make host-protocol-codegen`.
+"""Typed envelope adapters. Payload ownership stays with the caller."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeAlias, overload
+
+from msgspec import UNSET, UnsetType
+
+from marimo._core import protocol
+
+if TYPE_CHECKING:
+ from datetime import datetime
+
+Body: TypeAlias = (
+ protocol.Analysis
+ | protocol.Attachment
+ | protocol.Cell
+ | protocol.Console
+ | protocol.Custom
+ | protocol.Display
+ | protocol.Document
+ | protocol.Execution
+ | protocol.Host
+ | protocol.Notebook
+ | protocol.Project
+ | protocol.Run
+ | protocol.Runtime
+ | protocol.Variable
+)
+SnapshotBody: TypeAlias = (
+ protocol.Analysis
+ | protocol.Attachment
+ | protocol.Cell
+ | protocol.Console
+ | protocol.Display
+ | protocol.Document
+ | protocol.Execution
+ | protocol.Host
+ | protocol.Notebook
+ | protocol.Project
+ | protocol.Run
+ | protocol.Runtime
+ | protocol.Variable
+)
+RecordEvent: TypeAlias = (
+ protocol.AnalysisEvent
+ | protocol.AttachmentEvent
+ | protocol.CellEvent
+ | protocol.ConsoleEvent
+ | protocol.CustomEvent
+ | protocol.DisplayEvent
+ | protocol.DocumentEvent
+ | protocol.ExecutionEvent
+ | protocol.HostEvent
+ | protocol.NotebookEvent
+ | protocol.ProjectEvent
+ | protocol.RunEvent
+ | protocol.RuntimeEvent
+ | protocol.VariableEvent
+)
+RemovableBody: TypeAlias = (
+ protocol.Attachment
+ | protocol.Cell
+ | protocol.Console
+ | protocol.Display
+ | protocol.Execution
+ | protocol.Notebook
+ | protocol.Project
+ | protocol.Run
+ | protocol.Runtime
+ | protocol.Variable
+)
+RemovalEvent: TypeAlias = (
+ protocol.AttachmentRemovedEvent
+ | protocol.CellRemovedEvent
+ | protocol.ConsoleRemovedEvent
+ | protocol.DisplayRemovedEvent
+ | protocol.ExecutionRemovedEvent
+ | protocol.NotebookRemovedEvent
+ | protocol.ProjectRemovedEvent
+ | protocol.RunRemovedEvent
+ | protocol.RuntimeRemovedEvent
+ | protocol.VariableRemovedEvent
+)
+
+
+@overload
+def record(
+ value: protocol.Analysis,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.AnalysisEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Attachment,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.AttachmentEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Cell,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.CellEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Console,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.ConsoleEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Custom,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime,
+) -> protocol.CustomEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Display,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.DisplayEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Document,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.DocumentEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Execution,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.ExecutionEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Host,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.HostEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Notebook,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.NotebookEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Project,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.ProjectEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Run,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.RunEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Runtime,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.RuntimeEvent: ...
+
+
+@overload
+def record(
+ value: protocol.Variable,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.VariableEvent: ...
+
+
+def record(
+ value: Body,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> RecordEvent:
+ """Wrap a record without copying it; occurrences require a timestamp."""
+ match value:
+ case protocol.Analysis():
+ return protocol.AnalysisEvent(
+ protocol.AnalysisMessage(
+ analysis=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Attachment():
+ return protocol.AttachmentEvent(
+ protocol.AttachmentMessage(
+ attachment=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Cell():
+ return protocol.CellEvent(
+ protocol.CellMessage(
+ cell=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Console():
+ return protocol.ConsoleEvent(
+ protocol.ConsoleMessage(
+ console=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Custom():
+ if isinstance(time, UnsetType):
+ raise ValueError("CustomEvent requires an emission time")
+
+ return protocol.CustomEvent(
+ protocol.CustomMessage(
+ custom=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Display():
+ return protocol.DisplayEvent(
+ protocol.DisplayMessage(
+ display=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Document():
+ return protocol.DocumentEvent(
+ protocol.DocumentMessage(
+ document=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Execution():
+ return protocol.ExecutionEvent(
+ protocol.ExecutionMessage(
+ execution=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Host():
+ return protocol.HostEvent(
+ protocol.HostMessage(
+ host=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Notebook():
+ return protocol.NotebookEvent(
+ protocol.NotebookMessage(
+ notebook=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Project():
+ return protocol.ProjectEvent(
+ protocol.ProjectMessage(
+ project=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Run():
+ return protocol.RunEvent(
+ protocol.RunMessage(
+ run=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Runtime():
+ return protocol.RuntimeEvent(
+ protocol.RuntimeMessage(
+ runtime=value, request_id=request_id, time=time
+ )
+ )
+
+ case protocol.Variable():
+ return protocol.VariableEvent(
+ protocol.VariableMessage(
+ variable=value, request_id=request_id, time=time
+ )
+ )
+
+ raise TypeError(f"Unsupported record type: {type(value)}")
+
+
+@overload
+def body(event: protocol.AnalysisEvent) -> protocol.Analysis: ...
+
+
+@overload
+def body(event: protocol.AttachmentEvent) -> protocol.Attachment: ...
+
+
+@overload
+def body(event: protocol.CellEvent) -> protocol.Cell: ...
+
+
+@overload
+def body(event: protocol.ConsoleEvent) -> protocol.Console: ...
+
+
+@overload
+def body(event: protocol.CustomEvent) -> protocol.Custom: ...
+
+
+@overload
+def body(event: protocol.DisplayEvent) -> protocol.Display: ...
+
+
+@overload
+def body(event: protocol.DocumentEvent) -> protocol.Document: ...
+
+
+@overload
+def body(event: protocol.ExecutionEvent) -> protocol.Execution: ...
+
+
+@overload
+def body(event: protocol.HostEvent) -> protocol.Host: ...
+
+
+@overload
+def body(event: protocol.NotebookEvent) -> protocol.Notebook: ...
+
+
+@overload
+def body(event: protocol.ProjectEvent) -> protocol.Project: ...
+
+
+@overload
+def body(event: protocol.RunEvent) -> protocol.Run: ...
+
+
+@overload
+def body(event: protocol.RuntimeEvent) -> protocol.Runtime: ...
+
+
+@overload
+def body(event: protocol.VariableEvent) -> protocol.Variable: ...
+
+
+def body(event: RecordEvent) -> Body:
+ """Read a record payload without copying it."""
+ match event:
+ case protocol.AnalysisEvent(data=data):
+ return data.analysis
+
+ case protocol.AttachmentEvent(data=data):
+ return data.attachment
+
+ case protocol.CellEvent(data=data):
+ return data.cell
+
+ case protocol.ConsoleEvent(data=data):
+ return data.console
+
+ case protocol.CustomEvent(data=data):
+ return data.custom
+
+ case protocol.DisplayEvent(data=data):
+ return data.display
+
+ case protocol.DocumentEvent(data=data):
+ return data.document
+
+ case protocol.ExecutionEvent(data=data):
+ return data.execution
+
+ case protocol.HostEvent(data=data):
+ return data.host
+
+ case protocol.NotebookEvent(data=data):
+ return data.notebook
+
+ case protocol.ProjectEvent(data=data):
+ return data.project
+
+ case protocol.RunEvent(data=data):
+ return data.run
+
+ case protocol.RuntimeEvent(data=data):
+ return data.runtime
+
+ case protocol.VariableEvent(data=data):
+ return data.variable
+
+ raise TypeError(f"Not a record event: {type(event)}")
+
+
+@overload
+def removed(
+ record_type: type[protocol.Attachment],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.AttachmentRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Cell],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.CellRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Console],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.ConsoleRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Display],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.DisplayRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Execution],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.ExecutionRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Notebook],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.NotebookRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Project],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.ProjectRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Run],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.RunRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Runtime],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.RuntimeRemovedEvent: ...
+
+
+@overload
+def removed(
+ record_type: type[protocol.Variable],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.VariableRemovedEvent: ...
+
+
+def removed(
+ record_type: type[RemovableBody],
+ object_id: str,
+ *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> RemovalEvent:
+ """Construct the removal envelope for a supported record type."""
+
+ if record_type is protocol.Attachment:
+ return protocol.AttachmentRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Cell:
+ return protocol.CellRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Console:
+ return protocol.ConsoleRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Display:
+ return protocol.DisplayRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Execution:
+ return protocol.ExecutionRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Notebook:
+ return protocol.NotebookRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Project:
+ return protocol.ProjectRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Run:
+ return protocol.RunRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Runtime:
+ return protocol.RuntimeRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ if record_type is protocol.Variable:
+ return protocol.VariableRemovedEvent(
+ protocol.RemovedMessage(
+ id=object_id, request_id=request_id, time=time
+ )
+ )
+
+ raise TypeError(f"No removal event for {record_type}")
diff --git a/marimo/_core/run_log.py b/marimo/_core/run_log.py
index cabf5baf7a..3edbe2b667 100644
--- a/marimo/_core/run_log.py
+++ b/marimo/_core/run_log.py
@@ -7,8 +7,8 @@ from dataclasses import dataclass, field
from math import isfinite
from typing import TYPE_CHECKING
-from marimo._core import protocol
-from marimo._core.stream import Event, Kind, message, removal
+from marimo._core import protocol, protocol_events
+from marimo._core.stream import RoutedEvent, removal, snapshot_event
if TYPE_CHECKING:
from collections.abc import Callable
@@ -29,15 +29,15 @@ class RetentionPolicy:
class _Scratch:
"""A scratch execution's latest event and its outputs."""
- execution: Event
- outputs: dict[str, Event] = field(default_factory=dict)
+ execution: RoutedEvent
+ outputs: dict[str, RoutedEvent] = field(default_factory=dict)
@dataclass
class _Run:
"""A run's latest event and what still keeps it visible."""
- event: Event
+ event: RoutedEvent
request_id: str | None
live: set[str] = field(default_factory=set)
scratch: dict[str, _Scratch] = field(default_factory=dict)
@@ -60,10 +60,10 @@ class RunLog:
self._clock = clock
self._runs: dict[str, _Run] = {}
- def observe(self, event: Event) -> list[Event]:
+ def observe(self, event: RoutedEvent) -> list[RoutedEvent]:
"""Record an event and return removals to publish after it."""
- match event:
- case Event(
+ match event.event:
+ case protocol.RunEvent(
data=protocol.RunMessage(run=run, request_id=request_id)
):
entry = self._runs.get(run.id)
@@ -76,7 +76,9 @@ class RunLog:
if run.status == "completed" and entry.completed_at is None:
entry.completed_at = self._clock()
return self._close(run.id)
- case Event(data=protocol.ExecutionMessage(execution=execution)):
+ case protocol.ExecutionEvent(
+ data=protocol.ExecutionMessage(execution=execution)
+ ):
if (entry := self._entry(event)) is not None:
entry.had_executions = True
entry.live.add(execution.id)
@@ -86,12 +88,16 @@ class RunLog:
entry.scratch[execution.id] = _Scratch(event)
else:
scratch.execution = event
- case Event(data=protocol.ConsoleMessage(console=item)):
+ case protocol.ConsoleEvent(
+ data=protocol.ConsoleMessage(console=item)
+ ):
self._record_output(event, item)
- case Event(data=protocol.DisplayMessage(display=item)):
+ case protocol.DisplayEvent(
+ data=protocol.DisplayMessage(display=item)
+ ):
self._record_output(event, item)
- case Event(
- kind="execution", data=protocol.RemovedMessage(id=execution_id)
+ case protocol.ExecutionRemovedEvent(
+ data=protocol.RemovedMessage(id=execution_id)
):
if (entry := self._entry(event)) is not None:
entry.live.discard(execution_id)
@@ -105,10 +111,10 @@ class RunLog:
entry = self._runs.get(run_id)
if entry is None:
return None
- assert isinstance(entry.event.data, protocol.RunMessage)
- return entry.event.data.run
+ assert isinstance(entry.event.event, protocol.RunEvent)
+ return entry.event.event.data.run
- def snapshot(self) -> list[Event]:
+ def snapshot(self) -> list[RoutedEvent]:
"""Return the runs and scratch the log holds, parents first."""
events = [
self._snapshot_event(e.event, e) for e in self._runs.values()
@@ -122,10 +128,10 @@ class RunLog:
)
return events
- def expire(self, policy: RetentionPolicy) -> list[Event]:
+ def expire(self, policy: RetentionPolicy) -> list[RoutedEvent]:
"""Return removals for scratch whose retention has ended."""
now = self._clock()
- events: list[Event] = []
+ events: list[RoutedEvent] = []
for run_id, entry in list(self._runs.items()):
if (
(entry.scratch or not entry.had_executions)
@@ -135,9 +141,9 @@ class RunLog:
events.extend(self._release(run_id))
return events
- def clear(self) -> list[Event]:
+ def clear(self) -> list[RoutedEvent]:
"""Remove all retained history."""
- events: list[Event] = []
+ events: list[RoutedEvent] = []
for run_id, entry in list(self._runs.items()):
entry.live.clear()
if entry.completed_at is None:
@@ -145,11 +151,11 @@ class RunLog:
events.extend(self._release(run_id))
return events
- def _entry(self, event: Event) -> _Run | None:
+ def _entry(self, event: RoutedEvent) -> _Run | None:
return None if event.run_id is None else self._runs.get(event.run_id)
def _record_output(
- self, event: Event, item: protocol.Console | protocol.Display
+ self, event: RoutedEvent, item: protocol.Console | protocol.Display
) -> None:
entry = self._entry(event)
if entry is None:
@@ -158,21 +164,28 @@ class RunLog:
if scratch is not None:
scratch.outputs[item.id] = event
- def _release(self, run_id: str) -> list[Event]:
+ def _release(self, run_id: str) -> list[RoutedEvent]:
"""Remove a run's scratch, then the run if nothing else holds it."""
entry = self._runs[run_id]
- events: list[Event] = []
+ events: list[RoutedEvent] = []
for execution_id, scratch in entry.scratch.items():
for output in scratch.outputs.values():
- assert output.kind is not None
- item = getattr(output.data, output.kind)
- events.append(self._removal(entry, output.kind, item.id))
- events.append(self._removal(entry, "execution", execution_id))
+ assert isinstance(
+ output.event,
+ (protocol.ConsoleEvent, protocol.DisplayEvent),
+ )
+ body = protocol_events.body(output.event)
+ events.append(self._removal(entry, type(body), body.id))
+ events.append(
+ self._removal(entry, protocol.Execution, execution_id)
+ )
entry.live.discard(execution_id)
entry.scratch.clear()
return [*events, *self._close(run_id, retain_empty=False)]
- def _close(self, run_id: str, *, retain_empty: bool = True) -> list[Event]:
+ def _close(
+ self, run_id: str, *, retain_empty: bool = True
+ ) -> list[RoutedEvent]:
entry = self._runs[run_id]
if (
entry.completed_at is None
@@ -181,29 +194,30 @@ class RunLog:
):
return []
del self._runs[run_id]
- return [self._removal(entry, "run", run_id)]
-
- def _removal(self, entry: _Run, kind: Kind, object_id: str) -> Event:
+ return [self._removal(entry, protocol.Run, run_id)]
+
+ def _removal(
+ self,
+ entry: _Run,
+ record_type: type[protocol_events.RemovableBody],
+ object_id: str,
+ ) -> RoutedEvent:
return removal(
- kind,
+ record_type,
object_id,
notebook_id=entry.event.notebook_id,
request_id=entry.request_id,
run_id=entry.event.run_id,
)
- def _snapshot_event(self, event: Event, entry: _Run) -> Event:
- assert event.kind is not None
- body = getattr(event.data, event.kind)
- return Event(
- event.name,
- message(
- body,
- request_id=(
- None
- if entry.completed_at is not None
- else entry.request_id
- ),
+ def _snapshot_event(self, event: RoutedEvent, entry: _Run) -> RoutedEvent:
+ assert isinstance(event.event, protocol_events.RecordEvent)
+ body = protocol_events.body(event.event)
+ assert isinstance(body, protocol_events.SnapshotBody)
+ return snapshot_event(
+ body,
+ request_id=(
+ None if entry.completed_at is not None else entry.request_id
),
notebook_id=event.notebook_id,
run_id=event.run_id,
diff --git a/marimo/_core/stream.py b/marimo/_core/stream.py
index eb21e0cf9b..706c23cf8b 100644
--- a/marimo/_core/stream.py
+++ b/marimo/_core/stream.py
@@ -13,94 +13,32 @@ from collections import deque
from collections.abc import Callable, Collection, Iterator
from contextlib import AbstractContextManager, contextmanager
from copy import deepcopy
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
from datetime import datetime, timezone
-from typing import Literal, TypeAlias, get_args
import msgspec
from msgspec import UNSET
-from marimo._core import protocol
+from marimo._core import protocol, protocol_events
LOGGER = logging.getLogger(__name__)
-Body: TypeAlias = (
- protocol.Host
- | protocol.Project
- | protocol.Notebook
- | protocol.Document
- | protocol.Analysis
- | protocol.Cell
- | protocol.Runtime
- | protocol.Attachment
- | protocol.Run
- | protocol.Execution
- | protocol.Console
- | protocol.Display
- | protocol.Variable
- | protocol.Custom
-)
-"""Every object a stream carries. The wrapper map and the notebook kinds
-derive from it; the catalog kinds are a chosen subset."""
-
-
-Kind: TypeAlias = Literal[
- "host",
- "project",
- "notebook",
- "document",
- "analysis",
- "cell",
- "runtime",
- "attachment",
- "run",
- "execution",
- "console",
- "display",
- "variable",
- "custom",
-]
-"""The kinds of object a stream carries, one per `Body` type."""
-
-_KIND_BY_NAME: dict[str, Kind] = {kind: kind for kind in get_args(Kind)}
-assert set(_KIND_BY_NAME) == {
- body_type.__name__.lower() for body_type in get_args(Body)
-}
-
-
-def kind_of(body: Body) -> Kind:
- """Return the object's event kind, used by the `types` filter."""
- return _KIND_BY_NAME[type(body).__name__.lower()]
-
-
-_WRAPPERS: dict[Kind, type[msgspec.Struct]] = {
- _KIND_BY_NAME[body_type.__name__.lower()]: getattr(
- protocol, f"{body_type.__name__}Message"
- )
- for body_type in get_args(Body)
-}
-
-CATALOG_KINDS: frozenset[Kind] = frozenset(
- {"host", "project", "notebook", "runtime", "attachment"}
-)
-# Host and project describe the whole host, so they never belong to one
-# notebook's stream. Every other kind does.
-NOTEBOOK_KINDS = frozenset(_WRAPPERS) - {"host", "project"}
-
-def message(
- body: Body,
+def snapshot_event(
+ body: protocol_events.SnapshotBody,
*,
+ notebook_id: protocol.NotebookId | None = None,
+ run_id: protocol.RunId | None = None,
request_id: str | None = None,
- time: datetime | None = None,
-) -> msgspec.Struct:
- """Wrap an object in its protocol message."""
- kind = kind_of(body)
- fields: dict[str, Body] = {kind: deepcopy(body)}
- return _WRAPPERS[kind](
- **fields,
- request_id=UNSET if request_id is None else request_id,
- time=UNSET if time is None else time,
+) -> RoutedEvent:
+ """Copy current state into an event without an emission time or cursor."""
+ return RoutedEvent(
+ protocol_events.record(
+ deepcopy(body),
+ request_id=UNSET if request_id is None else request_id,
+ ),
+ notebook_id=notebook_id,
+ run_id=run_id,
)
@@ -109,66 +47,100 @@ def utcnow() -> datetime:
def removal(
- kind: Kind,
+ record_type: type[protocol_events.RemovableBody],
object_id: str,
*,
notebook_id: protocol.NotebookId | None = None,
request_id: str | None = None,
run_id: protocol.RunId | None = None,
-) -> Event:
+) -> RoutedEvent:
"""Return an event announcing an object's removal."""
- data = protocol.RemovedMessage(
- id=object_id,
- request_id=UNSET if request_id is None else request_id,
- time=utcnow(),
- )
- return Event(
- f"{kind}.removed", data, notebook_id=notebook_id, run_id=run_id
+ return RoutedEvent(
+ protocol_events.removed(
+ record_type,
+ object_id,
+ request_id=UNSET if request_id is None else request_id,
+ time=utcnow(),
+ ),
+ notebook_id=notebook_id,
+ run_id=run_id,
)
-@dataclass(frozen=True)
-class Event:
- """An event with an optional replay cursor and notebook scope.
+class ExtensionEvent(msgspec.Struct, frozen=True, tag_field="event"):
+ """Base envelope for host extensions outside the public protocol.
- Snapshot events have no `id`. Control events have no `data`.
+ Subclasses declare their event tag and payload type.
"""
- name: str
- data: msgspec.Struct | None = None
- id: int | None = None
+ data: msgspec.Struct
+ id: str | msgspec.UnsetType = UNSET
+
+
+def event_name(event: protocol.Event | ExtensionEvent) -> str:
+ """Read the wire tag for transport framing and client type filters."""
+ tag = event.__struct_config__.tag
+ assert isinstance(tag, str)
+ return tag
+
+
+@dataclass(frozen=True)
+class RoutedEvent:
+ """A typed wire event with internal notebook and run routing."""
+
+ event: protocol.Event | ExtensionEvent
notebook_id: protocol.NotebookId | None = None
run_id: protocol.RunId | None = None
@property
- def kind(self) -> Kind | None:
- """The object kind without the `.removed` suffix.
-
- `ready` and `reset` carry no object and have no kind.
- """
- return _KIND_BY_NAME.get(self.name.partition(".")[0])
+ def id(self) -> int | None:
+ """The stream's integer cursor, absent on snapshots and resets."""
+ return None if self.event.id is UNSET else int(self.event.id)
def visible_in(self, notebook_id: str | None) -> bool:
"""Whether the event belongs in the catalog or notebook stream."""
+ if isinstance(self.event, (protocol.ReadyEvent, protocol.ResetEvent)):
+ return False
if notebook_id is None:
- return self.kind in CATALOG_KINDS
- return self.notebook_id == notebook_id and (
- self.kind in NOTEBOOK_KINDS
- or (self.kind is None and self.name not in ("ready", "reset"))
+ return isinstance(
+ self.event,
+ (
+ protocol.HostEvent,
+ protocol.ProjectEvent,
+ protocol.ProjectRemovedEvent,
+ protocol.NotebookEvent,
+ protocol.NotebookRemovedEvent,
+ protocol.RuntimeEvent,
+ protocol.RuntimeRemovedEvent,
+ protocol.AttachmentEvent,
+ protocol.AttachmentRemovedEvent,
+ ),
+ )
+ return self.notebook_id == notebook_id and not isinstance(
+ self.event,
+ (
+ protocol.HostEvent,
+ protocol.ProjectEvent,
+ protocol.ProjectRemovedEvent,
+ ),
)
def wanted(
self, types: Collection[str] | None, run_id: str | None = None
) -> bool:
"""Apply kind and run filters, always including `ready` and `reset`."""
- if self.name in ("ready", "reset"):
+ if isinstance(self.event, (protocol.ReadyEvent, protocol.ResetEvent)):
return True
- return (types is None or (self.kind or self.name) in types) and (
- run_id is None or self.run_id == run_id
- )
+ if types is not None:
+ kind = event_name(self.event)
+ if isinstance(self.event, protocol_events.RemovalEvent):
+ kind = kind.removesuffix(".removed")
+ if kind not in types:
+ return False
+ return run_id is None or self.run_id == run_id
-Listener = Callable[[Event], None]
+Listener = Callable[[RoutedEvent], None]
class Sink(ABC):
@@ -178,37 +150,44 @@ class Sink(ABC):
each event before the stream records it.
"""
- def append(self, event: Event) -> Event:
+ def append(self, event: RoutedEvent) -> RoutedEvent:
"""Record an event without requiring a public protocol type."""
return self._append(deepcopy(event))
def publish(
self,
- body: Body,
+ body: protocol_events.Body,
*,
notebook_id: protocol.NotebookId | None = None,
request_id: str | None = None,
run_id: protocol.RunId | None = None,
- ) -> Event:
+ ) -> RoutedEvent:
"""Publish a new or updated object."""
- data = message(body, request_id=request_id, time=utcnow())
return self._append(
- Event(kind_of(body), data, notebook_id=notebook_id, run_id=run_id)
+ RoutedEvent(
+ protocol_events.record(
+ deepcopy(body),
+ request_id=UNSET if request_id is None else request_id,
+ time=utcnow(),
+ ),
+ notebook_id=notebook_id,
+ run_id=run_id,
+ )
)
def remove(
self,
- kind: Kind,
+ record_type: type[protocol_events.RemovableBody],
object_id: str,
*,
notebook_id: protocol.NotebookId | None = None,
request_id: str | None = None,
run_id: protocol.RunId | None = None,
- ) -> Event:
+ ) -> RoutedEvent:
"""Publish an object's removal."""
return self._append(
removal(
- kind,
+ record_type,
object_id,
notebook_id=notebook_id,
request_id=request_id,
@@ -221,7 +200,7 @@ class Sink(ABC):
"""Deliver events published in the block once it ends."""
@abstractmethod
- def _append(self, event: Event) -> Event:
+ def _append(self, event: RoutedEvent) -> RoutedEvent:
"""Record an owned event and return an isolated copy as recorded.
The event must already be isolated from the caller. Forward it to
@@ -238,16 +217,18 @@ class Stream(Sink):
def __init__(self, *, history: int = 1000) -> None:
self._last_id = 0
- self._history: deque[Event] = deque(maxlen=history)
+ self._history: deque[RoutedEvent] = deque(maxlen=history)
self._listeners: list[Listener] = []
- self._pending: deque[tuple[Event, tuple[Listener, ...]]] = deque()
+ self._pending: deque[tuple[RoutedEvent, tuple[Listener, ...]]] = (
+ deque()
+ )
self._dispatching = False
@property
def last_id(self) -> int:
return self._last_id
- def since(self, cursor: int) -> list[Event] | None:
+ def since(self, cursor: int) -> list[RoutedEvent] | None:
"""Return events after `cursor`, or `None` for a stale or future cursor."""
if cursor == self._last_id:
return []
@@ -292,14 +273,11 @@ class Stream(Sink):
self._dispatching = False
self._drain()
- def _append(self, event: Event) -> Event:
+ def _append(self, event: RoutedEvent) -> RoutedEvent:
self._last_id += 1
- stamped = Event(
- event.name,
- event.data,
- self._last_id,
- event.notebook_id,
- event.run_id,
+ stamped = replace(
+ event,
+ event=msgspec.structs.replace(event.event, id=str(self._last_id)),
)
self._history.append(stamped)
self._pending.append((stamped, tuple(self._listeners)))
diff --git a/marimo/_server/host/api.py b/marimo/_server/host/api.py
index 43f2606721..7ecdeef58e 100644
--- a/marimo/_server/host/api.py
+++ b/marimo/_server/host/api.py
@@ -30,6 +30,7 @@ from marimo._core.errors import (
NoRuntime,
NotFound,
)
+from marimo._core.stream import event_name
from marimo._server.api.auth import TOKEN_QUERY_PARAM, validate_auth
from marimo._server.api.deps import AppState, AppStateBase
from marimo._server.api.endpoints.ws.ws_connection_validator import (
@@ -52,7 +53,7 @@ if TYPE_CHECKING:
from starlette.requests import HTTPConnection, Request
from marimo._core.notebook import Notebook
- from marimo._core.stream import Event
+ from marimo._core.stream import RoutedEvent
from marimo._server.host.bridge import SessionBridge
from marimo._server.host.context import HostContext
@@ -254,10 +255,10 @@ def _mutation(operation: str) -> Callable[[_Endpoint], _Endpoint]:
lifecycle_accepted: Callable[[Response], None] | None = None
if operation == "runtime.run" and request.method == "POST":
# The receipt outlives results without retaining their payloads.
- def updated(event: Event) -> None:
- if isinstance(event.data, protocol.RunMessage):
- run = event.data.run
- if event.data.request_id == key:
+ def updated(event: RoutedEvent) -> None:
+ if isinstance(event.event, protocol.RunEvent):
+ run = event.event.data.run
+ if event.event.data.request_id == key:
mutation.run = run
if (
run.status == "completed"
@@ -319,13 +320,13 @@ def _watch_lifecycle(
) -> tuple[Callable[[Response], None], Callable[[], None]]:
runtime_id: protocol.RuntimeId | None = None
previous_id: protocol.RuntimeId | None = None
- early: list[Event] = []
+ early: list[RoutedEvent] = []
def settle() -> None:
context.settle(mutation)
unsubscribe()
- def updated(event: Event) -> None:
+ def updated(event: RoutedEvent) -> None:
nonlocal previous_id
if mutation.expires_at is not None:
return
@@ -333,13 +334,13 @@ def _watch_lifecycle(
# A backend can finish synchronously, before the response exists.
early.append(event)
return
- if event.name == "notebook.removed":
+ if isinstance(event.event, protocol.NotebookRemovedEvent):
settle()
- elif isinstance(event.data, protocol.RuntimeMessage):
- runtime = event.data.runtime
+ elif isinstance(event.event, protocol.RuntimeEvent):
+ runtime = event.event.data.runtime
if (
operation == "runtime.restart"
- and event.data.request_id == request_id
+ and event.event.data.request_id == request_id
and runtime.status == "terminating"
and runtime.id != runtime_id
):
@@ -350,12 +351,10 @@ def _watch_lifecycle(
and runtime.status in ("running", "failed")
):
settle()
- elif event.name == "runtime.removed" and isinstance(
- event.data, protocol.RemovedMessage
- ):
- if event.data.id == runtime_id or (
- event.data.id == previous_id
- and event.data.request_id != request_id
+ elif isinstance(event.event, protocol.RuntimeRemovedEvent):
+ if event.event.data.id == runtime_id or (
+ event.event.data.id == previous_id
+ and event.event.data.request_id != request_id
):
# A later stop can cancel a restart before its replacement starts.
settle()
@@ -672,12 +671,14 @@ def _initial_events(
notebook_id: protocol.NotebookId | None,
run_id: str | None = None,
include_session: bool = False,
-) -> list[Event]:
+) -> list[RoutedEvent]:
"""Capture a snapshot or replay, with `ready` marking its end."""
events = bridge.host.events(
cursor, notebook_id=notebook_id, types=types, run_id=run_id
)
- needs_snapshot = cursor is None or events[0].name == "reset"
+ needs_snapshot = cursor is None or isinstance(
+ events[0].event, protocol.ResetEvent
+ )
if include_session and notebook_id is not None and needs_snapshot:
ready = events.pop()
events.extend(
@@ -691,13 +692,13 @@ def _initial_events(
class _EventSubscription:
def __init__(
- self, initial: list[Event], queue: asyncio.Queue[Event]
+ self, initial: list[RoutedEvent], queue: asyncio.Queue[RoutedEvent]
) -> None:
self.initial = initial
self._queue = queue
self._ready_id = initial[-1].id or 0
- async def next(self) -> Event:
+ async def next(self) -> RoutedEvent:
"""Wait for a live event not already covered by the initial state."""
while True:
event = await self._queue.get()
@@ -715,7 +716,7 @@ def _subscribe_events(
run_id: str | None = None,
include_session: bool = False,
) -> Iterator[_EventSubscription]:
- queue: asyncio.Queue[Event] = asyncio.Queue()
+ queue: asyncio.Queue[RoutedEvent] = asyncio.Queue()
# Subscribe and capture state in one event-loop turn to avoid lost updates.
unsubscribe = bridge.host.subscribe(
queue.put_nowait,
@@ -775,13 +776,13 @@ def _stream(
)
-def _frame(event: Event) -> bytes:
+def _frame(event: RoutedEvent) -> bytes:
"""Encode an event as an SSE frame."""
lines = []
if event.id is not None:
lines.append(f"id: {event.id}")
- lines.append(f"event: {event.name}")
- data = b"{}" if event.data is None else msgspec.json.encode(event.data)
+ lines.append(f"event: {event_name(event.event)}")
+ data = msgspec.json.encode(event.event.data)
lines.append(f"data: {data.decode()}")
return ("\n".join(lines) + "\n\n").encode()
diff --git a/marimo/_server/host/bridge.py b/marimo/_server/host/bridge.py
index 94880074d6..8a4c5f5c8b 100644
--- a/marimo/_server/host/bridge.py
+++ b/marimo/_server/host/bridge.py
@@ -38,7 +38,7 @@ if TYPE_CHECKING:
from marimo._config.manager import MarimoConfigManager
from marimo._core.backend import Message
- from marimo._core.stream import Event, Sink
+ from marimo._core.stream import RoutedEvent, Sink
from marimo._messaging.notebook import NotebookCell
from marimo._server.session_manager import SessionManager
from marimo._session.notebook import AppFileManager
@@ -383,7 +383,7 @@ class SessionBridge(SessionEventListener):
def session_snapshot(
self, notebook_id: protocol.NotebookId
- ) -> list[Event]:
+ ) -> list[RoutedEvent]:
"""Return retained marimo events for one client without publishing them."""
session = self._session_of(notebook_id)
if session is None:
@@ -658,8 +658,11 @@ class SessionBridge(SessionEventListener):
self._backends[notebook_id] = backend
return backend
- def _forget_backend(self, event: Event) -> None:
- if event.name == "notebook.removed" and event.notebook_id is not None:
+ def _forget_backend(self, event: RoutedEvent) -> None:
+ if (
+ isinstance(event.event, protocol.NotebookRemovedEvent)
+ and event.notebook_id is not None
+ ):
self._backends.pop(event.notebook_id, None)
self._file_texts.pop(event.notebook_id, None)
self._rebaselining.pop(event.notebook_id, None)
diff --git a/marimo/_server/host/events.py b/marimo/_server/host/events.py
index 07246a34cc..d7b9b10ed4 100644
--- a/marimo/_server/host/events.py
+++ b/marimo/_server/host/events.py
@@ -6,7 +6,7 @@ from __future__ import annotations
import msgspec
from marimo._core import protocol
-from marimo._core.stream import Event
+from marimo._core.stream import ExtensionEvent, RoutedEvent
from marimo._messaging.notification import NotificationMessage
@@ -19,25 +19,24 @@ class MarimoMessage(msgspec.Struct, frozen=True):
marimo: NotificationMessage
+class MarimoEvent(ExtensionEvent, frozen=True, tag="marimo"):
+ """A typed envelope for internal marimo notifications."""
+
+ data: MarimoMessage
+
+
def notification_event(
notebook_id: protocol.NotebookId, notification: NotificationMessage
-) -> Event:
+) -> RoutedEvent:
"""Wrap a notification with its notebook and optional run scope."""
run_id = getattr(notification, "run_id", None)
- return Event(
- "marimo",
- MarimoMessage(notification),
+ return RoutedEvent(
+ MarimoEvent(MarimoMessage(notification)),
notebook_id=notebook_id,
run_id=protocol.RunId(run_id) if run_id is not None else None,
)
-def serialize_event(event: Event) -> str:
+def serialize_event(event: RoutedEvent) -> str:
"""Encode one host event as a WebSocket frame."""
- frame: dict[str, object] = {
- "event": event.name,
- "data": {} if event.data is None else event.data,
- }
- if event.id is not None:
- frame["id"] = str(event.id)
- return msgspec.json.encode(frame).decode()
+ return msgspec.json.encode(event.event).decode()
diff --git a/marimo/_server/host/websocket.py b/marimo/_server/host/websocket.py
index 64609865ff..268a9a01bf 100644
--- a/marimo/_server/host/websocket.py
+++ b/marimo/_server/host/websocket.py
@@ -18,7 +18,7 @@ from marimo._server.api.endpoints.ws.ws_message_loop import (
from marimo._server.api.endpoints.ws.ws_session_connector import ConnectionType
from marimo._server.codes import WebSocketCloseReason, WebSocketCodes
from marimo._server.host.events import (
- MarimoMessage,
+ MarimoEvent,
notification_event,
serialize_event,
)
@@ -29,7 +29,7 @@ if TYPE_CHECKING:
from starlette.websockets import WebSocket
from marimo._core.notebook import Notebook
- from marimo._core.stream import Event
+ from marimo._core.stream import RoutedEvent
from marimo._messaging.types import KernelMessage
from marimo._server.api.endpoints.ws.ws_connection_validator import (
ConnectionParams,
@@ -75,7 +75,7 @@ class EditorEventSocket(SessionHandler):
self.types = types
self.cursor = cursor
self._ready_id = 0
- self._events: asyncio.Queue[Event | _Close] = asyncio.Queue()
+ self._events: asyncio.Queue[RoutedEvent | _Close] = asyncio.Queue()
self._connection_type = (
ConnectionType.RTC_EXISTING
if params.rtc_enabled and not params.kiosk
@@ -89,10 +89,10 @@ class EditorEventSocket(SessionHandler):
if event.wanted(self.types):
self._events.put_nowait(event)
- def _on_host_event(self, event: Event) -> None:
+ def _on_host_event(self, event: RoutedEvent) -> None:
# The session delivers marimo notifications with recipient filtering,
# including edits that must not echo to the client that sent them.
- if event.name != "marimo" and (
+ if not isinstance(event.event, MarimoEvent) and (
event.id is None or event.id > self._ready_id
):
self._events.put_nowait(event)
@@ -112,7 +112,7 @@ class EditorEventSocket(SessionHandler):
for event in initial:
# Session notifications must retain their recipient filtering,
# including on reconnect; only protocol records use replay.
- if event.name != "marimo":
+ if not isinstance(event.event, MarimoEvent):
self._events.put_nowait(event)
await self.websocket.accept()
async with self._connection_lifetime(self.websocket) as startup:
@@ -167,14 +167,14 @@ class EditorEventSocket(SessionHandler):
):
await self.websocket.close(event.code, event.reason)
return
- if isinstance(event.data, MarimoMessage):
+ if isinstance(event.event, MarimoEvent):
viewer = self.params.kiosk
if self._session is not None:
viewer = self._is_viewer(
self._session, self._connection_type
)
if should_filter_operation(
- event.data.marimo.name, is_kiosk=viewer
+ event.event.data.marimo.name, is_kiosk=viewer
):
continue
await self.websocket.send_text(serialize_event(event))
diff --git a/protocols/host/README.md b/protocols/host/README.md
index 831ba13148..8f2ce43e93 100644
--- a/protocols/host/README.md
+++ b/protocols/host/README.md
@@ -9,7 +9,8 @@ notebooks and runtimes.
- [Conformance tests](conformance/README.md)
The OpenAPI schema is the source of truth for the Python types in
-`marimo/_core/protocol.py` and the frontend schemas and types in
+`marimo/_core/protocol.py`, the typed event adapters in
+`marimo/_core/protocol_events.py`, and the frontend schemas and types in
`frontend/src/core/host/protocol.ts`. The frontend generator also adds the
native `marimo` event with an `unknown` payload.
diff --git a/protocols/host/generate.py b/protocols/host/generate.py
index 6332c61fd7..a1619613c6 100644
--- a/protocols/host/generate.py
+++ b/protocols/host/generate.py
@@ -2,6 +2,7 @@
# requires-python = ">=3.11"
# dependencies = [
# "datamodel-code-generator==0.72.0",
+# "jinja2==3.1.6",
# "ruff==0.16.4",
# "msgspec[yaml]==0.22.0"
# ]
@@ -76,6 +77,82 @@ def tuple_arrays(source: bytes) -> bytes:
return source
+def event_adapters(document: dict[str, Any]) -> str:
+ """Derive typed event adapters from the discriminator and schema refs."""
+ from jinja2 import Environment, FileSystemLoader, StrictUndefined
+
+ schemas = document["components"]["schemas"]
+ mapping = schemas["Event"]["discriminator"]["mapping"]
+
+ def reference(value: dict[str, Any]) -> str:
+ ref = value["$ref"]
+ prefix = "#/components/schemas/"
+ if not ref.startswith(prefix):
+ raise ValueError(f"Expected a local schema reference: {ref}")
+ return ref.removeprefix(prefix)
+
+ records = {}
+ removals = []
+ for tag, ref in sorted(mapping.items()):
+ name = reference({"$ref": ref})
+ data = schemas[name]["properties"]["data"]
+ if "$ref" not in data:
+ continue # Control events have no record payload.
+ message = reference(data)
+ if tag.endswith(".removed"):
+ removals.append((tag.removesuffix(".removed"), name, message))
+ continue
+ schema = schemas[message]
+ fields = {
+ field: reference(value)
+ for field, value in schema["properties"].items()
+ if "$ref" in value
+ and schemas[reference(value)].get("type") == "object"
+ and field in schema.get("required", [])
+ }
+ if len(fields) != 1:
+ raise ValueError(f"{message} must contain one required record")
+ field, body = next(iter(fields.items()))
+ if set(schema["properties"]) != {field, "request_id", "time"}:
+ raise ValueError(f"Unsupported event metadata in {message}")
+ records[tag] = {
+ "event": name,
+ "message": message,
+ "body": body,
+ "field": field,
+ "requires_time": "time" in schema.get("required", []),
+ }
+
+ removed = []
+ for tag, name, message in removals:
+ if tag not in records:
+ raise ValueError(f"{name} has no corresponding record event")
+ removed.append({**records[tag], "event": name, "message": message})
+
+ env = Environment(
+ loader=FileSystemLoader(Path(__file__).parent / "templates"),
+ undefined=StrictUndefined,
+ keep_trailing_newline=True,
+ )
+ return env.get_template("events.py.jinja2").render(
+ records=list(records.values()), removals=removed
+ )
+
+
+def format_generated(output_path: Path) -> None:
+ subprocess.run(
+ [
+ "ruff",
+ "format",
+ "--isolated",
+ "--line-length",
+ "79",
+ str(output_path),
+ ],
+ check=True,
+ )
+
+
def generate_models(document: dict[str, Any], output_path: Path) -> None:
from datamodel_code_generator import (
DataModelType,
@@ -124,17 +201,7 @@ def generate_models(document: dict[str, Any], output_path: Path) -> None:
output_path.write_bytes(tuple_arrays(output_path.read_bytes()))
- subprocess.run(
- [
- "ruff",
- "format",
- "--isolated",
- "--line-length",
- "79",
- str(output_path),
- ],
- check=True,
- )
+ format_generated(output_path)
def main() -> None:
@@ -144,20 +211,25 @@ def main() -> None:
parser.add_argument("--check", action="store_true")
args = parser.parse_args()
root = Path(__file__).resolve().parent
- destination = root.parents[1] / "marimo" / "_core" / "protocol.py"
+ destination = root.parents[1] / "marimo" / "_core"
document = sorted_keys(
msgspec.yaml.decode((root / "openapi.yaml").read_bytes())
)
with tempfile.TemporaryDirectory() as directory:
output = Path(directory) / "protocol.py"
generate_models(document, output)
- content = output.read_bytes()
- if not destination.exists() or destination.read_bytes() != content:
- if args.check:
- raise SystemExit(
- "Host models are stale; run make host-protocol-codegen"
- )
- destination.write_bytes(content)
+ adapters = Path(directory) / "protocol_events.py"
+ adapters.write_text(event_adapters(document), encoding="utf-8")
+ format_generated(adapters)
+ for generated in (output, adapters):
+ target = destination / generated.name
+ content = generated.read_bytes()
+ if not target.exists() or target.read_bytes() != content:
+ if args.check:
+ raise SystemExit(
+ "Host bindings are stale; run make host-protocol-codegen"
+ )
+ target.write_bytes(content)
print("Host protocol models are current.")
diff --git a/protocols/host/generate.py.lock b/protocols/host/generate.py.lock
index bb4d3b5eda..88efab3624 100644
--- a/protocols/host/generate.py.lock
+++ b/protocols/host/generate.py.lock
@@ -17,6 +17,7 @@ marimo-lens = false
[manifest]
requirements = [
{ name = "datamodel-code-generator", specifier = "==0.72.0" },
+ { name = "jinja2", specifier = "==3.1.6" },
{ name = "msgspec", extras = ["yaml"], specifier = "==0.22.0" },
{ name = "ruff", specifier = "==0.16.4" },
]
diff --git a/protocols/host/templates/events.py.jinja2 b/protocols/host/templates/events.py.jinja2
new file mode 100644
index 0000000000..8e30625c0d
--- /dev/null
+++ b/protocols/host/templates/events.py.jinja2
@@ -0,0 +1,87 @@
+# Copyright 2026 Marimo. All rights reserved.
+# AUTO-GENERATED FILE — DO NOT EDIT.
+# Generated from protocols/host/openapi.yaml.
+# Regenerate with `make host-protocol-codegen`.
+"""Typed envelope adapters. Payload ownership stays with the caller."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypeAlias, overload
+
+from msgspec import UNSET, UnsetType
+
+from marimo._core import protocol
+
+if TYPE_CHECKING:
+ from datetime import datetime
+
+Body: TypeAlias = {% for r in records %}protocol.{{ r.body }}{{ " | " if not loop.last }}{% endfor %}
+SnapshotBody: TypeAlias = {% for r in records if not r.requires_time %}protocol.{{ r.body }}{{ " | " if not loop.last }}{% endfor %}
+RecordEvent: TypeAlias = {% for r in records %}protocol.{{ r.event }}{{ " | " if not loop.last }}{% endfor %}
+RemovableBody: TypeAlias = {% for r in removals %}protocol.{{ r.body }}{{ " | " if not loop.last }}{% endfor %}
+RemovalEvent: TypeAlias = {% for r in removals %}protocol.{{ r.event }}{{ " | " if not loop.last }}{% endfor %}
+
+{% for r in records %}
+@overload
+def record(
+ value: protocol.{{ r.body }}, *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime{{ "" if r.requires_time else " | UnsetType = UNSET" }},
+) -> protocol.{{ r.event }}: ...
+{% endfor %}
+
+def record(
+ value: Body, *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> RecordEvent:
+ """Wrap a record without copying it; occurrences require a timestamp."""
+ match value:
+{% for r in records %}
+ case protocol.{{ r.body }}():
+{% if r.requires_time %}
+ if isinstance(time, UnsetType):
+ raise ValueError("{{ r.event }} requires an emission time")
+{% endif %}
+ return protocol.{{ r.event }}(
+ protocol.{{ r.message }}({{ r.field }}=value, request_id=request_id, time=time)
+ )
+{% endfor %}
+ raise TypeError(f"Unsupported record type: {type(value)}")
+
+{% for r in records %}
+@overload
+def body(event: protocol.{{ r.event }}) -> protocol.{{ r.body }}: ...
+{% endfor %}
+
+def body(event: RecordEvent) -> Body:
+ """Read a record payload without copying it."""
+ match event:
+{% for r in records %}
+ case protocol.{{ r.event }}(data=data):
+ return data.{{ r.field }}
+{% endfor %}
+ raise TypeError(f"Not a record event: {type(event)}")
+
+{% for r in removals %}
+@overload
+def removed(
+ record_type: type[protocol.{{ r.body }}], object_id: str, *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> protocol.{{ r.event }}: ...
+{% endfor %}
+
+def removed(
+ record_type: type[RemovableBody], object_id: str, *,
+ request_id: str | UnsetType = UNSET,
+ time: datetime | UnsetType = UNSET,
+) -> RemovalEvent:
+ """Construct the removal envelope for a supported record type."""
+{% for r in removals %}
+ if record_type is protocol.{{ r.body }}:
+ return protocol.{{ r.event }}(
+ protocol.{{ r.message }}(id=object_id, request_id=request_id, time=time)
+ )
+{% endfor %}
+ raise TypeError(f"No removal event for {record_type}")
diff --git a/pyproject.toml b/pyproject.toml
index 0c48430564..741186acf8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -171,6 +171,8 @@ test = [
"inline-snapshot~=0.29.0",
"hypothesis~=6.102.1",
"dirty-equals~=0.9.0",
+ # For protocol code generation tests
+ "jinja2>=3.1.6",
# No cp315 wheels as of 2026-10 for matplotlib 3.10 and zstandard; drop the
# python_version markers when published. numpy is listed on its own because
# tests used to get it only through matplotlib.
diff --git a/tests/_core/conftest.py b/tests/_core/conftest.py
index 4c66737dc3..4e96a8fb58 100644
--- a/tests/_core/conftest.py
+++ b/tests/_core/conftest.py
@@ -7,13 +7,13 @@ import asyncio
import pytest
-from marimo._core import backend as be, protocol
+from marimo._core import backend as be, protocol, protocol_events
from marimo._core.document import Document, code_hash
from marimo._core.executions import CellExecution, Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.run_log import RetentionPolicy
-from marimo._core.stream import Event, Sink
+from marimo._core.stream import RoutedEvent, Sink, event_name
OPERATIONS = ["notebook.create", "runtime.start", "runtime.run"]
@@ -155,19 +155,19 @@ async def notebook(host: Host, backend: ScriptedBackend) -> Notebook:
@pytest.fixture
-def log(host: Host) -> list[Event]:
+def log(host: Host) -> list[RoutedEvent]:
"""Collect events published during the test."""
- events: list[Event] = []
+ events: list[RoutedEvent] = []
host.subscribe(events.append, notebook_id="n1")
return events
-def names(events: list[Event]) -> list[str]:
- return [e.name for e in events]
+def names(events: list[RoutedEvent]) -> list[str]:
+ return [event_name(e.event) for e in events]
-def request_ids(events: list[Event]) -> list[object]:
- return [getattr(e.data, "request_id", None) for e in events]
+def request_ids(events: list[RoutedEvent]) -> list[object]:
+ return [getattr(e.event.data, "request_id", None) for e in events]
class Clock:
@@ -221,17 +221,36 @@ def finish(notebook: Notebook, execution: protocol.ExecutionId) -> None:
notebook.observe(be.Status(execution, "completed"))
-def fold(events: list[Event], initial: dict | None = None) -> dict:
+def fold(events: list[RoutedEvent], initial: dict | None = None) -> dict:
state = dict(initial or {})
- for event in events:
- if event.name == "reset":
+ for routed in events:
+ event = routed.event
+ if isinstance(event, protocol.ResetEvent):
state.clear()
- elif event.kind in {"run", "execution", "console", "display"}:
- if event.name.endswith(".removed"):
- state.pop((event.kind, event.data.id), None)
- else:
- body = getattr(event.data, event.kind)
- state[event.kind, body.id] = body
+ elif isinstance(
+ event,
+ (
+ protocol.RunEvent,
+ protocol.ExecutionEvent,
+ protocol.ConsoleEvent,
+ protocol.DisplayEvent,
+ ),
+ ):
+ body = protocol_events.body(event)
+ state[event_name(event), body.id] = body
+ elif isinstance(
+ event,
+ (
+ protocol.RunRemovedEvent,
+ protocol.ExecutionRemovedEvent,
+ protocol.ConsoleRemovedEvent,
+ protocol.DisplayRemovedEvent,
+ ),
+ ):
+ state.pop(
+ (event_name(event).removesuffix(".removed"), event.data.id),
+ None,
+ )
return state
diff --git a/tests/_core/test_executions.py b/tests/_core/test_executions.py
index baae72ac79..b61e2a2b80 100644
--- a/tests/_core/test_executions.py
+++ b/tests/_core/test_executions.py
@@ -16,7 +16,7 @@ from marimo._core.executions import (
Released,
Removed,
)
-from marimo._core.stream import kind_of, utcnow
+from marimo._core.stream import utcnow
from tests._core.conftest import retained_execution
NOTEBOOK = protocol.NotebookId("n1")
@@ -81,9 +81,11 @@ def describe(changes: list[Change]) -> list[str]:
if isinstance(change, Released):
out.append(f"released {change.run_id}")
elif isinstance(change, Removed):
- out.append(f"{change.kind}.removed {change.id}")
+ out.append(
+ f"{change.record_type.__name__.lower()}.removed {change.id}"
+ )
else:
- out.append(f"{kind_of(change)} {change.id}")
+ out.append(f"{type(change).__name__.lower()} {change.id}")
return out
diff --git a/tests/_core/test_host.py b/tests/_core/test_host.py
index ab99ae03ba..a4ded7bb12 100644
--- a/tests/_core/test_host.py
+++ b/tests/_core/test_host.py
@@ -13,7 +13,7 @@ from msgspec.structs import replace
from marimo._core import backend as be, protocol
from marimo._core.errors import NotFound
from marimo._core.host import Host
-from marimo._core.stream import Event, Sink
+from marimo._core.stream import RoutedEvent, Sink, event_name
from tests._core.conftest import (
Clock,
ScriptedBackend,
@@ -42,11 +42,11 @@ def test_a_subscriber_can_remove_a_notebook_after_its_children(
if trigger == "run":
notebook.start()
notebook.observe(be.Running(runtime_id_of(notebook)))
- events: list[Event] = []
+ events: list[RoutedEvent] = []
- def remove(event: Event) -> None:
+ def remove(event: RoutedEvent) -> None:
events.append(event)
- if event.name == trigger:
+ if event_name(event.event) == trigger:
host.remove_notebook(notebook.id)
host.subscribe(remove, notebook_id=notebook.id)
@@ -87,8 +87,8 @@ def test_replacing_a_cell_result_updates_history_before_delivery(
notebook.observe(be.Done(run.id, "succeeded"))
snapshots = []
- def read_snapshot(event: Event) -> None:
- if event.name == "console.removed":
+ def read_snapshot(event: RoutedEvent) -> None:
+ if isinstance(event.event, protocol.ConsoleRemovedEvent):
snapshots.append(set(fold(host.events(notebook_id=notebook.id))))
host.subscribe(read_snapshot, notebook_id=notebook.id)
@@ -125,7 +125,9 @@ async def test_catalog_snapshot_and_replay_exclude_runs(host: Host) -> None:
]
assert all(e.id is None for e in events[:-1])
assert events[-1].id == cursor + 2
- assert all(getattr(e.data, "time", None) is UNSET for e in events[:-1])
+ assert all(
+ getattr(e.event.data, "time", None) is UNSET for e in events[:-1]
+ )
assert names(host.events(cursor)) == ["attachment", "ready"]
@@ -202,9 +204,9 @@ async def test_types_filter_keeps_ready_and_reset(host: Host) -> None:
async def test_subscribe_filters_the_live_stream(host: Host) -> None:
host.update_project(project())
notebook = await add_notebook(host, record(), ScriptedBackend())
- catalog: list[Event] = []
- mine: list[Event] = []
- runtimes: list[Event] = []
+ catalog: list[RoutedEvent] = []
+ mine: list[RoutedEvent] = []
+ runtimes: list[RoutedEvent] = []
host.subscribe(catalog.append)
host.subscribe(mine.append, notebook_id="n1")
unsubscribe = host.subscribe(runtimes.append, types={"runtime"})
@@ -229,7 +231,7 @@ async def test_removing_a_notebook_removes_what_it_owns_first(
notebook.observe(be.Running(runtime_id_of(notebook)))
notebook.attach()
run = notebook.run("1", request_id="r1")
- log: list[Event] = []
+ log: list[RoutedEvent] = []
host.subscribe(log.append, notebook_id="n1")
host.remove_notebook("n1", request_id="req-del")
@@ -241,7 +243,7 @@ async def test_removing_a_notebook_removes_what_it_owns_first(
"run.removed",
"notebook.removed",
]
- assert getattr(log[-1].data, "request_id", None) == "req-del"
+ assert getattr(log[-1].event.data, "request_id", None) == "req-del"
assert "n1" not in host.notebooks
with pytest.raises(NotFound):
(await host.notebook(notebook.id))
@@ -257,7 +259,7 @@ async def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:
run = notebook.run("1", request_id="run")
runtime = notebook.runtime
backend.calls.clear()
- log: list[Event] = []
+ log: list[RoutedEvent] = []
host.subscribe(log.append, notebook_id="n1")
host.update_notebook(record())
@@ -271,15 +273,15 @@ async def test_updating_a_notebook_publishes_only_changes(host: Host) -> None:
assert backend.calls == []
assert host.events(notebook_id="n1", types={"run"})[
0
- ].data == protocol.RunMessage(run=run, request_id="run")
- assert host.events(notebook_id="n1")[0].data == protocol.NotebookMessage(
- notebook=moved
- )
- assert host.events(types={"notebook"})[0].data == protocol.NotebookMessage(
- notebook=moved
- )
+ ].event.data == protocol.RunMessage(run=run, request_id="run")
+ assert host.events(notebook_id="n1")[
+ 0
+ ].event.data == protocol.NotebookMessage(notebook=moved)
+ assert host.events(types={"notebook"})[
+ 0
+ ].event.data == protocol.NotebookMessage(notebook=moved)
assert names(log) == ["notebook"]
- assert getattr(log[0].data, "request_id", None) == "req-mv"
+ assert getattr(log[0].event.data, "request_id", None) == "req-mv"
with pytest.raises(NotFound):
host.update_notebook(record("n9"))
with pytest.raises(ValueError, match="project"):
@@ -293,7 +295,7 @@ def test_removed_notebook_handles_cannot_be_reused(
host: Host,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
) -> None:
runtime, _ = notebook.start()
notebook.observe(be.Running(runtime.id))
@@ -350,9 +352,9 @@ async def test_catalog_updates_do_not_share_mutable_records(
replay = host.events(0, types={"project"})
projects = [
- e.data.project
+ e.event.data.project
for e in replay
- if isinstance(e.data, protocol.ProjectMessage)
+ if isinstance(e.event, protocol.ProjectEvent)
]
assert projects == [
project(),
@@ -523,7 +525,7 @@ async def test_expiration_converges_for_live_replay_and_snapshot(
"console",
"display",
}
- live: list[Event] = []
+ live: list[RoutedEvent] = []
host.subscribe(live.append, notebook_id=notebook.id, run_id=run.id)
clock.now = 9
host.expire()
@@ -536,11 +538,11 @@ async def test_expiration_converges_for_live_replay_and_snapshot(
"execution.removed",
"run.removed",
]
- assert all(event.data.request_id == "request" for event in live)
+ assert all(event.event.data.request_id == "request" for event in live)
replay = host.events(
snapshot[-1].id, notebook_id=notebook.id, run_id=run.id
)
- assert (replay[0].name == "reset") == (history == 2)
+ assert (isinstance(replay[0].event, protocol.ResetEvent)) == (history == 2)
assert (
fold(live, initial)
== fold(replay, initial)
@@ -593,7 +595,7 @@ async def test_run_survives_until_its_last_cell_execution_is_replaced() -> (
finish(notebook, first)
finish(notebook, second)
notebook.observe(be.Done(original.id, "succeeded"))
- live: list[Event] = []
+ live: list[RoutedEvent] = []
host.subscribe(live.append, notebook_id=notebook.id, run_id=original.id)
replacement = notebook.run("code", request_id="replacement")
@@ -732,7 +734,7 @@ async def test_completed_scratch_runs_belong_to_the_host() -> None:
)
)
assert ("execution", execution) in fold(notebook._snapshot())
- live: list[Event] = []
+ live: list[RoutedEvent] = []
host.subscribe(live.append, notebook_id=notebook.id)
finish(notebook, execution)
notebook.observe(be.Done(run.id, "succeeded"))
diff --git a/tests/_core/test_notebook.py b/tests/_core/test_notebook.py
index 8fdf53f026..686a13e2f2 100644
--- a/tests/_core/test_notebook.py
+++ b/tests/_core/test_notebook.py
@@ -12,7 +12,7 @@ from inline_snapshot import snapshot
from msgspec import UNSET
from msgspec.structs import replace
-from marimo._core import backend as be, protocol
+from marimo._core import backend as be, protocol, protocol_events
from marimo._core.document import Document, DocumentCell
from marimo._core.errors import Conflict, NoRuntime, NotFound
from marimo._core.executions import CellExecution, Executions
@@ -44,7 +44,7 @@ from marimo._core.protocol import (
RuntimeMessage,
ValueOutcome,
)
-from marimo._core.stream import Event, Stream
+from marimo._core.stream import RoutedEvent, Stream, event_name
from tests._core.conftest import (
Clock,
ScriptedBackend,
@@ -66,8 +66,16 @@ def published(
) -> tuple[protocol.Document, list[protocol.Cell]]:
"""The document and cell records the notebook publishes."""
events = notebook._snapshot()
- (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]
- cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]
+ (document,) = [
+ e.event.data.document
+ for e in events
+ if isinstance(e.event, protocol.DocumentEvent)
+ ]
+ cells = [
+ e.event.data.cell
+ for e in events
+ if isinstance(e.event, protocol.CellEvent)
+ ]
return document, cells
@@ -110,14 +118,17 @@ class TestStart:
host.events(0, notebook_id=notebook.id),
):
assert [
- event.data.runtime
+ event.event.data.runtime
for event in events
- if isinstance(event.data, RuntimeMessage)
+ if isinstance(event.event.data, RuntimeMessage)
] == [runtime]
assert backend.calls == [("start", runtime.id)]
def test_starts_a_runtime_and_asks_the_backend(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
runtime, created = notebook.start(request_id="req-1")
@@ -128,7 +139,10 @@ class TestStart:
assert request_ids(log) == ["req-1"]
def test_returns_an_existing_runtime_without_starting(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
first, _ = notebook.start()
again, created = notebook.start()
@@ -139,7 +153,7 @@ class TestStart:
assert names(log) == ["runtime"]
def test_request_follows_the_runtime_until_it_settles(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
notebook.start(request_id="req-1")
notebook.observe(
@@ -158,7 +172,7 @@ class TestStart:
assert notebook.runtime.message is None
def test_a_kernel_that_never_comes_up_fails(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
notebook.start(request_id="req-1")
notebook.observe(
@@ -173,7 +187,10 @@ class TestStart:
class TestStop:
def test_stop_cancels_a_pending_restart(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
runtime = running(notebook, backend)
notebook.restart(request_id="restart")
@@ -192,7 +209,10 @@ class TestStop:
notebook.stop()
def test_terminates_then_removes_once_the_kernel_is_gone(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
log.clear()
@@ -211,7 +231,7 @@ class TestStop:
host: Host,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
run = scratch(notebook)
@@ -227,7 +247,7 @@ class TestStop:
"run",
"runtime.removed",
]
- interrupted = log[1].data
+ interrupted = log[1].event.data
assert isinstance(interrupted, ExecutionMessage)
assert interrupted.execution.status == "completed"
assert isinstance(interrupted.execution.outcome, InterruptedOutcome)
@@ -241,7 +261,10 @@ class TestStop:
]
def test_a_failed_runtime_is_removed_at_once(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
notebook.start()
notebook.observe(be.Exited(runtime_id_of(notebook), "boom"))
@@ -260,7 +283,7 @@ class TestStop:
host: Host,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
run = scratch(notebook)
@@ -297,7 +320,10 @@ class TestRestart:
notebook.restart()
def test_replaces_the_runtime_and_keeps_old_results(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
before = running(notebook, backend)
run = scratch(notebook)
@@ -336,7 +362,7 @@ class TestRestart:
"runtime",
"runtime",
]
- execution = log[1].data
+ execution = log[1].event.data
assert isinstance(execution, ExecutionMessage)
assert execution.execution.runtime_id == before.id
assert request_ids(log)[0] == "req-restart"
@@ -362,7 +388,10 @@ class TestRestart:
class TestAdoption:
def test_a_kernel_someone_else_started_is_published(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
adopted = notebook.adopt(lambda _: None)
notebook.observe(
@@ -381,7 +410,10 @@ class TestAdoption:
assert request_ids(log) == [UNSET, UNSET, UNSET]
def test_reports_about_other_kernels_change_nothing(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
stranger = RuntimeId("rt-stranger")
notebook.observe(be.Running(stranger, marimo_version="0.25.0"))
@@ -436,7 +468,7 @@ class TestAdoption:
host: Host,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
run = scratch(notebook)
@@ -449,9 +481,9 @@ class TestAdoption:
assert notebook.runtime.message == "killed"
assert names(log) == ["execution", "run", "runtime"]
[run] = [
- event.data.run
+ event.event.data.run
for event in host.events(notebook_id=notebook.id)
- if isinstance(event.data, RunMessage)
+ if isinstance(event.event.data, RunMessage)
]
assert run.status == "completed"
@@ -482,7 +514,7 @@ class TestRun:
notebook.observe(be.Status(ExecutionId("e1"), "completed"))
notebook.observe(be.Done(run.id, "succeeded"))
cursor = host.events()[-1].id
- live: list[Event] = []
+ live: list[RoutedEvent] = []
unsubscribe = host.subscribe(
live.append, notebook_id=notebook.id, run_id=run.id
)
@@ -517,7 +549,7 @@ class TestRun:
host: Host,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
log.clear()
@@ -558,17 +590,17 @@ class TestRun:
runs = [
data.run
for event in log
- if isinstance(data := event.data, RunMessage)
+ if isinstance(data := event.event.data, RunMessage)
]
executions = [
data.execution
for event in log
- if isinstance(data := event.data, ExecutionMessage)
+ if isinstance(data := event.event.data, ExecutionMessage)
]
consoles = [
data.console
for event in log
- if isinstance(data := event.data, ConsoleMessage)
+ if isinstance(data := event.event.data, ConsoleMessage)
]
assert [run.status for run in runs] == [
"queued",
@@ -583,9 +615,16 @@ class TestRun:
("completed", value("working<pre>9</pre>")),
]
retained = [
- event.data
+ event.event.data
for event in host.events(notebook_id=notebook.id)
- if event.kind in {"run", "execution", "console"}
+ if isinstance(
+ event.event,
+ (
+ protocol.RunEvent,
+ protocol.ExecutionEvent,
+ protocol.ConsoleEvent,
+ ),
+ )
]
assert retained == [
RunMessage(run=runs[-1]),
@@ -649,7 +688,10 @@ class TestRun:
]
def test_one_run_at_a_time(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
first = notebook.run("1", request_id="first")
@@ -657,9 +699,9 @@ class TestRun:
notebook.run("2", request_id="second")
notebook.observe(be.Done(first.id, "succeeded"))
final = next(
- event.data
+ event.event.data
for event in reversed(log)
- if isinstance(event.data, RunMessage)
+ if isinstance(event.event.data, RunMessage)
)
assert isinstance(final, RunMessage)
assert final.run.status == "completed"
@@ -675,16 +717,19 @@ class TestRun:
notebook.observe(be.Produced(console("o1", "e1", "0\n")))
notebook.observe(be.Produced(console("o1", "e1", "0\n1\n")))
items = [
- event.data.console
+ event.event.data.console
for event in host.events(notebook_id=notebook.id)
- if isinstance(event.data, ConsoleMessage)
+ if isinstance(event.event.data, ConsoleMessage)
]
assert len(items) == 1
assert isinstance(items[0], Console)
assert items[0].text == "0\n1\n"
def test_messages_about_unknown_runs_are_ignored(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
log.clear()
@@ -702,7 +747,10 @@ class TestRun:
class TestRunCompletion:
def test_later_work_gets_its_own_run(
- self, notebook: Notebook, backend: ScriptedBackend, log: list[Event]
+ self,
+ notebook: Notebook,
+ backend: ScriptedBackend,
+ log: list[RoutedEvent],
) -> None:
running(notebook, backend)
original = scratch(notebook)
@@ -715,9 +763,9 @@ class TestRunCompletion:
assert request_ids(log) == [UNSET, UNSET]
assert all(event.run_id == "later" for event in log)
final = next(
- event.data
+ event.event.data
for event in reversed(log)
- if isinstance(event.data, RunMessage)
+ if isinstance(event.event.data, RunMessage)
)
assert isinstance(final, RunMessage)
assert final.run.caused_by == "e1"
@@ -728,7 +776,7 @@ class TestRunCompletion:
self,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
outcome: RunOutcome,
) -> None:
running(notebook, backend)
@@ -736,9 +784,9 @@ class TestRunCompletion:
assert run.outcome is None
notebook.observe(be.Done(run.id, outcome))
final = next(
- event.data
+ event.event.data
for event in reversed(log)
- if isinstance(event.data, RunMessage)
+ if isinstance(event.event.data, RunMessage)
)
assert isinstance(final, RunMessage)
assert final.run.status == "completed"
@@ -751,7 +799,7 @@ class TestRunCompletion:
self,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
outcome: RunOutcome,
) -> None:
running(notebook, backend)
@@ -802,9 +850,9 @@ class TestRunCompletion:
notebook.observe(be.Done(run.id, "succeeded"))
notebook.observe(be.Done(run.id, outcome))
final = next(
- event.data
+ event.event.data
for event in reversed(log)
- if isinstance(event.data, RunMessage)
+ if isinstance(event.event.data, RunMessage)
)
assert isinstance(final, RunMessage)
assert final.run.outcome == outcome
@@ -863,7 +911,7 @@ class TestCellResults:
self,
notebook: Notebook,
backend: ScriptedBackend,
- log: list[Event],
+ log: list[RoutedEvent],
same_run: bool,
) -> None:
running(notebook, backend)
@@ -915,9 +963,9 @@ class TestCellResults:
"execution",
]
visible = [
- event.data.execution.id
+ event.event.data.execution.id
for event in notebook._snapshot()
- if isinstance(event.data, ExecutionMessage)
+ if isinstance(event.event.data, ExecutionMessage)
]
assert visible == [new]
notebook.observe(be.Concluded(new, ValueOutcome(None)))
@@ -959,7 +1007,7 @@ class TestCellResults:
class TestAttachments:
def test_api_clients_attach_and_detach(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
att = notebook.attach()
notebook.detach(att.id)
@@ -970,7 +1018,7 @@ class TestAttachments:
assert names(log) == ["attachment", "attachment.removed"]
def test_one_identity_attaches_separately(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
first = notebook.attach(identity="k1", kind="agent", name="Codex")
second = notebook.attach(identity="k1", kind="agent", name="Codex")
@@ -981,7 +1029,7 @@ class TestAttachments:
assert _attachment_ids(notebook) == {first.id, second.id}
def test_detach_leaves_other_attachments_with_the_identity(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
first = notebook.attach(identity="k1")
second = notebook.attach(identity="k1")
@@ -993,39 +1041,39 @@ class TestAttachments:
assert _attachment_ids(notebook) == {second.id}
def test_attach_without_an_identity_omits_it_on_the_wire(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
att = notebook.attach()
assert att.identity is UNSET
- wire = msgspec.json.decode(msgspec.json.encode(log[0].data))
+ wire = msgspec.json.decode(msgspec.json.encode(log[0].event.data))
assert "identity" not in wire["attachment"]
class TestEmit:
def test_emit_publishes_a_custom_event_on_the_notebook_stream(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
custom = notebook.emit("marimo.test", {"hello": 1}, request_id="req-1")
assert custom == Custom(type="marimo.test", data={"hello": 1})
assert names(log) == ["custom"]
assert log[0].notebook_id == notebook.id
- published = log[0].data
+ published = log[0].event.data
assert isinstance(published, CustomMessage)
assert published.custom == custom
assert published.request_id == "req-1"
assert published.time is not UNSET
def test_emit_rejects_data_that_is_not_json(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
with pytest.raises(TypeError):
notebook.emit("marimo.test", object())
assert "custom" not in names(log)
def test_emit_rejects_an_empty_type(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
with pytest.raises(ValueError):
notebook.emit("", 1)
@@ -1041,9 +1089,9 @@ class TestEmit:
def _attachment_ids(notebook: Notebook) -> set[str]:
return {
- event.data.attachment.id
+ event.event.data.attachment.id
for event in notebook._snapshot()
- if isinstance(event.data, AttachmentMessage)
+ if isinstance(event.event.data, AttachmentMessage)
}
@@ -1085,15 +1133,17 @@ async def test_outputs_follow_their_execution_through_updates_and_removal(
notebook.observe(be.Done(run.id, "succeeded"))
initial = host.events(notebook_id=notebook.id)
assert [
- getattr(event.data, event.kind)
+ protocol_events.body(event.event)
for event in initial
- if event.kind in {"console", "display"}
+ if isinstance(
+ event.event, (protocol.ConsoleEvent, protocol.DisplayEvent)
+ )
] == [first_console, first_display, second_console, second_display]
- live: list[Event] = []
+ live: list[RoutedEvent] = []
snapshots: list[dict] = []
- def updated(event: Event) -> None:
+ def updated(event: RoutedEvent) -> None:
live.append(event)
snapshots.append(fold(notebook._snapshot()))
@@ -1112,9 +1162,9 @@ async def test_outputs_follow_their_execution_through_updates_and_removal(
host.remove_notebook(notebook.id)
assert [
- (event.name, event.data.id)
+ (event_name(event.event), event.event.data.id)
for event in live
- if event.name.endswith(".removed")
+ if isinstance(event.event, protocol_events.RemovalEvent)
] == [
("console.removed", first_console.id),
("display.removed", first_display.id),
@@ -1135,7 +1185,7 @@ async def test_outputs_follow_their_execution_through_updates_and_removal(
assert all(
("execution", first) not in state
for event, state in zip(live, snapshots, strict=True)
- if event.name.endswith(".removed")
+ if isinstance(event.event, protocol_events.RemovalEvent)
)
@@ -1158,7 +1208,7 @@ async def test_initial_results_are_published_and_replaced_by_live_execution(
saved_etag=document.etag,
),
)
- live: list[Event] = []
+ live: list[RoutedEvent] = []
host.subscribe(live.append, notebook_id=record().id)
notebook = await host.notebook(record().id)
assert notebook.runtime is None
@@ -1271,9 +1321,11 @@ def test_restoration_preserves_revisions_and_outputs(
assert notebook.executions.current(CellId("c1")) == retained
assert backend.calls == []
outputs = [
- e for e in notebook._snapshot() if e.kind in ("console", "display")
+ protocol_events.body(e.event)
+ for e in notebook._snapshot()
+ if isinstance(e.event, (protocol.ConsoleEvent, protocol.DisplayEvent))
]
- assert [getattr(e.data, e.kind).seq for e in outputs] == [0, 1, 2]
+ assert [output.seq for output in outputs] == [0, 1, 2]
# Restoration copies the supplied records.
document_record.app_config["width"] = "medium"
assert published(notebook) == published(original)
@@ -1301,7 +1353,7 @@ async def test_edits_preserve_results_and_deletion_removes_them() -> None:
assert (
next(iter(notebook.document)).code_hash != retained.execution.code_hash
)
- live: list[Event] = []
+ live: list[RoutedEvent] = []
host.subscribe(live.append, notebook_id=notebook.id)
notebook.replace([], {})
assert list(notebook.document) == []
@@ -1369,7 +1421,7 @@ async def test_source_edits_keep_live_results_until_the_cell_is_deleted() -> (
notebook.replace([DocumentCell("c1", "43")], {})
assert notebook.executions._records() == retained
- live: list[Event] = []
+ live: list[RoutedEvent] = []
host.subscribe(live.append, notebook_id=notebook.id)
notebook.replace([], {})
assert list(notebook.document) == []
diff --git a/tests/_core/test_notebook_document.py b/tests/_core/test_notebook_document.py
index 5ce83dc880..405963e9f4 100644
--- a/tests/_core/test_notebook_document.py
+++ b/tests/_core/test_notebook_document.py
@@ -24,7 +24,7 @@ from marimo._core.errors import EditConflict, Invalid
from marimo._core.executions import Executions
from marimo._core.host import Host
from marimo._core.notebook import Notebook
-from marimo._core.stream import Event, Stream
+from marimo._core.stream import RoutedEvent, Stream
from tests._core.conftest import (
ScriptedAnalyzer,
ScriptedBackend,
@@ -104,8 +104,16 @@ def records(
) -> tuple[protocol.Document, list[protocol.Cell]]:
"""The document and cell records the notebook publishes."""
events = notebook._snapshot()
- (document,) = [e.data.document for e in events if e.kind == "document"] # type: ignore[union-attr]
- cells = [e.data.cell for e in events if e.kind == "cell"] # type: ignore[union-attr]
+ (document,) = [
+ e.event.data.document
+ for e in events
+ if isinstance(e.event, protocol.DocumentEvent)
+ ]
+ cells = [
+ e.event.data.cell
+ for e in events
+ if isinstance(e.event, protocol.CellEvent)
+ ]
return document, cells
@@ -503,17 +511,17 @@ class TestNotebook:
self,
host: Host,
notebook: Notebook,
- log: list[Event],
+ log: list[RoutedEvent],
method: str,
remove: bool,
) -> None:
notebook.replace([cell("c1", "0")], {})
log.clear()
- def change_again(event: Event) -> None:
+ def change_again(event: RoutedEvent) -> None:
if (
- isinstance(event.data, protocol.CellMessage)
- and event.data.request_id == "first"
+ isinstance(event.event, protocol.CellEvent)
+ and event.event.data.request_id == "first"
):
change = delete("c1", "*") if remove else put("c1", "2", "*")
notebook.edit([change], request_id="second")
@@ -527,11 +535,11 @@ class TestNotebook:
)
first_cell, first_document = log[:2]
- assert isinstance(first_cell.data, protocol.CellMessage)
- assert isinstance(first_document.data, protocol.DocumentMessage)
- published = first_cell.data.cell
+ assert isinstance(first_cell.event, protocol.CellEvent)
+ assert isinstance(first_document.event, protocol.DocumentEvent)
+ published = first_cell.event.data.cell
assert response == protocol.EditResponse(
- document=first_document.data.document,
+ document=first_document.event.data.document,
cells={
"c1": protocol.CellVersion(
etag=published.etag,
@@ -545,7 +553,7 @@ class TestNotebook:
)
async def test_initialization_publishes_cells_then_the_document(
- self, host: Host, log: list[Event]
+ self, host: Host, log: list[RoutedEvent]
) -> None:
host.update_project(project())
host.add_notebook(
@@ -577,7 +585,7 @@ class TestNotebook:
assert "cell" not in names(host.events())
def test_replace_publishes_what_changed(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
notebook.replace(fixture_cells(), {})
log.clear()
@@ -592,11 +600,11 @@ class TestNotebook:
)
assert names(log) == ["cell", "cell.removed", "document"]
- assert all(e.data.request_id == "edit-1" for e in log) # type: ignore[union-attr]
- assert log[1].data.id == "k7f2" # type: ignore[union-attr]
+ assert all(e.event.data.request_id == "edit-1" for e in log) # type: ignore[union-attr]
+ assert log[1].event.data.id == "k7f2" # type: ignore[union-attr]
def test_replace_can_record_the_saved_revision(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
notebook.replace(fixture_cells(), {})
log.clear()
@@ -612,10 +620,10 @@ class TestNotebook:
"cell.removed",
"document",
]
- assert log[-1].data.document == response.document # type: ignore[union-attr]
+ assert log[-1].event.data.document == response.document # type: ignore[union-attr]
def test_mark_saved_records_the_revision_that_was_written(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
notebook.replace(fixture_cells(), {})
written = notebook.document.etag
@@ -628,13 +636,13 @@ class TestNotebook:
assert document.etag != written
assert names(log) == ["document"]
assert request_ids(log) == ["save-1"]
- assert log[0].data.document == document # type: ignore[union-attr]
+ assert log[0].event.data.document == document # type: ignore[union-attr]
# Marking the same revision again publishes nothing.
assert notebook.mark_saved(written) == document
assert names(log) == ["document"]
def test_edit_publishes_as_one_unit_with_the_request_key(
- self, notebook: Notebook, log: list[Event]
+ self, notebook: Notebook, log: list[RoutedEvent]
) -> None:
notebook.replace(fixture_cells(), {})
log.clear()
@@ -651,7 +659,7 @@ class TestNotebook:
assert names(log) == ["cell", "cell.removed", "document"]
assert request_ids(log) == ["edit-1"] * 3
- assert response.document == log[-1].data.document # type: ignore[union-attr]
+ assert response.document == log[-1].event.data.document # type: ignore[union-attr]
assert set(response.cells) == {"c2", "k7f2"}
@@ -667,7 +675,7 @@ def cell_analyses(
class TestAnalysis:
async def test_the_initial_revision_is_analyzed_and_published_after_the_document(
- self, host: Host, log: list[Event]
+ self, host: Host, log: list[RoutedEvent]
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
@@ -705,7 +713,7 @@ class TestAnalysis:
]
async def test_edits_during_analysis_are_analyzed_once_afterwards(
- self, host: Host, log: list[Event]
+ self, host: Host, log: list[RoutedEvent]
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
@@ -745,7 +753,7 @@ class TestAnalysis:
assert notebook.analysis.document_etag == latest.etag
async def test_an_edit_is_analyzed_under_its_request_key(
- self, host: Host, log: list[Event]
+ self, host: Host, log: list[RoutedEvent]
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
@@ -809,7 +817,7 @@ class TestAnalysis:
@pytest.mark.parametrize("edit_while_running", [False, True])
async def test_a_failed_analysis_leaves_the_notebook_ready_for_the_next(
- self, host: Host, log: list[Event], edit_while_running: bool
+ self, host: Host, log: list[RoutedEvent], edit_while_running: bool
) -> None:
host.update_project(project())
analyzer = ScriptedAnalyzer()
@@ -839,7 +847,7 @@ class TestAnalysis:
assert names(log) == ["analysis"]
async def test_removal_discards_a_result_even_if_cancellation_is_suppressed(
- self, host: Host, log: list[Event]
+ self, host: Host, log: list[RoutedEvent]
) -> None:
started, cancelled = asyncio.Event(), asyncio.Event()
result = asyncio.get_running_loop().create_future()
diff --git a/tests/_core/test_protocol.py b/tests/_core/test_protocol.py
index 6dc3a8d6cd..fa6cc22ab0 100644
--- a/tests/_core/test_protocol.py
+++ b/tests/_core/test_protocol.py
@@ -12,7 +12,7 @@ from typing import Any
import msgspec
import pytest
-from marimo._core import protocol
+from marimo._core import protocol, protocol_events
FIXTURES = (
Path(__file__).resolve().parents[2] / "protocols" / "host" / "fixtures"
@@ -171,6 +171,38 @@ def test_stream_models(path: Path) -> None:
assert not snapshot, f"{path.name}: incomplete snapshot"
+ "path", sorted(FIXTURES.glob("*.sse")), ids=lambda path: path.name
+)
+def test_produced_events_match_wire_fixtures(path: Path) -> None:
+ for frame in stream_events(path):
+ expected = {**frame, "data": json.loads(frame["data"])}
+ wire = msgspec.json.decode(json.dumps(expected), type=protocol.Event)
+ if isinstance(wire, (protocol.ReadyEvent, protocol.ResetEvent)):
+ continue
+ if isinstance(wire, protocol_events.RemovalEvent):
+ record_type = getattr(
+ protocol, frame["event"].removesuffix(".removed").title()
+ )
+ produced = protocol_events.removed(
+ record_type,
+ wire.data.id,
+ request_id=wire.data.request_id,
+ time=wire.data.time,
+ )
+ else:
+ value = protocol_events.body(wire)
+ produced = protocol_events.record(
+ value, request_id=wire.data.request_id, time=wire.data.time
+ )
+ assert protocol_events.body(produced) is value
+ # The stream assigns cursors independently of constructing envelopes.
+ encoded = msgspec.json.encode(
+ msgspec.structs.replace(produced, id=wire.id)
+ )
+ assert json.loads(encoded) == expected
+
+
def test_custom_event_replay_preserves_envelope_and_cursor() -> None:
live = stream_events(FIXTURES / "custom-events.sse")
replay = stream_events(FIXTURES / "custom-events-replay.sse")
diff --git a/tests/_core/test_stream.py b/tests/_core/test_stream.py
index 23a42efbd5..e3c0c05962 100644
--- a/tests/_core/test_stream.py
+++ b/tests/_core/test_stream.py
@@ -8,17 +8,16 @@ from typing import get_args
import msgspec
import pytest
-from marimo._core import backend as be, protocol
+from marimo._core import backend as be, protocol, protocol_events
from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.stream import (
- CATALOG_KINDS,
- NOTEBOOK_KINDS,
- Body,
- Event,
+ ExtensionEvent,
+ RoutedEvent,
Stream,
- kind_of,
- message,
+ event_name,
+ removal,
+ utcnow,
)
from tests._core.conftest import ScriptedBackend, names, project
@@ -28,29 +27,29 @@ def test_subscriber_failure_does_not_prevent_startup(
notebook: Notebook,
backend: ScriptedBackend,
) -> None:
- def fail(_event: Event) -> None:
+ def fail(_event: RoutedEvent) -> None:
raise RuntimeError("subscriber failed")
host.subscribe(fail)
- delivered: list[Event] = []
+ delivered: list[RoutedEvent] = []
host.subscribe(delivered.append)
runtime, created = notebook.start()
assert created
assert backend.calls == [("start", runtime.id)]
- assert [e.name for e in delivered] == ["runtime"]
+ assert [event_name(e.event) for e in delivered] == ["runtime"]
def test_nested_publications_follow_the_current_event() -> None:
stream = Stream()
- def publish_another(event: Event) -> None:
+ def publish_another(event: RoutedEvent) -> None:
if event.id == 1:
stream.publish(project("p2"))
stream.subscribe(publish_another)
- delivered: list[Event] = []
+ delivered: list[RoutedEvent] = []
stream.subscribe(delivered.append)
stream.publish(project())
@@ -62,40 +61,40 @@ def test_nested_publications_follow_the_current_event() -> None:
def test_readers_cannot_change_other_readers_or_replay() -> None:
stream = Stream()
- def mutate(event: Event) -> None:
- assert isinstance(event.data, protocol.ProjectMessage)
+ def mutate(event: RoutedEvent) -> None:
+ assert isinstance(event.event, protocol.ProjectEvent)
with pytest.raises(AttributeError):
- event.data.project.name = "subscriber mutation"
+ event.event.data.project.name = "subscriber mutation"
with pytest.raises(AttributeError):
- event.data.project.operations.clear()
+ event.event.data.project.operations.clear()
stream.subscribe(mutate)
- delivered: list[Event] = []
+ delivered: list[RoutedEvent] = []
stream.subscribe(delivered.append)
original = project()
published = stream.publish(original)
with pytest.raises(AttributeError):
original.name = "caller mutation"
- assert isinstance(published.data, protocol.ProjectMessage)
- assert published.data.project == project()
+ assert isinstance(published.event, protocol.ProjectEvent)
+ assert published.event.data.project == project()
with pytest.raises(AttributeError):
- published.data.project.name = "return value mutation"
- assert isinstance(delivered[0].data, protocol.ProjectMessage)
- assert delivered[0].data.project == project()
+ published.event.data.project.name = "return value mutation"
+ assert isinstance(delivered[0].event, protocol.ProjectEvent)
+ assert delivered[0].event.data.project == project()
with pytest.raises(AttributeError):
- delivered[0].data.project.name = "listener mutation"
+ delivered[0].event.data.project.name = "listener mutation"
replay = stream.since(0)
assert replay is not None
- assert isinstance(replay[0].data, protocol.ProjectMessage)
- assert replay[0].data.project == project()
+ assert isinstance(replay[0].event, protocol.ProjectEvent)
+ assert replay[0].event.data.project == project()
with pytest.raises(AttributeError):
- replay[0].data.project.name = "replay mutation"
+ replay[0].event.data.project.name = "replay mutation"
reread = stream.since(0)
assert reread is not None
- assert isinstance(reread[0].data, protocol.ProjectMessage)
- assert reread[0].data.project == project()
+ assert isinstance(reread[0].event, protocol.ProjectEvent)
+ assert reread[0].event.data.project == project()
@pytest.mark.parametrize("external", [False, True])
@@ -107,28 +106,31 @@ def test_mutable_payloads_are_isolated_from_callers_and_listeners(
sink = notebook.sink if via_notebook else stream
cursor = stream.last_id
payload = protocol.Custom(type="example", data={"values": [1]})
- delivered: list[Event] = []
+ delivered: list[RoutedEvent] = []
- def mutate(event: Event) -> None:
- assert isinstance(event.data, protocol.CustomMessage)
- event.data.custom.data["values"].append(2)
+ def mutate(event: RoutedEvent) -> None:
+ assert isinstance(event.event, protocol.CustomEvent)
+ event.event.data.custom.data["values"].append(2)
stream.subscribe(mutate)
stream.subscribe(delivered.append)
if external:
- event = Event(
- "custom",
- protocol.CustomMessage(custom=payload, time=msgspec.UNSET),
+ event = RoutedEvent(
+ protocol.CustomEvent(
+ protocol.CustomMessage(custom=payload, time=utcnow())
+ ),
)
published = sink.append(event)
else:
published = sink.publish(payload)
payload.data["values"].append(3)
- assert isinstance(published.data, protocol.CustomMessage)
- published.data.custom.data["values"].append(4)
+ assert isinstance(published.event, protocol.CustomEvent)
+ published.event.data.custom.data["values"].append(4)
replay = stream.since(cursor)
assert replay is not None
- assert [event.data.custom.data for event in [*delivered, *replay]] == [
+ assert [
+ event.event.data.custom.data for event in [*delivered, *replay]
+ ] == [
{"values": [1]},
{"values": [1]},
]
@@ -136,7 +138,7 @@ def test_mutable_payloads_are_isolated_from_callers_and_listeners(
def test_deferred_events_join_history_before_delivery() -> None:
stream = Stream()
- delivered: list[Event] = []
+ delivered: list[RoutedEvent] = []
stream.subscribe(delivered.append)
with stream.deferred():
@@ -150,8 +152,8 @@ def test_deferred_events_join_history_before_delivery() -> None:
def test_subscribers_act_after_the_command_reaches_the_backend(
host: Host, notebook: Notebook, backend: ScriptedBackend
) -> None:
- def stop_on_starting(event: Event) -> None:
- if event.name == "runtime":
+ def stop_on_starting(event: RoutedEvent) -> None:
+ if isinstance(event.event, protocol.RuntimeEvent):
notebook.stop()
host.subscribe(stop_on_starting, types={"runtime"})
@@ -172,8 +174,8 @@ def test_subscribers_cannot_interrupt_a_restart(
backend.calls.clear()
started: list[tuple[protocol.Runtime, bool]] = []
- def start_on_removal(event: Event) -> None:
- if event.name == "runtime.removed":
+ def start_on_removal(event: RoutedEvent) -> None:
+ if isinstance(event.event, protocol.RuntimeRemovedEvent):
started.append(notebook.start())
host.subscribe(start_on_removal, types={"runtime"})
@@ -193,8 +195,8 @@ def test_subscribers_cannot_start_a_runtime_during_adoption(
started: list[tuple[protocol.Runtime, bool]] = []
attached: list[protocol.RuntimeId] = []
- def start_on_removal(event: Event) -> None:
- if event.name == "runtime.removed":
+ def start_on_removal(event: RoutedEvent) -> None:
+ if isinstance(event.event, protocol.RuntimeRemovedEvent):
started.append(notebook.start())
host.subscribe(start_on_removal, types={"runtime"})
@@ -213,9 +215,8 @@ def test_custom_events_are_on_the_notebook_stream_only(
) -> None:
cursor = host.events(notebook_id=notebook.id)[-1].id
assert cursor is not None
- custom = notebook.emit("marimo.test", {"hello": 1})
+ notebook.emit("marimo.test", {"hello": 1})
- assert kind_of(custom) == "custom"
assert names(host.events(cursor, notebook_id=notebook.id)) == [
"custom",
"ready",
@@ -232,18 +233,56 @@ def test_custom_events_are_on_the_notebook_stream_only(
assert names(replayed) == ["custom"]
-def test_every_body_has_a_kind_a_stream_and_a_message() -> None:
- kinds = {body_type.__name__.lower() for body_type in get_args(Body)}
- assert kinds == CATALOG_KINDS | NOTEBOOK_KINDS
- assert CATALOG_KINDS - NOTEBOOK_KINDS == {"host", "project"}
- for body_type in get_args(Body):
+def test_every_body_has_a_kind_a_stream_and_a_typed_event() -> None:
+ for body_type in get_args(protocol_events.Body):
kind = body_type.__name__.lower()
- wrapper = type(message(_blank(body_type)))
+ event = Stream().publish(
+ _blank(body_type),
+ notebook_id=protocol.NotebookId("n1"),
+ )
+ assert type(event.event).__name__ == f"{body_type.__name__}Event"
+ assert event_name(event.event) == kind
+ wrapper = type(event.event.data)
assert wrapper.__name__ == f"{body_type.__name__}Message"
assert kind in {
field.name for field in msgspec.structs.fields(wrapper)
}
- assert kind_of(_blank(body_type)) == kind
+ assert event.wanted({kind})
+ assert not event.wanted({"unknown"})
+ assert protocol_events.body(event.event) == _blank(body_type)
+ assert event.visible_in(None) == (
+ kind in {"host", "project", "notebook", "runtime", "attachment"}
+ )
+ assert event.visible_in("n1") == (kind not in {"host", "project"})
+ assert not event.visible_in("n2")
+
+
+ "record_type", get_args(protocol_events.RemovableBody)
+)
+def test_removals_preserve_scope_and_type_filters(
+ record_type: type[protocol_events.RemovableBody],
+) -> None:
+ kind = record_type.__name__.lower()
+ event = removal(record_type, "item", notebook_id=protocol.NotebookId("n1"))
+ assert event.visible_in(None) == (
+ kind in {"project", "notebook", "runtime", "attachment"}
+ )
+ assert event.visible_in("n1") == (kind != "project")
+ assert not event.visible_in("n2")
+ assert event.wanted({kind})
+ assert not event.wanted({"host"})
+
+
+def test_extension_type_filters_preserve_the_full_wire_name() -> None:
+ class Extension(ExtensionEvent, tag="extension.removed"):
+ pass
+
+ event = RoutedEvent(Extension(protocol.RemovedMessage(id="item")))
+ assert [
+ event.wanted(types)
+ for types in (None, {"extension.removed"}, {"extension"})
+ ] == [True, True, False]
def _blank(body_type: type[msgspec.Struct]) -> msgspec.Struct:
diff --git a/tests/_lint/test_host_protocol_codegen.py b/tests/_lint/test_host_protocol_codegen.py
index 873b5f4898..ad56a89f77 100644
--- a/tests/_lint/test_host_protocol_codegen.py
+++ b/tests/_lint/test_host_protocol_codegen.py
@@ -2,10 +2,15 @@
from __future__ import annotations
+from datetime import datetime
+from pathlib import Path
+
import msgspec
+import msgspec.yaml
import pytest
-from protocols.host.generate import tuple_arrays
+from marimo._core import protocol
+from protocols.host.generate import event_adapters, tuple_arrays
@pytest.mark.parametrize(
@@ -44,3 +49,56 @@ class Example(Struct, frozen=True):
assert value.xs == ("a",)
assert value.value == "after"
assert value.rows == ((1, 2),)
+
+
+def test_event_adapters_follow_schema_references(
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ """Record access does not depend on names matching the wire tag."""
+ document = msgspec.yaml.decode(
+ Path("protocols/host/openapi.yaml").read_bytes()
+ )
+ schemas = document["components"]["schemas"]
+ message = schemas.pop("ProjectMessage")
+ message["properties"]["workspace"] = message["properties"].pop("project")
+ message["required"] = ["workspace"]
+ schemas["WorkspaceUpdate"] = message
+ event = schemas.pop("ProjectEvent")
+ event["properties"]["data"]["$ref"] = (
+ "#/components/schemas/WorkspaceUpdate"
+ )
+ schemas["WorkspaceChanged"] = event
+ schemas["Event"]["discriminator"]["mapping"]["project"] = (
+ "#/components/schemas/WorkspaceChanged"
+ )
+ update_type = msgspec.defstruct(
+ "WorkspaceUpdate",
+ [
+ ("workspace", protocol.Project),
+ ("request_id", str | msgspec.UnsetType, msgspec.UNSET),
+ ("time", datetime | msgspec.UnsetType, msgspec.UNSET),
+ ],
+ )
+ event_type = msgspec.defstruct("WorkspaceChanged", [("data", update_type)])
+ monkeypatch.setattr(
+ protocol, "WorkspaceUpdate", update_type, raising=False
+ )
+ monkeypatch.setattr(
+ protocol, "WorkspaceChanged", event_type, raising=False
+ )
+ namespace = {}
+ exec(compile(event_adapters(document), "<adapters>", "exec"), namespace)
+ project = protocol.Project(
+ id=protocol.ProjectId("p1"),
+ name="project",
+ root="/tmp",
+ message=None,
+ operations=(),
+ status="ready",
+ )
+ wrapped = namespace["record"](project)
+ assert wrapped == event_type(update_type(project))
+ assert namespace["body"](wrapped) is project
+ assert namespace["removed"](protocol.Project, project.id) == (
+ protocol.ProjectRemovedEvent(protocol.RemovedMessage(id="p1"))
+ )
diff --git a/tests/_server/host/test_host_api.py b/tests/_server/host/test_host_api.py
index 3bfcc69073..384d292819 100644
--- a/tests/_server/host/test_host_api.py
+++ b/tests/_server/host/test_host_api.py
@@ -21,12 +21,12 @@ from marimo._core.host import Host
from marimo._core.notebook import Notebook
from marimo._core.protocol import ProjectMessage
from marimo._core.run_log import RetentionPolicy
-from marimo._core.stream import Event
+from marimo._core.stream import RoutedEvent, event_name
from marimo._messaging.notification import CompletedRunNotification
from marimo._server.host import HOST_API_PATH, api as api_module
from marimo._server.host.bridge import SessionBridge
from marimo._server.host.context import HostContext
-from marimo._server.host.events import MarimoMessage
+from marimo._server.host.events import MarimoEvent, MarimoMessage
from marimo._server.host.index import WorkspaceIndex
from marimo._server.main import create_starlette_app
from marimo._server.models.home import MarimoFile
@@ -553,7 +553,10 @@ async def test_a_notebook_stream_attaches_the_client(harness: Harness) -> None:
disconnect()
await asyncio.wait_for(task, 5)
- assert [e.name for e in harness.host.events(notebook_id=notebook.id)] == [
+ assert [
+ event_name(e.event)
+ for e in harness.host.events(notebook_id=notebook.id)
+ ] == [
"notebook",
"cell",
"document",
@@ -622,7 +625,9 @@ async def test_a_reconnect_with_one_identity_attaches_fresh(
old = first.records[0]["data"]["attachment"]
disconnect_first()
await asyncio.wait_for(first_task, 5)
- assert "attachment" not in [e.name for e in harness.host.events()]
+ assert "attachment" not in [
+ event_name(e.event) for e in harness.host.events()
+ ]
second, second_task, disconnect_second = request(
harness.app,
@@ -1143,7 +1148,10 @@ async def test_request_receipts_expire_independently_of_results(
assert replayed.json()["status"] == "completed"
assert replayed.json()["outcome"] == "succeeded"
assert any(
- event.kind == "execution"
+ isinstance(
+ event.event,
+ (protocol.ExecutionEvent, protocol.ExecutionRemovedEvent),
+ )
for event in harness.host.events(notebook_id=nid)
) == (cell_id is not None)
conflicting = await finished(
@@ -1381,9 +1389,9 @@ async def test_operations_the_host_does_not_offer_are_501(
notebook = await harness.host.notebook(harness.notebook_id)
host = Host(operations=[])
[project] = [
- e.data.project
+ e.event.data.project
for e in harness.host.events()
- if isinstance(e.data, ProjectMessage)
+ if isinstance(e.event.data, ProjectMessage)
]
host.update_project(project)
host.add_notebook(harness.host.notebooks[notebook.id], make_notebook)
@@ -1959,7 +1967,7 @@ async def test_marimo_notifications_use_their_own_sse_kind(
await wait_for(response, until_ready)
payload = MarimoMessage(CompletedRunNotification(run_id="r1"))
published = notebook.sink.append(
- Event("marimo", payload, notebook_id=notebook.id)
+ RoutedEvent(MarimoEvent(payload), notebook_id=notebook.id)
)
await wait_for(response, lambda r: "marimo" in r.names())
assert [r for r in response.records if r.get("event") == "marimo"] == [
@@ -1994,7 +2002,9 @@ def test_websocket_delivers_live_events(harness: Harness, query: str) -> None:
)
client.portal.call(analyzed, notebook)
payload = MarimoMessage(CompletedRunNotification(run_id="r1"))
- event = Event("marimo", payload, notebook_id=notebook.id, run_id="r1")
+ event = RoutedEvent(
+ MarimoEvent(payload), notebook_id=notebook.id, run_id="r1"
+ )
client.portal.call(notebook.sink.append, event)
path = f"{HOST_API_PATH}/notebooks/{notebook.id}/events/ws{query}"
with client.websocket_connect(
@@ -2004,13 +2014,17 @@ def test_websocket_delivers_live_events(harness: Harness, query: str) -> None:
assert all("id" not in event for event in initial[:-1])
client.portal.call(
notebook.sink.append,
- Event("marimo", payload, notebook_id="nb_other", run_id="r1"),
+ RoutedEvent(
+ MarimoEvent(payload), notebook_id="nb_other", run_id="r1"
+ ),
)
if "run_id" in query:
client.portal.call(
notebook.sink.append,
- Event(
- "marimo", payload, notebook_id=notebook.id, run_id="r2"
+ RoutedEvent(
+ MarimoEvent(payload),
+ notebook_id=notebook.id,
+ run_id="r2",
),
)
first = client.portal.call(notebook.sink.append, event)
@@ -2060,12 +2074,15 @@ def test_websocket_disconnect_detaches_the_client(
)
client.portal.call(analyzed, notebook)
removed = asyncio.Event()
- events: list[Event] = []
+ events: list[RoutedEvent] = []
- def observe(event: Event) -> None:
- if event.notebook_id == notebook.id and event.kind == "attachment":
+ def observe(event: RoutedEvent) -> None:
+ if event.notebook_id == notebook.id and isinstance(
+ event.event,
+ (protocol.AttachmentEvent, protocol.AttachmentRemovedEvent),
+ ):
events.append(event)
- if event.name == "attachment.removed":
+ if isinstance(event.event, protocol.AttachmentRemovedEvent):
removed.set()
unsubscribe = client.portal.call(harness.host.subscribe, observe)
@@ -2083,13 +2100,15 @@ def test_websocket_disconnect_detaches_the_client(
else:
websocket.close()
client.portal.call(asyncio.wait_for, removed.wait(), 5)
- assert [event.name for event in events] == [
+ assert [event_name(event.event) for event in events] == [
"attachment",
"attachment.removed",
]
- assert isinstance(events[0].data, protocol.AttachmentMessage)
- assert isinstance(events[1].data, protocol.RemovedMessage)
- assert events[1].data.id == events[0].data.attachment.id
+ assert isinstance(events[0].event, protocol.AttachmentEvent)
+ assert isinstance(events[1].event, protocol.AttachmentRemovedEvent)
+ assert (
+ events[1].event.data.id == events[0].event.data.attachment.id
+ )
assert harness.backend().calls == []
finally:
client.portal.call(unsubscribe)
@@ -2174,7 +2193,7 @@ def test_editor_authentication_is_limited_to_the_event_socket(
payload = MarimoMessage(CompletedRunNotification(run_id="r1"))
published = client.portal.call(
notebook.sink.append,
- Event("marimo", payload, notebook_id=notebook.id),
+ RoutedEvent(MarimoEvent(payload), notebook_id=notebook.id),
)
assert websocket.receive_json() == {
"id": str(published.id),
@@ -2284,7 +2303,7 @@ def test_websocket_rejects_unknown_notebooks_and_routes(
def test_websocket_snapshot_failure_releases_subscription(
harness: Harness, monkeypatch: pytest.MonkeyPatch
) -> None:
- def broken(*_args: Any, **_kwargs: Any) -> list[Event]:
+ def broken(*_args: Any, **_kwargs: Any) -> list[RoutedEvent]:
raise RuntimeError("snapshot failed")
with TestClient(with_client_address(harness.app)) as client:
diff --git a/tests/_server/host/test_host_bridge.py b/tests/_server/host/test_host_bridge.py
index d3936332de..68ad0e303d 100644
--- a/tests/_server/host/test_host_bridge.py
+++ b/tests/_server/host/test_host_bridge.py
@@ -11,7 +11,7 @@ import pytest
from marimo._core import protocol
from marimo._core.errors import Conflict, DecisionRequired, EditConflict
-from marimo._core.stream import Event
+from marimo._core.stream import RoutedEvent
from marimo._messaging.notification import (
CompletedRunNotification,
ExecutionNotification,
@@ -20,7 +20,7 @@ from marimo._messaging.notification import (
)
from marimo._runtime.scratch import SCRATCH_CELL_ID
from marimo._server.host.bridge import SessionBridge
-from marimo._server.host.events import MarimoMessage
+from marimo._server.host.events import MarimoEvent, MarimoMessage
from marimo._server.models.home import MarimoFile
from marimo._server.workspace import FixedFilesWorkspace
from tests._core.conftest import names
@@ -193,10 +193,10 @@ async def test_a_subscriber_can_stop_an_adopted_session(
session = FakeSession(str(tmp_path / "a.py"))
manager.sessions["browser"] = session
- def stop_on_starting(event: Event) -> None:
+ def stop_on_starting(event: RoutedEvent) -> None:
if (
- isinstance(event.data, protocol.RuntimeMessage)
- and event.data.runtime.status == "starting"
+ isinstance(event.event, protocol.RuntimeEvent)
+ and event.event.data.runtime.status == "starting"
):
notebook.stop()
@@ -401,7 +401,7 @@ async def test_editor_transactions_reach_the_host_document(
await bridge.open()
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
- events: list[Event] = []
+ events: list[RoutedEvent] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
# The document comes from the session, ids included.
@@ -452,7 +452,7 @@ async def test_host_edits_reach_the_session_as_one_transaction(
record = bridge.index.notebook_for(str(tmp_path / "a.py"))
assert record is not None
notebook = await bridge.host.notebook(record.id)
- events: list[Event] = []
+ events: list[RoutedEvent] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
response = await bridge.edit(
@@ -474,13 +474,15 @@ async def test_host_edits_reach_the_session_as_one_transaction(
assert isinstance(notification, NotebookDocumentTransactionNotification)
assert notification.transaction.source == "host"
# The session echoes the edit without publishing the document twice.
- assert names([e for e in events if e.name != "marimo"]) == [
+ assert names(
+ [e for e in events if not isinstance(e.event, MarimoEvent)]
+ ) == [
"cell",
"document",
]
- assert [e.data for e in events if e.name == "marimo"] == [
- MarimoMessage(notification)
- ]
+ assert [
+ e.event.data for e in events if isinstance(e.event, MarimoEvent)
+ ] == [MarimoMessage(notification)]
assert notebook.document.etag == response.document.etag
assert "y = x" not in (tmp_path / "a.py").read_text()
bridge.close()
@@ -540,7 +542,7 @@ async def test_a_new_session_replaces_a_read_without_host_edits(
assert record is not None
notebook = await bridge.host.notebook(record.id)
document = notebook.document
- events: list[Event] = []
+ events: list[RoutedEvent] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
# The file changes after the host read it, then a session opens it.
@@ -703,7 +705,7 @@ async def test_save_writes_the_cells_and_keeps_the_app_config(
notebook = await bridge.host.notebook(record.id)
document = notebook.document
(cell,) = document
- events: list[Event] = []
+ events: list[RoutedEvent] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
edited = await bridge.edit(
@@ -730,7 +732,7 @@ async def test_save_writes_the_cells_and_keeps_the_app_config(
assert "x = 2" in text
assert 'width="full"' in text
assert names(events)[-1] == "document"
- assert events[-1].data.request_id == "save-1" # type: ignore[union-attr]
+ assert events[-1].event.data.request_id == "save-1" # type: ignore[union-attr]
bridge.close()
@@ -804,7 +806,7 @@ async def test_save_with_a_session_writes_through_the_editors_file_manager(
(cell,) = document
# The editor wrote once, so its manager remembers what is on disk.
session.app_file_manager.save_from_cells(list(session.document.cells))
- events: list[Event] = []
+ events: list[RoutedEvent] = []
bridge.host.subscribe(events.append, notebook_id=record.id)
edited = await bridge.edit(
@@ -823,10 +825,10 @@ async def test_save_with_a_session_writes_through_the_editors_file_manager(
published = [
e
for e in events
- if e.name == "document"
- and e.data.document.saved_etag == saved.document.etag # type: ignore[union-attr]
+ if isinstance(e.event, protocol.DocumentEvent)
+ and e.event.data.document.saved_etag == saved.document.etag # type: ignore[union-attr]
]
- assert [e.data.request_id for e in published] == ["save-1"] # type: ignore[union-attr]
+ assert [e.event.data.request_id for e in published] == ["save-1"] # type: ignore[union-attr]
bridge.close()
@@ -1005,11 +1007,11 @@ async def test_session_notifications_join_the_notebook_stream_once(
assert a is not None
assert b is not None
- first: list[Event] = []
- second: list[Event] = []
- catalog: list[Event] = []
- other: list[Event] = []
- filtered: list[Event] = []
+ first: list[RoutedEvent] = []
+ second: list[RoutedEvent] = []
+ catalog: list[RoutedEvent] = []
+ other: list[RoutedEvent] = []
+ filtered: list[RoutedEvent] = []
bridge.host.subscribe(first.append, notebook_id=a.id)
bridge.host.subscribe(second.append, notebook_id=a.id)
bridge.host.subscribe(catalog.append)
@@ -1029,8 +1031,8 @@ async def test_session_notifications_join_the_notebook_stream_once(
assert first == second
assert catalog == other == []
- assert filtered == [e for e in first if e.name == "marimo"]
- assert [(e.run_id, e.data) for e in filtered] == [
+ assert filtered == [e for e in first if isinstance(e.event, MarimoEvent)]
+ assert [(e.run_id, e.event.data) for e in filtered] == [
(None, MarimoMessage(variables)),
(protocol.RunId("run-1"), MarimoMessage(planned)),
]
diff --git a/tests/_server/host/test_host_events.py b/tests/_server/host/test_host_events.py
new file mode 100644
index 0000000000..1eee7ec79b
--- /dev/null
+++ b/tests/_server/host/test_host_events.py
@@ -0,0 +1,97 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Typed envelopes preserve transport framing and event routing."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+import pytest
+
+from marimo._core import protocol
+from marimo._core.stream import RoutedEvent, Stream, snapshot_event
+from marimo._messaging.notification import CompletedRunNotification
+from marimo._server.host.api import _frame
+from marimo._server.host.events import (
+ MarimoEvent,
+ MarimoMessage,
+ notification_event,
+ serialize_event,
+)
+
+
+ ("event", "expected"),
+ [
+ (
+ snapshot_event(protocol.Host(operations=("runtime.start",))),
+ {
+ "event": "host",
+ "data": {"host": {"operations": ["runtime.start"]}},
+ },
+ ),
+ (
+ RoutedEvent(protocol.ReadyEvent(data={}, id="42")),
+ {"event": "ready", "data": {}, "id": "42"},
+ ),
+ (
+ RoutedEvent(protocol.ResetEvent(data={})),
+ {"event": "reset", "data": {}},
+ ),
+ (
+ notification_event(
+ protocol.NotebookId("n1"),
+ CompletedRunNotification(run_id="r1"),
+ ),
+ {
+ "event": "marimo",
+ "data": {
+ "marimo": {
+ "op": "completed-run",
+ "run_id": "r1",
+ "outcome": "succeeded",
+ "error": None,
+ }
+ },
+ },
+ ),
+ ],
+)
+def test_transports_encode_the_same_envelope(
+ event: RoutedEvent, expected: dict[str, Any]
+) -> None:
+ assert json.loads(serialize_event(event)) == expected
+ frame = _frame(event).decode()
+ assert frame.endswith("\n\n")
+ fields = dict(line.split(": ", 1) for line in frame.strip().splitlines())
+ assert {**fields, "data": json.loads(fields["data"])} == expected
+
+
+def test_extension_routing_and_control_filters() -> None:
+ notebook_id = protocol.NotebookId("n1")
+ event = notification_event(
+ notebook_id, CompletedRunNotification(run_id="r1")
+ )
+ assert [event.visible_in(scope) for scope in (None, "n1", "n2")] == [
+ False,
+ True,
+ False,
+ ]
+ assert event.wanted({"marimo"}, "r1")
+ assert not event.wanted({"cell"}, "r1")
+ assert not event.wanted({"marimo"}, "r2")
+
+ stream = Stream()
+ recorded = stream.append(event)
+ assert recorded.event == MarimoEvent(
+ data=MarimoMessage(CompletedRunNotification(run_id="r1")), id="1"
+ )
+ assert stream.since(0) == [recorded]
+
+ for wire in (
+ protocol.ReadyEvent(data={}, id="1"),
+ protocol.ResetEvent(data={}),
+ ):
+ control = RoutedEvent(wire, notebook_id=notebook_id)
+ assert control.wanted({"cell"}, "other-run")
+ assert not control.visible_in(notebook_id)
diff --git a/tests/_server/host/test_host_index.py b/tests/_server/host/test_host_index.py
index e653ad779b..00e49274ad 100644
--- a/tests/_server/host/test_host_index.py
+++ b/tests/_server/host/test_host_index.py
@@ -12,7 +12,7 @@ from marimo._core import backend as be
from marimo._core.errors import NotFound
from marimo._core.host import Host
from marimo._core.protocol import ProjectMessage
-from marimo._core.stream import Event
+from marimo._core.stream import RoutedEvent
from marimo._server.host.index import WorkspaceIndex
from marimo._server.models.home import MarimoFile
from marimo._server.workspace import FixedFilesWorkspace
@@ -54,9 +54,9 @@ def test_refresh_publishes_the_project_and_its_notebooks(
"ready",
]
[project] = [
- e.data.project
+ e.event.data.project
for e in host.events()
- if isinstance(e.data, ProjectMessage)
+ if isinstance(e.event.data, ProjectMessage)
]
assert project.root == str(tmp_path)
assert project.status == "indexed"
@@ -69,7 +69,7 @@ def test_ids_survive_a_rescan_and_a_move(tmp_path: Path) -> None:
index = WorkspaceIndex(host, workspace(tmp_path, "a.py"), make_notebook)
index.refresh()
(notebook,) = host.notebooks.values()
- log: list[Event] = []
+ log: list[RoutedEvent] = []
host.subscribe(log.append)
index.refresh()
diff --git a/tests/_server/host/test_host_record.py b/tests/_server/host/test_host_record.py
index bdc892a768..852079d30b 100644
--- a/tests/_server/host/test_host_record.py
+++ b/tests/_server/host/test_host_record.py
@@ -199,7 +199,9 @@ async def test_idle_host_expires_results_and_stops_maintenance(
removed = asyncio.Event()
host.subscribe(
lambda event: (
- removed.set() if event.name == "run.removed" else None
+ removed.set()
+ if isinstance(event.event, protocol.RunRemovedEvent)
+ else None
),
notebook_id=notebook.id,
)