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.

refactor: scope down exposed state from the runner, add explicit context (#8247)

Myles Scolnick74561580dd23
diff --git a/marimo/_runtime/app/kernel_runner.py b/marimo/_runtime/app/kernel_runner.py
index a258388e8a..4d8d9e920f 100644
--- a/marimo/_runtime/app/kernel_runner.py
+++ b/marimo/_runtime/app/kernel_runner.py
@@ -16,7 +16,7 @@ from marimo._runtime.commands import (
)
from marimo._runtime.context.types import get_context
from marimo._runtime.patches import create_main_module
-from marimo._runtime.runner import cell_runner
+from marimo._runtime.runner import cell_runner, hook_context
from marimo._session.model import SessionMode
from marimo._types.ids import CellId_t
@@ -86,13 +86,13 @@ class AppKernelRunner:
def cache_output(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: hook_context.PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
"""Update the app's cached outputs."""
from marimo._plugins.stateless.flex import vstack
- del runner
+ del ctx
if (
run_result.output is None
and run_result.accumulated_output is not None
diff --git a/marimo/_runtime/runner/cell_runner.py b/marimo/_runtime/runner/cell_runner.py
index ba7b211060..51ae67e5f2 100644
--- a/marimo/_runtime/runner/cell_runner.py
+++ b/marimo/_runtime/runner/cell_runner.py
@@ -11,7 +11,7 @@ import traceback
from dataclasses import dataclass
from pathlib import Path
from types import TracebackType
-from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional
from marimo._ast.variables import unmangle_local
from marimo._config.config import ExecutionType, OnCellChangeType
@@ -19,7 +19,6 @@ from marimo._dependencies.dependencies import DependencyManager
from marimo._dependencies.errors import ManyModulesNotFoundError
from marimo._loggers import marimo_logger
from marimo._messaging.errors import (
- Error,
MarimoExceptionRaisedError,
MarimoSQLError,
MarimoStrictExecutionError,
@@ -39,6 +38,10 @@ from marimo._runtime.executor import (
get_executor,
)
from marimo._runtime.marimo_pdb import MarimoPdb
+from marimo._runtime.runner.hook_context import (
+ ExceptionOrError,
+ ExecutionContextManager,
+)
from marimo._sql.error_utils import (
create_sql_error_from_exception,
is_sql_parse_error,
@@ -50,19 +53,34 @@ LOGGER = marimo_logger()
if TYPE_CHECKING:
from collections.abc import Iterator
- from marimo._runtime.context.types import ExecutionContext
from marimo._runtime.runner.hooks import NotebookCellHooks
from marimo._runtime.state import State
+def _should_broadcast_data() -> bool:
+ """Whether data (variables, datasets, etc.) should be broadcast.
+
+ Returns True only in edit mode for non-embedded contexts.
+ """
+ from marimo._runtime.context.kernel_context import KernelRuntimeContext
+ from marimo._runtime.context.types import get_context
+ from marimo._session.model import SessionMode
+
+ ctx = get_context()
+ is_edit_mode = (
+ isinstance(ctx, KernelRuntimeContext)
+ and ctx.session_mode == SessionMode.EDIT
+ )
+ # We don't broadcast data in embedded contexts, since the variables
+ # panel, etc. should only show the top-level graph's variables.
+ return is_edit_mode and not ctx.is_embedded()
+
+
def cell_filename(cell_id: CellId_t) -> str:
"""Filename to use when running cells through exec."""
return f"<cell-{cell_id}>"
-ExceptionOrError = Union[BaseException, Error]
-
-
@dataclass
class RunResult:
# Raw output of cell: last expression
@@ -114,10 +132,7 @@ class Runner:
execution_mode: OnCellChangeType = "autorun",
execution_type: ExecutionType = "relaxed",
excluded_cells: set[CellId_t] | None = None,
- execution_context: Callable[
- [CellId_t], contextlib._GeneratorContextManager[ExecutionContext]
- ]
- | None = None,
+ execution_context: ExecutionContextManager | None = None,
):
self.graph = graph
self.debugger = debugger
@@ -647,9 +662,34 @@ class Runner:
return ref, blamed_cell
async def run_all(self) -> None:
+ from marimo._runtime.runner.hook_context import (
+ OnFinishHookContext,
+ PostExecutionHookContext,
+ PreExecutionHookContext,
+ PreparationHookContext,
+ )
+
+ prep_ctx = PreparationHookContext(
+ graph=self.graph,
+ execution_mode=self.execution_mode,
+ cells_to_run=self.cells_to_run,
+ )
LOGGER.debug("Running preparation hooks")
for prep_hook in self._hooks.preparation_hooks:
- prep_hook(self)
+ prep_hook(prep_ctx)
+
+ pre_exec_ctx = PreExecutionHookContext(
+ graph=self.graph,
+ execution_mode=self.execution_mode,
+ )
+ post_exec_ctx = PostExecutionHookContext(
+ graph=self.graph,
+ glbls=self.glbls,
+ execution_context=self.execution_context,
+ exceptions=self.exceptions,
+ cells_cancelled=self.cells_cancelled,
+ should_broadcast_data=_should_broadcast_data(),
+ )
while self.pending():
cell_id = self.pop_cell()
@@ -678,7 +718,7 @@ class Runner:
LOGGER.debug("Running pre_execution hooks")
for pre_hook in self._hooks.pre_execution_hooks:
- pre_hook(cell, self)
+ pre_hook(cell, pre_exec_ctx)
LOGGER.debug("Running cell %s", cell_id)
if self.execution_context is not None:
try:
@@ -689,7 +729,7 @@ class Runner:
run_result.accumulated_output = exc_ctx.output
LOGGER.debug("Running post_execution hooks in context")
for post_hook in self._hooks.post_execution_hooks:
- post_hook(cell, self, run_result)
+ post_hook(cell, post_exec_ctx, run_result)
except KeyboardInterrupt:
LOGGER.error(
"""
@@ -701,8 +741,15 @@ class Runner:
run_result = await self.run(cell_id)
LOGGER.debug("Running post_execution hooks out of context")
for post_hook in self._hooks.post_execution_hooks:
- post_hook(cell, self, run_result)
-
+ post_hook(cell, post_exec_ctx, run_result)
+
+ finish_ctx = OnFinishHookContext(
+ graph=self.graph,
+ cells_to_run=self.cells_to_run,
+ interrupted=self.interrupted,
+ cells_cancelled=self.cells_cancelled,
+ exceptions=self.exceptions,
+ )
LOGGER.debug("Running on_finish hooks")
for finish_hook in self._hooks.on_finish_hooks:
- finish_hook(self)
+ finish_hook(finish_ctx)
diff --git a/marimo/_runtime/runner/hook_context.py b/marimo/_runtime/runner/hook_context.py
new file mode 100644
index 0000000000..70512ec21c
--- /dev/null
+++ b/marimo/_runtime/runner/hook_context.py
@@ -0,0 +1,63 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Callable, TypeAlias, Union
+
+from marimo._config.config import OnCellChangeType
+from marimo._messaging.errors import Error
+from marimo._types.ids import CellId_t
+
+if TYPE_CHECKING:
+ from collections.abc import Mapping, Sequence
+ from contextlib import AbstractContextManager
+
+ from marimo._runtime.context.types import ExecutionContext
+ from marimo._runtime.dataflow.graph import DirectedGraph
+
+ExceptionOrError = Union[BaseException, Error]
+
+ExecutionContextManager: TypeAlias = Callable[
+ [CellId_t], "AbstractContextManager[ExecutionContext]"
+]
+
+
+@dataclass(frozen=True)
+class PreparationHookContext:
+ graph: DirectedGraph
+ execution_mode: OnCellChangeType
+ cells_to_run: Sequence[CellId_t]
+
+
+@dataclass(frozen=True)
+class PreExecutionHookContext:
+ graph: DirectedGraph
+ execution_mode: OnCellChangeType
+
+
+@dataclass(frozen=True)
+class PostExecutionHookContext:
+ graph: DirectedGraph
+ glbls: dict[str, Any]
+ execution_context: ExecutionContextManager | None
+ # Dict, because errors get mutated (formatted) by hooks.
+ exceptions: dict[CellId_t, ExceptionOrError]
+ cells_cancelled: Mapping[CellId_t, set[CellId_t]]
+ # Whether data (variables, datasets, etc.) should be broadcast
+ # to the frontend. Computed once per run to avoid repeated checks.
+ should_broadcast_data: bool = False
+
+ def cancelled(self, cell_id: CellId_t) -> bool:
+ """Check if a cell was cancelled."""
+ return any(
+ cell_id in cancelled for cancelled in self.cells_cancelled.values()
+ )
+
+
+@dataclass(frozen=True)
+class OnFinishHookContext:
+ graph: DirectedGraph
+ cells_to_run: Sequence[CellId_t]
+ interrupted: bool
+ cells_cancelled: Mapping[CellId_t, set[CellId_t]]
+ exceptions: Mapping[CellId_t, ExceptionOrError]
diff --git a/marimo/_runtime/runner/hooks.py b/marimo/_runtime/runner/hooks.py
index b4dff2e414..5ac4e9abef 100644
--- a/marimo/_runtime/runner/hooks.py
+++ b/marimo/_runtime/runner/hooks.py
@@ -10,6 +10,12 @@ if TYPE_CHECKING:
from marimo._ast.cell import CellImpl
from marimo._runtime.runner import cell_runner
+ from marimo._runtime.runner.hook_context import (
+ OnFinishHookContext,
+ PostExecutionHookContext,
+ PreExecutionHookContext,
+ PreparationHookContext,
+ )
__all__ = [
"NotebookCellHooks",
@@ -22,12 +28,12 @@ __all__ = [
]
# Hook type aliases
-PreparationHook = Callable[["cell_runner.Runner"], None]
-PreExecutionHook = Callable[["CellImpl", "cell_runner.Runner"], None]
+PreparationHook = Callable[["PreparationHookContext"], None]
+PreExecutionHook = Callable[["CellImpl", "PreExecutionHookContext"], None]
PostExecutionHook = Callable[
- ["CellImpl", "cell_runner.Runner", "cell_runner.RunResult"], None
+ ["CellImpl", "PostExecutionHookContext", "cell_runner.RunResult"], None
]
-OnFinishHook = Callable[["cell_runner.Runner"], None]
+OnFinishHook = Callable[["OnFinishHookContext"], None]
class Priority(IntEnum):
@@ -48,6 +54,30 @@ class _HookEntry:
@dataclass
+class _HookList:
+ """A list of hook entries with cached priority-sorted access."""
+
+ _entries: list[_HookEntry] = field(default_factory=list)
+ _sorted: list[Callable[..., None]] | None = field(
+ default=None, init=False, repr=False
+ )
+
+ def add(self, hook: Callable[..., None], priority: Priority) -> None:
+ self._entries.append(_HookEntry(hook, priority))
+ self._sorted = None
+
+ @property
+ def sorted_hooks(self) -> Sequence[Callable[..., None]]:
+ if self._sorted is None:
+ self._sorted = [
+ e.hook for e in sorted(self._entries, key=lambda e: e.priority)
+ ]
+ return self._sorted
+
+ def copy(self) -> _HookList:
+ return _HookList(self._entries.copy())
+
+
class NotebookCellHooks:
"""Container for cell execution hooks with priority-based ordering.
@@ -58,56 +88,53 @@ class NotebookCellHooks:
4. on_finish_hooks: Run once after all cells complete
"""
- _preparation: list[_HookEntry] = field(default_factory=list)
- _pre_execution: list[_HookEntry] = field(default_factory=list)
- _post_execution: list[_HookEntry] = field(default_factory=list)
- _on_finish: list[_HookEntry] = field(default_factory=list)
+ def __init__(
+ self,
+ _preparation: _HookList | None = None,
+ _pre_execution: _HookList | None = None,
+ _post_execution: _HookList | None = None,
+ _on_finish: _HookList | None = None,
+ ) -> None:
+ self._preparation = _preparation or _HookList()
+ self._pre_execution = _pre_execution or _HookList()
+ self._post_execution = _post_execution or _HookList()
+ self._on_finish = _on_finish or _HookList()
def add_preparation(
self, hook: PreparationHook, priority: Priority = Priority.NORMAL
) -> None:
- self._preparation.append(_HookEntry(hook, priority))
+ self._preparation.add(hook, priority)
def add_pre_execution(
self, hook: PreExecutionHook, priority: Priority = Priority.NORMAL
) -> None:
- self._pre_execution.append(_HookEntry(hook, priority))
+ self._pre_execution.add(hook, priority)
def add_post_execution(
self, hook: PostExecutionHook, priority: Priority = Priority.NORMAL
) -> None:
- self._post_execution.append(_HookEntry(hook, priority))
+ self._post_execution.add(hook, priority)
def add_on_finish(
self, hook: OnFinishHook, priority: Priority = Priority.NORMAL
) -> None:
- self._on_finish.append(_HookEntry(hook, priority))
+ self._on_finish.add(hook, priority)
@property
def preparation_hooks(self) -> Sequence[PreparationHook]:
- return [
- e.hook for e in sorted(self._preparation, key=lambda e: e.priority)
- ]
+ return self._preparation.sorted_hooks
@property
def pre_execution_hooks(self) -> Sequence[PreExecutionHook]:
- return [
- e.hook
- for e in sorted(self._pre_execution, key=lambda e: e.priority)
- ]
+ return self._pre_execution.sorted_hooks
@property
def post_execution_hooks(self) -> Sequence[PostExecutionHook]:
- return [
- e.hook
- for e in sorted(self._post_execution, key=lambda e: e.priority)
- ]
+ return self._post_execution.sorted_hooks
@property
def on_finish_hooks(self) -> Sequence[OnFinishHook]:
- return [
- e.hook for e in sorted(self._on_finish, key=lambda e: e.priority)
- ]
+ return self._on_finish.sorted_hooks
def copy(self) -> NotebookCellHooks:
return NotebookCellHooks(
@@ -125,10 +152,7 @@ def create_default_hooks() -> NotebookCellHooks:
Callers should add mode-specific hooks (e.g., render_toplevel_defs for
edit mode, attempt_pytest for reactive tests) after calling this.
"""
- from marimo._runtime.runner.hooks_on_finish import (
- _send_cancellation_errors,
- _send_interrupt_errors,
- )
+ from marimo._runtime.runner.hooks_on_finish import ON_FINISH_HOOKS
from marimo._runtime.runner.hooks_post_execution import (
POST_EXECUTION_HOOKS,
)
@@ -150,7 +174,7 @@ def create_default_hooks() -> NotebookCellHooks:
for post_hook in POST_EXECUTION_HOOKS:
hooks.add_post_execution(post_hook)
- hooks.add_on_finish(_send_interrupt_errors)
- hooks.add_on_finish(_send_cancellation_errors)
+ for finish_hook in ON_FINISH_HOOKS:
+ hooks.add_on_finish(finish_hook)
return hooks
diff --git a/marimo/_runtime/runner/hooks_on_finish.py b/marimo/_runtime/runner/hooks_on_finish.py
index 88e7d67d50..bca01c6f77 100644
--- a/marimo/_runtime/runner/hooks_on_finish.py
+++ b/marimo/_runtime/runner/hooks_on_finish.py
@@ -1,8 +1,6 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import Callable
-
from marimo import _loggers
from marimo._messaging.errors import (
Error,
@@ -14,21 +12,20 @@ from marimo._messaging.errors import (
)
from marimo._messaging.notification_utils import CellNotificationUtils
from marimo._runtime.control_flow import MarimoStopError
-from marimo._runtime.runner import cell_runner
+from marimo._runtime.runner.hook_context import OnFinishHookContext
+from marimo._runtime.runner.hooks import OnFinishHook
from marimo._tracer import kernel_tracer
LOGGER = _loggers.marimo_logger()
-OnFinishHookType = Callable[[cell_runner.Runner], None]
-
@kernel_tracer.start_as_current_span("send_interrupt_errors")
-def _send_interrupt_errors(runner: cell_runner.Runner) -> None:
- if runner.cells_to_run:
- assert runner.interrupted
- for cid in runner.cells_to_run:
+def _send_interrupt_errors(ctx: OnFinishHookContext) -> None:
+ if ctx.cells_to_run:
+ assert ctx.interrupted
+ for cid in ctx.cells_to_run:
# `cid` was not run
- runner.graph.cells[cid].set_runtime_state("idle")
+ ctx.graph.cells[cid].set_runtime_state("idle")
CellNotificationUtils.broadcast_error(
data=[MarimoInterruptionError()],
# these cells are transitioning from queued to stopped
@@ -40,17 +37,17 @@ def _send_interrupt_errors(runner: cell_runner.Runner) -> None:
@kernel_tracer.start_as_current_span("send_cancellation_errors")
-def _send_cancellation_errors(runner: cell_runner.Runner) -> None:
- for raising_cell in runner.cells_cancelled:
- for cid in runner.cells_cancelled[raising_cell]:
+def _send_cancellation_errors(ctx: OnFinishHookContext) -> None:
+ for raising_cell in ctx.cells_cancelled:
+ for cid in ctx.cells_cancelled[raising_cell]:
# `cid` was not run
- cell = runner.graph.cells[cid]
+ cell = ctx.graph.cells[cid]
if cell.runtime_state != "idle":
# the cell raising an exception will already be
# idle, but its descendants won't be.
cell.set_runtime_state("idle")
- exception = runner.exceptions[raising_cell]
+ exception = ctx.exceptions[raising_cell]
data: Error
if isinstance(exception, MarimoStopError):
data = MarimoAncestorStoppedError(
@@ -89,7 +86,7 @@ def _send_cancellation_errors(runner: cell_runner.Runner) -> None:
)
-ON_FINISH_HOOKS: list[OnFinishHookType] = [
+ON_FINISH_HOOKS: list[OnFinishHook] = [
_send_interrupt_errors,
_send_cancellation_errors,
]
diff --git a/marimo/_runtime/runner/hooks_post_execution.py b/marimo/_runtime/runner/hooks_post_execution.py
index 617722f206..eb2ad7863a 100644
--- a/marimo/_runtime/runner/hooks_post_execution.py
+++ b/marimo/_runtime/runner/hooks_post_execution.py
@@ -2,7 +2,6 @@
from __future__ import annotations
import sys
-from typing import Callable
from marimo import _loggers
from marimo._ast.cell import CellImpl
@@ -32,15 +31,15 @@ from marimo._messaging.tracebacks import write_traceback
from marimo._messaging.variables import create_variable_value
from marimo._output import formatting
from marimo._plugins.ui._core.ui_element import UIElement
-from marimo._runtime.context.kernel_context import KernelRuntimeContext
from marimo._runtime.context.types import (
get_context,
get_global_context,
)
from marimo._runtime.control_flow import MarimoInterrupt, MarimoStopError
from marimo._runtime.runner import cell_runner
+from marimo._runtime.runner.hook_context import PostExecutionHookContext
+from marimo._runtime.runner.hooks import PostExecutionHook
from marimo._runtime.side_effect import SideEffect
-from marimo._session.model import SessionMode
from marimo._sql.engines.duckdb import (
INTERNAL_DUCKDB_ENGINE,
DuckDBEngine,
@@ -56,47 +55,42 @@ from marimo._utils.flatten import contains_instance
LOGGER = _loggers.marimo_logger()
-PostExecutionHookType = Callable[
- [CellImpl, cell_runner.Runner, cell_runner.RunResult], None
-]
-
-
@kernel_tracer.start_as_current_span("set_imported_defs")
def _set_imported_defs(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
del run_result
LOGGER.debug("Acquiring graph lock to update cell import workspace")
- with runner.graph.lock:
+ with ctx.graph.lock:
LOGGER.debug("Acquired graph lock to update import workspace.")
if cell.import_workspace.is_import_block:
cell.import_workspace.imported_defs = set(
- name for name in cell.defs if name in runner.glbls
+ name for name in cell.defs if name in ctx.glbls
)
@kernel_tracer.start_as_current_span("set_status_idle")
def _set_status_idle(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
del run_result
- del runner
+ del ctx
cell.set_runtime_state(status="idle")
@kernel_tracer.start_as_current_span("set_run_result_status")
def _set_run_result_status(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
if isinstance(run_result.exception, MarimoInterruptionError):
cell.set_run_result_status("interrupted")
- elif runner.cancelled(cell.cell_id):
+ elif ctx.cancelled(cell.cell_id):
cell.set_run_result_status("cancelled")
elif run_result.exception is not None:
cell.set_run_result_status(
@@ -114,33 +108,20 @@ def _set_run_result_status(
cell.set_run_result_status("success")
-def _should_broadcast_data() -> bool:
- ctx = get_context()
- is_edit_mode = (
- isinstance(ctx, KernelRuntimeContext)
- and ctx.session_mode == SessionMode.EDIT
- )
- # We don't broadcast data in embedded contexts, since the variables panel,
- # etc. should only show the top-level graph's variables.
- return is_edit_mode and not ctx.is_embedded()
-
-
@kernel_tracer.start_as_current_span("broadcast_variables")
def _broadcast_variables(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
- if not _should_broadcast_data():
+ if not ctx.should_broadcast_data:
return
del run_result
values = [
create_variable_value(
name=variable,
- value=(
- runner.glbls[variable] if variable in runner.glbls else None
- ),
+ value=(ctx.glbls[variable] if variable in ctx.glbls else None),
)
for variable in cell.defs
]
@@ -151,18 +132,18 @@ def _broadcast_variables(
@kernel_tracer.start_as_current_span("broadcast_datasets")
def _broadcast_datasets(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
- if not _should_broadcast_data():
+ if not ctx.should_broadcast_data:
return
del run_result
tables = get_datasets_from_variables(
[
- (VariableName(variable), runner.glbls[variable])
+ (VariableName(variable), ctx.glbls[variable])
for variable in cell.defs
- if variable in runner.glbls
+ if variable in ctx.glbls
]
)
if tables:
@@ -173,18 +154,18 @@ def _broadcast_datasets(
@kernel_tracer.start_as_current_span("broadcast_data_source_connection")
def _broadcast_data_source_connection(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
- if not _should_broadcast_data():
+ if not ctx.should_broadcast_data:
return
del run_result
engines = get_engines_from_variables(
[
- (VariableName(variable), runner.glbls[variable])
+ (VariableName(variable), ctx.glbls[variable])
for variable in cell.defs
- if variable in runner.glbls
+ if variable in ctx.glbls
]
)
@@ -205,14 +186,13 @@ def _broadcast_data_source_connection(
@kernel_tracer.start_as_current_span("broadcast_duckdb_datasource")
def _broadcast_duckdb_datasource(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
- if not _should_broadcast_data():
+ if not ctx.should_broadcast_data:
return
del run_result
- del runner
if not DependencyManager.duckdb.has():
return
@@ -243,10 +223,10 @@ def _broadcast_duckdb_datasource(
@kernel_tracer.start_as_current_span("store_reference_to_output")
def _store_reference_to_output(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
- del runner
+ del ctx
# Stores a reference to the output if it contains a UIElement;
# this is required to make RPCs work for unnamed UI elements.
@@ -259,28 +239,28 @@ def _store_reference_to_output(
def _store_state_reference(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
del run_result
# Associate state variables with variable names
- ctx = get_context()
- ctx.state_registry.register_scope(runner.glbls, defs=cell.defs)
+ runtime_ctx = get_context()
+ runtime_ctx.state_registry.register_scope(ctx.glbls, defs=cell.defs)
privates = set().union(
- *[cell.temporaries for cell in ctx.graph.cells.values()]
+ *[cell.temporaries for cell in runtime_ctx.graph.cells.values()]
)
- ctx.state_registry.retain_active_states(
- set(runner.graph.definitions.keys()) | privates
+ runtime_ctx.state_registry.retain_active_states(
+ set(ctx.graph.definitions.keys()) | privates
)
@kernel_tracer.start_as_current_span("issue_exception_side_effect")
def _issue_exception_side_effect(
_cell: CellImpl,
- _runner: cell_runner.Runner,
+ _ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
- ctx = get_context()
+ runtime_ctx = get_context()
if run_result.exception is not None:
exception = run_result.exception
key = type(exception).__name__
@@ -297,13 +277,13 @@ def _issue_exception_side_effect(
# was raised.
key += f":{traceback.tb_lasti}"
# NB. This is on a cell level.
- ctx.cell_lifecycle_registry.add(SideEffect(key))
+ runtime_ctx.cell_lifecycle_registry.add(SideEffect(key))
@kernel_tracer.start_as_current_span("broadcast_outputs")
def _broadcast_outputs(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
# TODO: clean this logic up ...
@@ -328,12 +308,12 @@ def _broadcast_outputs(
formatted_output = formatting.try_format(
run_result.output, include_opinionated=False
)
- # For ImportError and ModuleNotFoundError, store the exception in the runner
- # so it can be reported by the missing_packages_hook.
+ # For ImportError and ModuleNotFoundError, store the exception in the
+ # context so it can be reported by the missing_packages_hook.
if isinstance(
formatted_output.exception, (ImportError, ModuleNotFoundError)
):
- runner.exceptions[cell.cell_id] = formatted_output.exception
+ ctx.exceptions[cell.cell_id] = formatted_output.exception
if formatted_output.traceback is not None:
write_traceback(formatted_output.traceback)
@@ -402,13 +382,13 @@ def _broadcast_outputs(
@kernel_tracer.start_as_current_span("render_toplevel_defs")
def render_toplevel_defs(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
del run_result
variable = cell.toplevel_variable
if variable is not None:
- extractor = TopLevelExtraction.from_graph(runner.graph, cell=cell)
+ extractor = TopLevelExtraction.from_graph(ctx.graph, cell=cell)
serialization = list(iter(extractor))[-1]
CellNotificationUtils.broadcast_serialization(
serialization=serialization,
@@ -419,7 +399,7 @@ def render_toplevel_defs(
@kernel_tracer.start_as_current_span("run_pytest")
def attempt_pytest(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
del run_result
@@ -427,9 +407,9 @@ def attempt_pytest(
try:
import marimo._runtime.pytest as marimo_pytest
- if runner.execution_context is not None:
- with runner.execution_context(cell.cell_id):
- result = marimo_pytest.run_pytest(cell.defs, runner.glbls)
+ if ctx.execution_context is not None:
+ with ctx.execution_context(cell.cell_id):
+ result = marimo_pytest.run_pytest(cell.defs, ctx.glbls)
if result.output:
sys.stdout.write(result.output)
except ImportError:
@@ -439,17 +419,17 @@ def attempt_pytest(
@kernel_tracer.start_as_current_span("reset_matplotlib_context")
def _reset_matplotlib_context(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
del cell
del run_result
if get_global_context().mpl_installed:
# ensures that every cell gets a fresh axis.
- exec("__marimo__._output.mpl.close_figures()", runner.glbls)
+ exec("__marimo__._output.mpl.close_figures()", ctx.glbls)
-POST_EXECUTION_HOOKS: list[PostExecutionHookType] = [
+POST_EXECUTION_HOOKS: list[PostExecutionHook] = [
_set_imported_defs,
_set_run_result_status,
_store_reference_to_output,
diff --git a/marimo/_runtime/runner/hooks_pre_execution.py b/marimo/_runtime/runner/hooks_pre_execution.py
index 97f92babe7..8fa3c251b7 100644
--- a/marimo/_runtime/runner/hooks_pre_execution.py
+++ b/marimo/_runtime/runner/hooks_pre_execution.py
@@ -1,23 +1,20 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import Callable
-
from marimo._ast.cell import CellImpl
-from marimo._runtime.runner import cell_runner
+from marimo._runtime.runner.hook_context import PreExecutionHookContext
+from marimo._runtime.runner.hooks import PreExecutionHook
from marimo._tracer import kernel_tracer
-PreExecutionHookType = Callable[[CellImpl, cell_runner.Runner], None]
-
@kernel_tracer.start_as_current_span("set_staleness")
def _set_staleness(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PreExecutionHookContext,
) -> None:
- graph = runner.graph
+ graph = ctx.graph
- if runner.execution_mode == "lazy" and not graph.is_any_ancestor_stale(
+ if ctx.execution_mode == "lazy" and not graph.is_any_ancestor_stale(
cell.cell_id
):
# TODO: The above check could be omitted as an optimization as long as
@@ -30,13 +27,13 @@ def _set_staleness(
@kernel_tracer.start_as_current_span("set_status_to_running")
def _set_status_to_running(
cell: CellImpl,
- runner: cell_runner.Runner,
+ ctx: PreExecutionHookContext,
) -> None:
- del runner
+ del ctx
cell.set_runtime_state("running")
-PRE_EXECUTION_HOOKS: list[PreExecutionHookType] = [
+PRE_EXECUTION_HOOKS: list[PreExecutionHook] = [
_set_staleness,
_set_status_to_running,
]
diff --git a/marimo/_runtime/runner/hooks_preparation.py b/marimo/_runtime/runner/hooks_preparation.py
index 0087cff524..7f1617f12f 100644
--- a/marimo/_runtime/runner/hooks_preparation.py
+++ b/marimo/_runtime/runner/hooks_preparation.py
@@ -1,29 +1,26 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
-from typing import Callable
-
from marimo._runtime import dataflow
-from marimo._runtime.runner import cell_runner
+from marimo._runtime.runner.hook_context import PreparationHookContext
+from marimo._runtime.runner.hooks import PreparationHook
from marimo._tracer import kernel_tracer
-PreparationHookType = Callable[[cell_runner.Runner], None]
-
@kernel_tracer.start_as_current_span("update_stale_statuses")
-def _update_stale_statuses(runner: cell_runner.Runner) -> None:
- graph = runner.graph
+def _update_stale_statuses(ctx: PreparationHookContext) -> None:
+ graph = ctx.graph
- if runner.execution_mode == "lazy":
+ if ctx.execution_mode == "lazy":
for cid in dataflow.transitive_closure(
graph,
- set(runner.cells_to_run),
+ set(ctx.cells_to_run),
inclusive=False,
relatives=dataflow.get_import_block_relatives(graph),
):
graph.cells[cid].set_stale(stale=True)
- for cid in runner.cells_to_run:
+ for cid in ctx.cells_to_run:
if graph.is_disabled(cid):
graph.cells[cid].set_stale(stale=True)
else:
@@ -32,4 +29,4 @@ def _update_stale_statuses(runner: cell_runner.Runner) -> None:
graph.cells[cid].set_stale(stale=False)
-PREPARATION_HOOKS: list[PreparationHookType] = [_update_stale_statuses]
+PREPARATION_HOOKS: list[PreparationHook] = [_update_stale_statuses]
diff --git a/marimo/_runtime/runtime.py b/marimo/_runtime/runtime.py
index 181bb94be4..ffae2b047b 100644
--- a/marimo/_runtime/runtime.py
+++ b/marimo/_runtime/runtime.py
@@ -163,7 +163,7 @@ from marimo._runtime.params import CLIArgs, QueryParams
from marimo._runtime.redirect_streams import redirect_streams
from marimo._runtime.reload.autoreload import ModuleReloader
from marimo._runtime.reload.module_watcher import ModuleWatcher
-from marimo._runtime.runner import cell_runner
+from marimo._runtime.runner import cell_runner, hook_context
from marimo._runtime.runner.hooks import (
NotebookCellHooks,
Priority,
@@ -1369,9 +1369,9 @@ class Kernel:
def _propagate_kernel_errors(
self,
- runner: cell_runner.Runner,
+ ctx: hook_context.OnFinishHookContext,
) -> None:
- for cell_id, error in runner.exceptions.items():
+ for cell_id, error in ctx.exceptions.items():
if isinstance(error, MarimoStrictExecutionError):
self.errors[cell_id] = (error,)
@@ -1388,17 +1388,17 @@ class Kernel:
# descendants (cancelled == cells that raise exceptions), whereas
# eager kernels do (since we clear all state ahead of time, and
# have the closure of the roots in cells to run)
- def invalidate_state(runner: cell_runner.Runner) -> None:
- for cid in runner.cells_to_run:
+ def invalidate_state(ctx: hook_context.PreparationHookContext) -> None:
+ for cid in ctx.cells_to_run:
self._invalidate_cell_state(cid)
def note_time_of_interruption(
cell_impl: CellImpl,
- runner: cell_runner.Runner,
+ ctx: hook_context.PostExecutionHookContext,
run_result: cell_runner.RunResult,
) -> None:
del cell_impl
- del runner
+ del ctx
if isinstance(run_result.exception, MarimoInterrupt):
self.last_interrupt_timestamp = time.time()
@@ -2785,10 +2785,12 @@ class PackagesCallbacks:
),
)
- def missing_packages_hook(self, runner: cell_runner.Runner) -> None:
+ def missing_packages_hook(
+ self, ctx: hook_context.OnFinishHookContext
+ ) -> None:
module_not_found_errors = [
e
- for e in runner.exceptions.values()
+ for e in ctx.exceptions.values()
if isinstance(e, (ImportError, ManyModulesNotFoundError))
]
diff --git a/marimo/_runtime/state.py b/marimo/_runtime/state.py
index f77a968d1c..861afd68db 100644
--- a/marimo/_runtime/state.py
+++ b/marimo/_runtime/state.py
@@ -4,7 +4,7 @@ from __future__ import annotations
import types
import weakref
from dataclasses import dataclass
-from typing import Any, Callable, Generic, Optional, TypeVar
+from typing import TYPE_CHECKING, Any, Callable, Generic, Optional, TypeVar
from uuid import uuid4
from marimo._output.rich_help import mddoc
@@ -13,6 +13,9 @@ from marimo._runtime.context import ContextNotInitializedError, get_context
T = TypeVar("T")
Id = int
+if TYPE_CHECKING:
+ from collections.abc import Mapping
+
@dataclass
class StateItem(Generic[T]):
@@ -72,7 +75,7 @@ class StateRegistry:
finalizer.atexit = False
def register_scope(
- self, glbls: dict[str, Any], defs: Optional[set[str]] = None
+ self, glbls: Mapping[str, Any], defs: Optional[set[str]] = None
) -> None:
"""Finds instances of state and scope, and adds them to registry if not
already present."""