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.

feat(save): stub serialization toolkit (class/lazy/module stubs) (#9896)

Dylan Madisetti6c7da04ddbb1
diff --git a/marimo/_runtime/exceptions.py b/marimo/_runtime/exceptions.py
index fcb51f4cea..833b9e0cd2 100644
--- a/marimo/_runtime/exceptions.py
+++ b/marimo/_runtime/exceptions.py
@@ -5,6 +5,7 @@ from typing import TYPE_CHECKING
if TYPE_CHECKING:
from marimo._runtime.dataflow import DirectedGraph
+ from marimo._types.ids import CellId_t
class MarimoRuntimeException(BaseException):
@@ -26,6 +27,39 @@ class MarimoMissingRefError(BaseException):
self.name_error = name_error
+class MarimoCancelCellError(BaseException):
+ """Soft-cancel signal raised by a lifecycle.
+
+ Subclasses BaseException (not Exception) so user-code `except Exception`
+ blocks don't swallow the control-flow signal.
+ """
+
+ cells_to_rerun: set[CellId_t]
+
+ def __init__(
+ self,
+ *args: object,
+ cells_to_rerun: set[CellId_t] | None = None,
+ ) -> None:
+ super().__init__(*args)
+ self.cells_to_rerun = cells_to_rerun or set()
+
+
+class MarimoUnhashableCacheError(MarimoCancelCellError):
+ """Raised when cell-level caching encounters a value that cannot be
+ hashed/serialized for cache restoration."""
+
+ def __init__(
+ self,
+ cells_to_rerun: set[CellId_t],
+ variables: list[str],
+ error_details: str,
+ ) -> None:
+ super().__init__(error_details, cells_to_rerun=cells_to_rerun)
+ self.variables = variables
+ self.error_details = error_details
+
+
def unwrap_user_exception(
exc: MarimoRuntimeException,
graph: DirectedGraph | None = None,
diff --git a/marimo/_save/cache.py b/marimo/_save/cache.py
index 26ceb8c12f..c07159bcfe 100644
--- a/marimo/_save/cache.py
+++ b/marimo/_save/cache.py
@@ -4,6 +4,7 @@ from __future__ import annotations
import abc
import inspect
import re
+import textwrap
from collections import namedtuple
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any, Literal, get_args
@@ -14,6 +15,7 @@ from marimo._runtime.context import ContextNotInitializedError, get_context
from marimo._runtime.state import SetFunctor
from marimo._save.stubs import (
CUSTOM_STUBS,
+ ClassStub,
CustomStub,
FunctionStub,
ModuleStub,
@@ -21,6 +23,7 @@ from marimo._save.stubs import (
UIElementStub,
maybe_register_stub,
)
+from marimo._save.stubs.lazy_stub import UnhashableStub
# Many assertions are for typing and should always pass. This message is a
# catch all to motive users to report if something does fail.
@@ -114,6 +117,24 @@ CacheInfo = namedtuple(
)
+def _source_refs(code: str) -> set[Name]:
+ """Free references of a captured class/function source block.
+
+ Reuses the cell `ScopedVisitor` so the notion of "what this def needs"
+ matches marimo's dataflow rather than a bespoke parser.
+ """
+ from marimo._ast.parse import ast_parse
+ from marimo._ast.visitor import ScopedVisitor
+
+ try:
+ tree = ast_parse(textwrap.dedent(code))
+ except SyntaxError:
+ return set()
+ visitor = ScopedVisitor("cache_restore")
+ visitor.visit(tree)
+ return set(visitor.refs)
+
+
# BaseException because "raise _ as e" is utilized.
class CacheException(BaseException):
pass
@@ -136,7 +157,7 @@ class Cache:
def restore(self, scope: dict[str, Any]) -> None:
"""Restores values from cache, into scope."""
memo: dict[int, Any] = {} # Track processed objects to handle cycles
- for var, lookup in self.contextual_defs():
+ for var, lookup in self._restore_order(self.contextual_defs()):
value = self.defs.get(var, None)
scope[lookup] = self._restore_from_stub_if_needed(
value, scope, memo
@@ -167,6 +188,44 @@ class Cache:
f"({type(ref)}:{ref})."
)
+ def _restore_deps(self, value: Any) -> set[Name]:
+ """Cross-def names *value* needs before it can be restored.
+
+ - A re-exec'd class/function needs the defs it references at
+ definition time (bases, decorators, class-body calls).
+ - A pickled instance of a cell-defined class needs that class
+ materialized first (tagged via `requires`).
+ """
+ if isinstance(value, (ClassStub, FunctionStub)):
+ return _source_refs(value.code)
+ requires = getattr(value, "requires", "")
+ return {requires} if requires else set()
+
+ def _restore_order(
+ self, contextual_defs: dict[tuple[Name, Name], Any]
+ ) -> list[tuple[Name, Name]]:
+ """Order `(var, lookup)` pairs so each def's cross-def dependencies
+ restore first (depth-first; tolerant of cycles via `seen`)."""
+ lookups = {var: lookup for var, lookup in contextual_defs}
+ deps = {
+ var: self._restore_deps(self.defs.get(var)) & lookups.keys()
+ for var in lookups
+ }
+ order: list[tuple[Name, Name]] = []
+ seen: set[Name] = set()
+
+ def visit(var: Name) -> None:
+ if var in seen:
+ return
+ seen.add(var)
+ for dep in deps[var]:
+ visit(dep)
+ order.append((var, lookups[var]))
+
+ for var in lookups:
+ visit(var)
+ return order
+
def _restore_from_stub_if_needed(
self,
value: Any,
@@ -223,6 +282,16 @@ class Cache:
result = value
elif isinstance(value, ReferenceStub):
result = value.load(scope)
+ elif isinstance(value, ClassStub):
+ # Re-exec the captured source into the cell namespace so the
+ # name rebinds to a live class (not the stub). Must run before
+ # any pickle blob referencing the class deserializes, so the
+ # class is resolvable as `__main__.<name>` in `scope`.
+ result = value.load(scope)
+ elif isinstance(value, UnhashableStub):
+ # Marker for a def whose value couldn't be serialized. Place it
+ # in scope as-is.
+ result = value
elif isinstance(value, CustomStub):
# CustomStub is a placeholder for a custom type, which cannot be
# restored directly.
@@ -315,8 +384,28 @@ class Cache:
if inspect.ismodule(value):
result = ModuleStub(value)
- elif inspect.isfunction(value):
+ elif (
+ inspect.isfunction(value)
+ and value.__name__ != "<lambda>"
+ and getattr(value, "__module__", "__main__") == "__main__"
+ ):
+ # NB. Lambdas can't round-trip via FunctionStub: inspect.getsource
+ # returns the line *containing* the lambda (e.g. "return model,
+ # lambda inp: model(inp)"), which fails to compile as a module.
result = FunctionStub(value)
+ elif (
+ inspect.isclass(value)
+ and getattr(value, "__module__", None) == "__main__"
+ ):
+ # Attempt to capture classes by source so the loader can rebuild
+ # them in the cell namespace before pickle blobs that reference them
+ # deserialize. Pass the executing cell's source filename as a hint
+ # so attribute-only classes (no method code object to read a
+ # filename from) still resolve against `linecache`.
+ try:
+ result = ClassStub(value, filename=self._cell_filename())
+ except (TypeError, OSError):
+ result = value
elif isinstance(value, UIElement):
result = UIElementStub(value)
elif isinstance(value, tuple):
@@ -397,6 +486,20 @@ class Cache:
return result
+ @staticmethod
+ def _cell_filename() -> str | None:
+ """Source filename of the executing cell, for sourcing classes that
+ lack a method code object. `None` when there is no runtime context
+ (e.g. script-mode / direct API use)."""
+ try:
+ from marimo._ast.compiler import get_filename
+
+ context = get_context().execution_context
+ assert context is not None
+ return get_filename(context.cell_id)
+ except (ContextNotInitializedError, AssertionError):
+ return None
+
def contextual_defs(self) -> dict[tuple[Name, Name], Any]:
"""Uses context to resolve private variable names."""
try:
diff --git a/marimo/_save/hash.py b/marimo/_save/hash.py
index c657b0583b..68cfd625ff 100644
--- a/marimo/_save/hash.py
+++ b/marimo/_save/hash.py
@@ -705,11 +705,13 @@ class BlockHasher:
version = ""
module = None
if self.pin_modules:
- module = sys.modules[imports[ref].module]
- version = getattr(module, "__version__", "")
+ # `.get`: a cached module def restored as a missing-
+ # module placeholder is in scope but not sys.modules.
+ module = sys.modules.get(imports[ref].module)
+ version = getattr(module, "__version__", "") or ""
if not version:
- module = sys.modules[imports[ref].namespace]
- version = getattr(module, "__version__", "")
+ module = sys.modules.get(imports[ref].namespace)
+ version = getattr(module, "__version__", "") or ""
content_serialization[ref] = type_sign(
bytes(f"module:{ref}:{version}", "utf-8"), "module"
@@ -1078,6 +1080,7 @@ def cache_attempt_from_hash(
hasher.defs,
hasher.key,
hasher.stateful_refs,
+ glbls=scope,
)
@@ -1166,4 +1169,5 @@ def content_cache_attempt_from_base(
hasher.defs,
hasher.key,
stateful_refs,
+ glbls=scope,
)
diff --git a/marimo/_save/loaders/lazy.py b/marimo/_save/loaders/lazy.py
index 2a917118c2..0e2824f5d0 100644
--- a/marimo/_save/loaders/lazy.py
+++ b/marimo/_save/loaders/lazy.py
@@ -1,6 +1,8 @@
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
+import importlib
+import inspect
import pickle
import queue
import threading
@@ -19,6 +21,7 @@ from marimo._save.hash import HashKey
from marimo._save.loaders.loader import BasePersistenceLoader
from marimo._save.stores import FileStore, Store
from marimo._save.stubs import (
+ ClassStub,
FunctionStub,
ModuleStub,
)
@@ -61,6 +64,33 @@ def maybe_update_lazy_stub(value: Any) -> str:
return loader
+def _maybe_import_ref(value: Any) -> tuple[str, str] | None:
+ """Return `(module, qualname)` if *value* is re-importable by name,
+ else `None`.
+ """
+ if not (
+ inspect.isclass(value)
+ or inspect.isroutine(value)
+ or type(value).__module__ == "typing"
+ ):
+ return None
+ module = getattr(value, "__module__", None)
+ qualname = (
+ getattr(value, "__qualname__", None)
+ or getattr(value, "__name__", None)
+ or getattr(value, "_name", None)
+ )
+ if not module or module == "__main__" or not qualname:
+ return None
+ try:
+ obj: Any = importlib.import_module(module)
+ for part in qualname.split("."):
+ obj = getattr(obj, part)
+ except (ImportError, AttributeError):
+ return None
+ return (module, qualname) if obj is value else None
+
+
def to_item(
path: Path,
value: Any | None,
@@ -77,20 +107,17 @@ def to_item(
type_hint = f"{type(value).__module__}.{type(value).__name__}"
if loader == "pickle":
+ # A re-importable reference is stored inline rather than as a blob.
+ ref = _maybe_import_ref(value)
+ if ref is not None:
+ return Item(import_ref=ref)
+ if loader in ("pickle", "npy", "arrow", "pt"):
+ # Blob strategies: the file extension is the loader name, matching
+ # the path `save_cache` writes (`{var}.{loader}`). Listing them
+ # together keeps a new format (e.g. `pt`) from silently falling
+ # through to the `.pickle` fallback and mismatching its blob.
return Item(
- reference=(path / f"{var_name}.pickle").as_posix(),
- hash=hash,
- type_hint=type_hint,
- )
- if loader == "npy":
- return Item(
- reference=(path / f"{var_name}.npy").as_posix(),
- hash=hash,
- type_hint=type_hint,
- )
- if loader == "arrow":
- return Item(
- reference=(path / f"{var_name}.arrow").as_posix(),
+ reference=(path / f"{var_name}.{loader}").as_posix(),
hash=hash,
type_hint=type_hint,
)
@@ -98,6 +125,8 @@ def to_item(
return Item(reference=(path / "ui.pickle").as_posix())
if isinstance(value, FunctionStub):
return Item(function=value.dump())
+ if isinstance(value, ClassStub):
+ return Item(class_def=value.dump())
if isinstance(value, ModuleStub):
return Item(module=value.name)
if isinstance(value, (int, str, float, bool, bytes, type(None))):
@@ -119,10 +148,18 @@ def from_item(item: Item) -> Any:
mod_stub = ModuleStub.__new__(ModuleStub)
mod_stub.name = item.module
return mod_stub
+ if item.import_ref is not None:
+ module, qualname = item.import_ref
+ obj: Any = importlib.import_module(module)
+ for part in qualname.split("."):
+ obj = getattr(obj, part)
+ return obj
if item.function is not None:
fn_stub = FunctionStub.__new__(FunctionStub)
fn_stub.code, fn_stub.filename, fn_stub.lineno = item.function
return fn_stub
+ if item.class_def is not None:
+ return ClassStub.from_dump(item.class_def)
if item.primitive is not None:
return item.primitive
return None
@@ -148,7 +185,12 @@ class LazyLoader(BasePersistenceLoader):
t.join()
self._pending.clear()
- def load_cache(self, key: HashKey) -> Cache | None:
+ def load_cache(
+ self,
+ key: HashKey,
+ glbls: dict[str, Any] | None = None,
+ ) -> Cache | None:
+ del glbls
try:
blob: bytes | None = self.store.get(str(self.build_path(key)))
if not blob:
@@ -166,12 +208,22 @@ class LazyLoader(BasePersistenceLoader):
ref_vars: dict[str, str] = {}
ref_type_hints: dict[str, str | None] = {}
variable_hashes: dict[str, str] = {}
+ # Instances of cell-defined (__main__) classes are deferred: their
+ # class must be re-exec'd into __main__ before the blob can unpickle.
+ # Cache.restore orders these after their class via `requires`.
+ deferred: dict[str, tuple[str, str]] = {}
for var_name, item in cache_data.defs.items():
if var_name in cache_data.ui_defs:
ref_vars[var_name] = (base / "ui.pickle").as_posix()
elif item.reference is not None:
- ref_vars[var_name] = item.reference
- ref_type_hints[item.reference] = item.type_hint
+ if item.type_hint and item.type_hint.startswith("__main__."):
+ deferred[var_name] = (
+ item.reference,
+ item.type_hint.rsplit(".", 1)[-1],
+ )
+ else:
+ ref_vars[var_name] = item.reference
+ ref_type_hints[item.reference] = item.type_hint
if item.hash:
variable_hashes[var_name] = item.hash
@@ -234,7 +286,20 @@ class LazyLoader(BasePersistenceLoader):
# Distribute to defs
defs: dict[str, Any] = {}
for var_name, item in cache_data.defs.items():
- if var_name in ref_vars:
+ if var_name in deferred:
+ ref, requires = deferred[var_name]
+ # Read the bytes now (via this loader's store); defer only
+ # the unpickle until Cache.restore has materialized the class.
+ raw = self.store.get(ref)
+ if not raw:
+ raise FileNotFoundError("Incomplete cache: missing blobs")
+ stub = ImmediateReferenceStub(
+ ReferenceStub(ref, hash_value=item.hash or "", blob=raw)
+ )
+ # Tag the cell class this instance needs materialized first.
+ stub.requires = requires
+ defs[var_name] = stub
+ elif var_name in ref_vars:
ref_key = ref_vars[var_name]
val = unpickled.get(ref_key)
if var_name in cache_data.ui_defs and isinstance(val, dict):
@@ -291,18 +356,23 @@ class LazyLoader(BasePersistenceLoader):
for var, obj in cache.defs.items():
loader = maybe_update_lazy_stub(obj)
- if loader == "ui":
- ui_vars[var] = obj
- ui_defs_list.append(var)
- elif loader not in ("inline",):
- format_vars.setdefault(loader, {})[var] = obj
- defs_dict[var] = to_item(
+ item = to_item(
path,
obj,
var_name=var,
loader=loader,
hash=variable_hashes.get(var, ""),
)
+ defs_dict[var] = item
+ if item.import_ref is not None:
+ # Re-importable reference: lives inline in the manifest,
+ # no blob to write.
+ continue
+ if loader == "ui":
+ ui_vars[var] = obj
+ ui_defs_list.append(var)
+ elif loader not in ("inline",):
+ format_vars.setdefault(loader, {})[var] = obj
manifest = msgspec.json.encode(
CacheSchema(
diff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.py
index f323123039..79fad423ec 100644
--- a/marimo/_save/loaders/loader.py
+++ b/marimo/_save/loaders/loader.py
@@ -122,9 +122,10 @@ class Loader(ABC):
defs: set[Name],
key: HashKey,
stateful_refs: set[Name],
+ glbls: dict[str, Any] | None = None,
) -> Cache:
start_time = time.time()
- loaded = self.load_cache(key)
+ loaded = self.load_cache(key, glbls=glbls)
if not loaded:
return Cache.empty(defs=defs, key=key, stateful_refs=stateful_refs)
load_time = time.time() - start_time
@@ -180,8 +181,14 @@ class Loader(ABC):
"""
@abstractmethod
- def load_cache(self, key: HashKey) -> Cache | None:
- """Load Cache"""
+ def load_cache(
+ self,
+ key: HashKey,
+ glbls: dict[str, Any] | None = None,
+ ) -> Cache | None:
+ """Load Cache. `glbls` is an optional cell namespace used by
+ loaders (e.g. `LazyLoader`) that need to resolve
+ `__main__`-qualified pickle refs against the live cell scope."""
@abstractmethod
def save_cache(self, cache: Cache) -> bool:
@@ -229,7 +236,12 @@ class BasePersistenceLoader(Loader):
return False
return self.store.put(str(self.build_path(cache.key)), blob)
- def load_cache(self, key: HashKey) -> Cache | None:
+ def load_cache(
+ self,
+ key: HashKey,
+ glbls: dict[str, Any] | None = None,
+ ) -> Cache | None:
+ del glbls # Base persistence loader doesn't need a cell namespace.
try:
blob: bytes | None = self.store.get(str(self.build_path(key)))
if not blob:
diff --git a/marimo/_save/loaders/memory.py b/marimo/_save/loaders/memory.py
index dd704a7c77..e38934ec8e 100644
--- a/marimo/_save/loaders/memory.py
+++ b/marimo/_save/loaders/memory.py
@@ -56,7 +56,12 @@ class MemoryLoader(Loader):
path = self.build_path(key)
return self._maybe_lock(lambda: path in self._cache)
- def load_cache(self, key: HashKey) -> Cache | None:
+ def load_cache(
+ self,
+ key: HashKey,
+ glbls: dict[str, Any] | None = None,
+ ) -> Cache | None:
+ del glbls # Memory loader doesn't need a cell namespace.
if not self.cache_hit(key):
return None
path = self.build_path(key)
diff --git a/marimo/_save/stubs/__init__.py b/marimo/_save/stubs/__init__.py
index d8b759b83b..6776bba76c 100644
--- a/marimo/_save/stubs/__init__.py
+++ b/marimo/_save/stubs/__init__.py
@@ -5,6 +5,7 @@ from __future__ import annotations
from typing import TYPE_CHECKING, Any
+from marimo._save.stubs.class_stub import ClassStub
from marimo._save.stubs.function_stub import FunctionStub
from marimo._save.stubs.lazy_stub import LAZY_STUB_LOOKUP, ReferenceStub
from marimo._save.stubs.module_stub import ModuleStub
@@ -77,6 +78,7 @@ def maybe_get_custom_stub(value: Any) -> CustomStub | None:
__all__ = [
"CUSTOM_STUBS",
"LAZY_STUB_LOOKUP",
+ "ClassStub",
"CustomStub",
"FunctionStub",
"ModuleStub",
diff --git a/marimo/_save/stubs/class_stub.py b/marimo/_save/stubs/class_stub.py
new file mode 100644
index 0000000000..e1f0ecbbea
--- /dev/null
+++ b/marimo/_save/stubs/class_stub.py
@@ -0,0 +1,147 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""ClassStub — source-based serialization for cell-defined classes.
+
+Pickle stores a class reference as `(__module__, __qualname__)`. For
+classes defined inside marimo cells the module is `"__main__"`, and dynamicall
+patched into the runtime.
+"""
+
+from __future__ import annotations
+
+import inspect
+import linecache
+import textwrap
+from typing import Any
+
+__all__ = ["ClassStub"]
+
+
+class ClassStub:
+ """Stub for class objects, storing the source code."""
+
+ def __init__(self, cls: Any, filename: str | None = None) -> None:
+ self.qualname = cls.__qualname__
+ # Classes don't have their own `__code__`/`co_filename` like
+ # functions do — they rely on `__module__` to find the source
+ # file.
+ method_code = self._find_code(target=cls)
+ if method_code is None and filename is None:
+ # Fallback: trust inspect.getsource. Raises if unsourcable.
+ self.code = textwrap.dedent(inspect.getsource(cls))
+ return
+
+ filename = (
+ method_code.co_filename if method_code is not None else filename
+ )
+ if filename is None:
+ raise ValueError("No filename, invalid load")
+
+ lines = linecache.getlines(filename)
+ if not lines:
+ raise OSError(
+ f"No source available for {cls.__name__} in {filename!r}"
+ )
+ lineno = vars(cls).get("__firstlineno__")
+ if lineno is None and method_code is not None:
+ # Older Python (no `__firstlineno__`): anchor on the class's own
+ # method, scanning upward from its line to the nearest enclosing
+ # `class <name>` statement. Tying the lineno to a real code object
+ # of *this* class avoids matching a same-named earlier (redefined)
+ # class higher in the file.
+ for idx in range(
+ min(method_code.co_firstlineno, len(lines)) - 1, -1, -1
+ ):
+ if lines[idx].lstrip().startswith(f"class {cls.__name__}"):
+ lineno = idx + 1
+ break
+ if lineno is None:
+ # Last resort (no method code object): forward scan by name.
+ for idx, line in enumerate(lines):
+ if line.lstrip().startswith(f"class {cls.__name__}"):
+ lineno = idx + 1
+ break
+ if lineno is None:
+ raise OSError(
+ f"Could not locate class {cls.__name__} in {filename!r}"
+ )
+ block = inspect.getblock(lines[lineno - 1 :])
+ self.code = textwrap.dedent("".join(block))
+
+ @staticmethod
+ def _find_code(target: Any) -> Any:
+ """Return a `__code__` object from a callable defined on *target*,
+ or `None` if none is found (e.g. `type(...)`-built or attribute-only
+ classes). Unwraps descriptor-wrapped callables — `staticmethod`,
+ `classmethod`, and `property` — which don't expose `__code__`
+ directly, so classes defining only those still resolve a filename."""
+ for attr in vars(target).values():
+ code = getattr(attr, "__code__", None)
+ if code is None:
+ func = getattr(attr, "__func__", None) or getattr(
+ attr, "fget", None
+ )
+ code = getattr(func, "__code__", None)
+ if code is not None:
+ return code
+ return None
+
+ def load(self, glbls: dict[str, Any]) -> Any:
+ """Reconstruct the class by executing its source in *glbls*.
+
+ The filename is derived from the loading cell (see
+ `_load_filename`); `linecache` is seeded under that class-specific
+ key so tracebacks render the source without clobbering the cell's
+ own entry.
+ """
+ bare_name = self.qualname.rsplit(".", 1)[-1]
+ filename = self._load_filename(bare_name)
+ linecache.cache[filename] = (
+ len(self.code),
+ None,
+ [line + "\n" for line in self.code.splitlines()],
+ filename,
+ )
+ # Exec into glbls directly so the class lands in the cell namespace
+ # under its bare name. (No lcls dict — top-level class statements
+ # must execute against glbls for cross-cell references to bind.)
+ #
+ # On a cache hit glbls is the cell namespace, i.e.
+ # `sys.modules["__main__"].__dict__`, so this also registers the
+ # class as `__main__.<name>` — which is exactly what `pickle.loads`
+ # uses to resolve instances of it (no custom unpickler needed).
+ exec(compile(self.code, filename, "exec"), glbls)
+ return glbls.get(bare_name)
+
+ @staticmethod
+ def _load_filename(bare_name: str) -> str:
+ """Filename for compiling the class source: the *loading* cell's
+ file when a kernel context exists, else a synthetic name. Suffixed
+ by the class name so seeding `linecache` does not overwrite the
+ cell's own source entry."""
+ try:
+ from marimo._ast.compiler import get_filename
+ from marimo._runtime.context import (
+ ContextNotInitializedError,
+ get_context,
+ )
+
+ ctx = get_context().execution_context
+ if ctx is not None:
+ return get_filename(ctx.cell_id, suffix=bare_name)
+ except (ContextNotInitializedError, AssertionError):
+ pass
+ return f"<{bare_name}>"
+
+ def dump(self) -> tuple[str, str]:
+ """Dump source + qualname for lazy serialization."""
+ return self.code, self.qualname
+
+ @classmethod
+ def from_dump(cls, dump: tuple[str, str]) -> ClassStub:
+ """Reconstruct a `ClassStub` from a `dump()` tuple.
+
+ Skips `__init__` (which requires a live class to introspect).
+ """
+ stub = cls.__new__(cls)
+ stub.code, stub.qualname = dump
+ return stub
diff --git a/marimo/_save/stubs/lazy_stub.py b/marimo/_save/stubs/lazy_stub.py
index c64b2d3974..a6f3348ac2 100644
--- a/marimo/_save/stubs/lazy_stub.py
+++ b/marimo/_save/stubs/lazy_stub.py
@@ -17,6 +17,8 @@ from marimo._save.stubs.stubs import CustomStub
if TYPE_CHECKING:
from collections.abc import Callable
+ from marimo._runtime.exceptions import MarimoUnhashableCacheError
+
class CacheType(Enum):
CONTEXT_EXECUTION_PATH = "ContextExecutionPath"
@@ -36,8 +38,16 @@ class Item(msgspec.Struct):
primitive: Any | None = None
reference: str | None = None
module: str | None = None
+ # (module, qualname) of a value re-importable by name — e.g.
+ # `from typing import Optional` or `from os.path import join`. Stored
+ # inline so trivial imported references never get their own blob on disk.
+ import_ref: tuple[str, str] | None = None
# (code, filename, linenumber)
function: tuple[str, str, int] | None = None
+ # (code, qualname) — cell-defined class source. Materialized into the
+ # cell namespace (and __main__) before pickle blobs deserialize, so
+ # __main__-qualified instances can resolve their type.
+ class_def: tuple[str, str] | None = None
hash: str | None = None
# Fully-qualified class name of the original value — used by format-aware
# deserializers (e.g. to distinguish pandas from polars Arrow blobs).
@@ -50,7 +60,9 @@ class Item(msgspec.Struct):
self.primitive,
self.reference,
self.module,
+ self.import_ref,
self.function,
+ self.class_def,
]
if field is not None
)
@@ -87,14 +99,18 @@ class Cache(msgspec.Struct):
# "pickle" — per-variable .pickle blob (default fallback)
# "npy" — numpy .npy blob
# "arrow" — Arrow IPC .arrow blob (polars and pandas)
+# "pt" — torch .pt blob (torch.save / torch.load)
LAZY_STUB_LOOKUP: dict[str, str] = {
"builtins.int": "inline",
"builtins.str": "inline",
"builtins.float": "inline",
"builtins.bool": "inline",
- "builtins.bytes": "inline",
+ # bytes can't round-trip through JSON (msgspec encodes as base64
+ # but decodes back as str with Any type). Use pickle instead.
+ "builtins.bytes": "pickle",
"builtins.NoneType": "inline",
"marimo._save.stubs.function_stub.FunctionStub": "inline",
+ "marimo._save.stubs.class_stub.ClassStub": "inline",
"marimo._save.stubs.module_stub.ModuleStub": "inline",
"marimo._save.stubs.ui_element_stub.UIElementStub": "ui",
# Optional third-party types — imported lazily only when encountered:
@@ -106,6 +122,9 @@ LAZY_STUB_LOOKUP: dict[str, str] = {
"pandas.core.frame.DataFrame": "arrow",
"pandas.Series": "arrow",
"pandas.core.series.Series": "arrow",
+ # Subclasses (e.g. torch.nn.Parameter) resolve here through the MRO
+ # walk in maybe_update_lazy_stub; torch.save round-trips them intact.
+ "torch.Tensor": "pt",
}
# Runtime cache: type → loader string, populated by maybe_update_lazy_stub().
@@ -150,6 +169,17 @@ def _arrow_load(data: bytes, type_hint: str | None = None) -> Any:
return result
+def _pt_load(data: bytes, type_hint: str | None = None) -> Any:
+ DependencyManager.torch.require("to load cached torch tensors.")
+ import torch # type: ignore[import-not-found]
+
+ del type_hint
+ # weights_only restricts unpickling to tensor payloads; a tensor saved
+ # on an unavailable device fails loudly here, and the cache falls back
+ # to recomputation rather than silently relocating the value.
+ return torch.load(io.BytesIO(data), weights_only=True)
+
+
def _pickle_load(data: bytes, type_hint: str | None = None) -> Any:
del type_hint
return pickle.loads(data)
@@ -159,6 +189,7 @@ BLOB_DESERIALIZERS: dict[str, Callable[[bytes, str | None], Any]] = {
".pickle": _pickle_load,
".npy": _npy_load,
".arrow": _arrow_load,
+ ".pt": _pt_load,
}
# ---------------------------------------------------------------------------
@@ -198,10 +229,20 @@ def _arrow_dump(obj: Any) -> bytes:
return buf.getvalue()
+def _pt_dump(obj: Any) -> bytes:
+ DependencyManager.torch.require("to dump torch tensors.")
+ import torch # type: ignore[import-not-found]
+
+ buf = io.BytesIO()
+ torch.save(obj, buf)
+ return buf.getvalue()
+
+
BLOB_SERIALIZERS: dict[str, Callable[[Any], bytes]] = {
"pickle": pickle.dumps,
"npy": _npy_dump,
"arrow": _arrow_dump,
+ "pt": _pt_dump,
}
# ---------------------------------------------------------------------------
@@ -213,11 +254,19 @@ class ReferenceStub:
"""Deferred blob reference — loads from store on access."""
def __init__(
- self, name: str, loader: str | None = None, hash_value: str = ""
+ self,
+ name: str,
+ loader: str | None = None,
+ hash_value: str = "",
+ blob: bytes | None = None,
) -> None:
self.name = name
self.loader = loader
self.hash = hash_value
+ # Preloaded bytes — set when the caller has already read the blob
+ # (e.g. the lazy loader, which uses its own store) and only the
+ # deserialization is being deferred.
+ self._blob = blob
def load(self, glbls: dict[str, Any]) -> Any:
del glbls
@@ -227,6 +276,8 @@ class ReferenceStub:
return pickle.loads(blob)
def to_bytes(self) -> bytes:
+ if self._blob is not None:
+ return self._blob
maybe_bytes = get_store().get(self.name)
return maybe_bytes if maybe_bytes else b""
@@ -236,6 +287,10 @@ class ImmediateReferenceStub(CustomStub):
def __init__(self, reference: ReferenceStub) -> None:
self.reference = reference
+ # Name of a cell-defined class this value's type needs materialized
+ # before it can unpickle; empty when there's no such dependency.
+ # Consumed by `Cache.restore` for dependency ordering.
+ self.requires: str = ""
def load(self, glbls: dict[str, Any]) -> Any:
return self.reference.load(glbls)
@@ -246,3 +301,99 @@ class ImmediateReferenceStub(CustomStub):
def to_bytes(self) -> bytes:
return self.reference.to_bytes()
+
+
+class UnhashableStub(CustomStub):
+ """Marker + tripwire for a def that could not be serialized for caching.
+
+ Written to the cache as a placeholder when per-def pickling fails (e.g.
+ a lambda, a closure over an unpicklable object). The marker is placed
+ in scope as-is by `Cache.restore` (no `.load()` call). It is
+ harmless when the consumer cell never touches it; any meaningful access
+ (call) raises `MarimoUnhashableCacheError` carrying
+ `variables=[var_name]` so the runner can identify the defining cell,
+ invalidate its manifest, and re-queue.
+
+ Detection happens at use-site, not at pre-execution. Bodies that don't
+ touch the stub run normally; closure-captured stubs surface through
+ whichever access the user code performs.
+
+ UnhashableStub is created on-demand by the loader and is not
+ registered in CUSTOM_STUBS — `get_type()` raises since no specific
+ value type maps to it.
+
+ `__marimo_unhashable__` is a class-level protocol marker: runtime
+ consumers (e.g. a cached-execution pre-flight) detect stubs through
+ the attribute rather than importing this class, keeping the runtime
+ and serialization layers independently mergeable.
+ """
+
+ __marimo_unhashable__ = True
+
+ __slots__ = ("error_msg", "type_name", "var_name")
+
+ def __init__(
+ self,
+ _obj: Any = None,
+ var_name: str = "",
+ error_msg: str = "",
+ ) -> None:
+ self.var_name = var_name
+ if _obj is not None:
+ value_type = type(_obj)
+ self.type_name = (
+ f"{getattr(value_type, '__module__', '<unknown>')}."
+ f"{getattr(value_type, '__name__', '<unknown>')}"
+ )
+ else:
+ self.type_name = "<unknown>"
+ self.error_msg = error_msg or "value could not be pickled for cache"
+
+ def _trip(self) -> MarimoUnhashableCacheError:
+ from marimo._runtime.exceptions import MarimoUnhashableCacheError
+
+ return MarimoUnhashableCacheError(
+ cells_to_rerun=set(),
+ variables=[self.var_name] if self.var_name else [],
+ error_details=(
+ f"{self.var_name} ({self.type_name}): {self.error_msg}"
+ if self.var_name
+ else f"({self.type_name}): {self.error_msg}"
+ ),
+ )
+
+ def load(self, glbls: dict[str, Any]) -> Any:
+ del glbls
+ raise self._trip()
+
+ # __call__ is the only tripwire: it covers the canonical user-code
+ # use pattern (`classic(x)`, `foo()` where foo's closure captures
+ # the stub) that produces `'UnhashableStub' object is not callable`.
+ # Other dunders (__getattr__, __getitem__, __iter__, __len__, …)
+ # deliberately fall through to Python defaults so framework probes
+ # (`getattr(value, "_repr_mimebundle_", None)`, isinstance, hasattr,
+ # storage-engine introspection, etc.) stay inert. A body that uses
+ # the stub through a non-call access raises a generic TypeError
+ # instead of the cleaner trip — acceptable trade-off; the alternative
+ # over-trips on framework probes and cancels innocent cells.
+ def __call__(self, *args: Any, **kwargs: Any) -> Any:
+ del args, kwargs
+ raise self._trip()
+
+ def __repr__(self) -> str:
+ return (
+ f"<UnhashableStub var_name={self.var_name!r} "
+ f"type={self.type_name!r}>"
+ )
+
+ @staticmethod
+ def get_type() -> type:
+ # UnhashableStub does not correspond to a specific value type — it's
+ # written on-demand by the loader when pickling fails. Not registered
+ # in CUSTOM_STUBS.
+ raise NotImplementedError(
+ "UnhashableStub is not registered for a specific type"
+ )
+
+ def to_bytes(self) -> bytes:
+ return pickle.dumps(self)
diff --git a/marimo/_save/stubs/module_stub.py b/marimo/_save/stubs/module_stub.py
index caa04e34d0..a58bf6ddd9 100644
--- a/marimo/_save/stubs/module_stub.py
+++ b/marimo/_save/stubs/module_stub.py
@@ -2,9 +2,33 @@
from __future__ import annotations
import importlib
+from types import ModuleType
from typing import Any
-__all__ = ["ModuleStub"]
+__all__ = ["MissingModule", "ModuleStub"]
+
+
+class MissingModule(ModuleType):
+ """Placeholder for a cached module def that is unimportable here.
+
+ Enables loading a cache lazily until a module is actually needed.
+ """
+
+ def __init__(self, name: str) -> None:
+ super().__init__(name)
+ self.__missing__ = True
+
+ def __getattr__(self, attr: str) -> Any:
+ if attr.startswith("__") and attr.endswith("__"):
+ # Dunder probes — pickling machinery, repr, and
+ # getattr-with-default version lookups — must fall back
+ # rather than propagate an import error.
+ raise AttributeError(attr)
+ raise ModuleNotFoundError(
+ f"No module named {self.__name__!r} in this environment "
+ f"(cached def restored lazily; accessing "
+ f"{self.__name__}.{attr} requires the real module)"
+ )
class ModuleStub:
@@ -15,5 +39,22 @@ class ModuleStub:
self.hash = hash
def load(self) -> Any:
- """Reload the module by name."""
- return importlib.import_module(self.name)
+ """Reload the module by name.
+
+ Falls back to a `MissingModule` placeholder when the module itself
+ is absent, so restoration succeeds and the error surfaces only on
+ actual use. A `ModuleNotFoundError` for a *different* module — i.e.
+ a transitive import the module performs internally — is re-raised
+ rather than masked as "this module is missing".
+ """
+ try:
+ return importlib.import_module(self.name)
+ except ModuleNotFoundError as e:
+ missing = getattr(e, "name", None)
+ if (
+ missing is None
+ or missing == self.name
+ or self.name.startswith(f"{missing}.")
+ ):
+ return MissingModule(self.name)
+ raise
diff --git a/tests/_save/loaders/mocks.py b/tests/_save/loaders/mocks.py
index 37a6b6ccf3..895205a322 100644
--- a/tests/_save/loaders/mocks.py
+++ b/tests/_save/loaders/mocks.py
@@ -31,7 +31,8 @@ class MockLoader(Loader):
def cache_hit(self, _) -> bool:
return self._cache_hit
- def load_cache(self, key) -> Cache | None:
+ def load_cache(self, key, glbls=None) -> Cache | None:
+ del glbls
if not self._cache_hit:
return None
self._loaded = True
diff --git a/tests/_save/loaders/test_class_roundtrip.py b/tests/_save/loaders/test_class_roundtrip.py
new file mode 100644
index 0000000000..3e047bc8b6
--- /dev/null
+++ b/tests/_save/loaders/test_class_roundtrip.py
@@ -0,0 +1,122 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""End-to-end: a cell-defined class survives a cache save/restore cycle as
+a usable class (not a leftover ClassStub) through both the pickle and lazy
+loaders.
+
+This is the behavior behind `with mo.persistent_cache(...): class Foo: ...`
+— on a cache hit the second run must restore `Foo` as a real class so
+`Foo()` / `isinstance(..., Foo)` work.
+"""
+
+from __future__ import annotations
+
+import linecache
+from typing import Any
+
+import pytest
+
+from marimo._save.cache import Cache
+from marimo._save.loaders import LazyLoader, PickleLoader
+from marimo._save.stores.file import FileStore
+
+CELL_FILENAME = "__marimo__cell_RtRt_.py"
+
+# Source for a fake marimo cell defining three flavors of class.
+CELL_SRC = (
+ "class WithMethod:\n"
+ " def __init__(self, v: int = 0) -> None:\n"
+ " self.v = v\n"
+ "\n"
+ " def doubled(self) -> int:\n"
+ " return self.v * 2\n"
+ "\n"
+ "class OnlyStatic:\n"
+ " @staticmethod\n"
+ " def f() -> int:\n"
+ " return 7\n"
+ "\n"
+ "class JustAttrs:\n"
+ " x = 1\n"
+)
+
+
+def cell_namespace() -> dict[str, Any]:
+ linecache.cache[CELL_FILENAME] = (
+ len(CELL_SRC),
+ None,
+ [line + "\n" for line in CELL_SRC.splitlines()],
+ CELL_FILENAME,
+ )
+ glbls: dict[str, Any] = {"__name__": "__main__"}
+ exec(compile(CELL_SRC, CELL_FILENAME, "exec"), glbls)
+ yield glbls
+ linecache.cache.pop(CELL_FILENAME, None)
+
+
+def _make_loader(kind: str, save_path: str):
+ store = FileStore(save_path=save_path)
+ if kind == "pickle":
+ return PickleLoader("test", store=store)
+ return LazyLoader("test", store=store)
+
+
+def _round_trip(loader: Any, cache: Cache) -> Cache:
+ """Persist `cache` through `loader` and read it back."""
+ if isinstance(loader, PickleLoader):
+ blob = loader.to_blob(cache)
+ return loader.restore_cache(cache.key, blob)
+ # LazyLoader writes blobs on a background thread.
+ assert loader.save_cache(cache)
+ loader.flush()
+ loaded = loader.load_cache(cache.key)
+ assert loaded is not None
+ return loaded
+
+
[email protected]("kind", ["pickle", "lazy"])
[email protected]("var", ["WithMethod", "OnlyStatic", "JustAttrs"])
+def test_class_round_trip(
+ kind: str,
+ var: str,
+ cell_namespace: dict[str, Any],
+ tmp_path: Any,
+ monkeypatch: pytest.MonkeyPatch,
+) -> None:
+ cls = cell_namespace[var]
+ # Simulate the runtime context's cell filename so attribute-only
+ # classes (no method code object) source from linecache.
+ monkeypatch.setattr(
+ Cache, "_cell_filename", staticmethod(lambda: CELL_FILENAME)
+ )
+
+ cache = Cache(
+ defs={var: cls},
+ hash="classhash",
+ cache_type="Pure",
+ stateful_refs=set(),
+ hit=False,
+ meta={},
+ )
+ cache.update({var: cls})
+ # The class was converted to a ClassStub for serialization.
+ from marimo._save.stubs import ClassStub
+
+ assert isinstance(cache.defs[var], ClassStub)
+
+ loader = _make_loader(kind, str(tmp_path))
+ loaded = _round_trip(loader, cache)
+
+ scope: dict[str, Any] = {"__name__": "__main__"}
+ loaded.restore(scope)
+
+ restored = scope[var]
+ assert isinstance(restored, type), (
+ f"{var} restored as {type(restored)}, expected a class"
+ )
+ if var == "WithMethod":
+ assert restored(5).doubled() == 10
+ elif var == "OnlyStatic":
+ assert restored.f() == 7
+ else:
+ assert restored.x == 1
diff --git a/tests/_save/loaders/test_loader.py b/tests/_save/loaders/test_loader.py
index cde916b69e..4310089e97 100644
--- a/tests/_save/loaders/test_loader.py
+++ b/tests/_save/loaders/test_loader.py
@@ -256,6 +256,39 @@ class TestLazyLoader(ABCTestLoader):
assert loaded.defs["y"] == "hello"
assert loaded.defs["z"] == [1, 2, 3]
+ def test_import_reference_stays_inline(self) -> None:
+ """Re-importable references (`from typing import Optional`, an
+ imported function/class) are stored inline in the manifest, not as
+ per-variable blobs, and restore to the original object by identity."""
+ from collections import OrderedDict
+ from typing import Optional
+
+ loader = self.instance()
+ cache = Cache(
+ defs={"Optional": Optional, "OrderedDict": OrderedDict},
+ hash="import_ref_hash",
+ cache_type="Pure",
+ stateful_refs=set(),
+ hit=False,
+ meta={"version": MARIMO_CACHE_VERSION},
+ )
+ cache.update({"Optional": Optional, "OrderedDict": OrderedDict})
+ assert loader.save_cache(cache)
+ loader.flush()
+
+ # No blob files — only the manifest is written.
+ blobs = [
+ p
+ for p in Path(self.store.save_path).rglob("*")
+ if p.is_file() and p.suffix != ".jsonl"
+ ]
+ assert not blobs, f"expected no blobs, found {blobs}"
+
+ loaded = loader.load_cache(key("import_ref_hash", "Pure"))
+ assert loaded is not None
+ assert loaded.defs["Optional"] is Optional
+ assert loaded.defs["OrderedDict"] is OrderedDict
+
def test_corrupt_cache_returns_none(self) -> None:
"""Corrupt manifest triggers cache miss, not crash."""
loader = self.instance()
@@ -339,6 +372,34 @@ class TestLazyLoader(ABCTestLoader):
assert loaded is not None
np.testing.assert_array_equal(loaded.defs["arr"], arr)
+ @pytest.mark.skipif(
+ not DependencyManager.has("torch"), reason="torch required"
+ )
+ def test_torch_round_trip(self) -> None:
+ """torch tensors survive save → flush → load via the .pt format —
+ the manifest reference must match the blob extension."""
+ import torch
+
+ loader = self.instance()
+ tensor = torch.tensor([1.0, 2.0, 3.0])
+ cache = Cache(
+ defs={"t": tensor},
+ hash="pt_hash",
+ cache_type="Pure",
+ stateful_refs=set(),
+ hit=False,
+ meta={"version": MARIMO_CACHE_VERSION},
+ )
+ assert loader.save_cache(cache)
+ loader.flush()
+
+ assert list(Path(self.store.save_path).rglob("*.pt")), (
+ "expected .pt blob, got pickle fallback"
+ )
+ loaded = loader.load_cache(key("pt_hash", "Pure"))
+ assert loaded is not None
+ assert torch.equal(loaded.defs["t"], tensor)
+
@pytest.mark.skipif(
not DependencyManager.has("polars"), reason="polars required"
)
diff --git a/tests/_save/stubs/test_class_stub.py b/tests/_save/stubs/test_class_stub.py
new file mode 100644
index 0000000000..be123815e5
--- /dev/null
+++ b/tests/_save/stubs/test_class_stub.py
@@ -0,0 +1,203 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Tests for ClassStub — source-based serialization of cell-defined classes."""
+
+from __future__ import annotations
+
+import linecache
+import sys
+import tempfile
+import textwrap
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from marimo._save.stubs.class_stub import ClassStub
+
+
+class TestClassStubBasics:
+ @staticmethod
+ def test_load_populates_glbls() -> None:
+ """ClassStub.load returns the class AND leaves it in glbls
+ so subsequent pickle deserialization can find it."""
+ # Build a ClassStub by hand from a known dump.
+ code = textwrap.dedent(
+ """
+ class Bar:
+ value = 42
+ """
+ )
+ stub = ClassStub.from_dump((code, "Bar"))
+ glbls: dict[str, Any] = {"__name__": "__main__"}
+ cls = stub.load(glbls)
+ assert cls is not None
+ assert cls.__name__ == "Bar"
+ assert glbls["Bar"] is cls
+ assert cls.value == 42
+
+ @staticmethod
+ def test_load_seeds_linecache_for_traceback() -> None:
+ """Outside a kernel context, load compiles under a synthetic
+ per-class filename and seeds linecache so tracebacks render the
+ class source."""
+ code = textwrap.dedent(
+ """
+ class Baz:
+ def hello(self) -> str:
+ return "hi"
+ """
+ )
+ synth_name = "<Baz>"
+ linecache.cache.pop(synth_name, None)
+ stub = ClassStub.from_dump((code, "Baz"))
+ glbls: dict[str, Any] = {"__name__": "__main__"}
+ stub.load(glbls)
+ assert synth_name in linecache.cache
+ assert glbls["Baz"]().hello() == "hi"
+
+
+class TestClassStubFromLiveClass:
+ @staticmethod
+ def test_from_live_class_in_temp_module() -> None:
+ """End-to-end: take a live class from a temp module, ClassStub it,
+ round-trip through dump/from_dump, and verify the class works."""
+ src = textwrap.dedent(
+ """
+ class Widget:
+ def __init__(self, n: int) -> None:
+ self.n = n
+
+ def squared(self) -> int:
+ return self.n * self.n
+ """
+ )
+ with tempfile.NamedTemporaryFile("w", suffix=".py", delete=False) as f:
+ f.write(src)
+ tmp_path = f.name
+ module_name = "_test_class_stub_live"
+ try:
+ module = type(sys)(module_name)
+ module.__file__ = tmp_path
+ sys.modules[module_name] = module
+ # Populate linecache so inspect.getsource works.
+ linecache.cache[tmp_path] = (
+ len(src),
+ None,
+ [line + "\n" for line in src.splitlines()],
+ tmp_path,
+ )
+ exec(compile(src, tmp_path, "exec"), module.__dict__)
+ cls = module.Widget
+
+ stub = ClassStub(cls)
+ dump = stub.dump()
+ assert "class Widget" in dump[0]
+
+ # Reload in a vacuum.
+ fresh_stub = ClassStub.from_dump(dump)
+ fresh_glbls: dict[str, Any] = {"__name__": "__main__"}
+ fresh_stub.load(fresh_glbls)
+ assert fresh_glbls["Widget"](5).squared() == 25
+ finally:
+ sys.modules.pop(module_name, None)
+ linecache.cache.pop(tmp_path, None)
+ Path(tmp_path).unlink(missing_ok=True)
+
+
+class TestClassStubSourceResolution:
+ """Filename/lineno resolution for awkward cell-defined classes."""
+
+ @staticmethod
+ def _seed_cell(src: str) -> tuple[str, dict[str, Any]]:
+ """Compile `src` under a fake cell filename, registering it in
+ linecache the way marimo's compiler does, and return
+ (filename, namespace)."""
+ filename = "__marimo__cell_TeSt_.py"
+ linecache.cache[filename] = (
+ len(src),
+ None,
+ [line + "\n" for line in src.splitlines()],
+ filename,
+ )
+ glbls: dict[str, Any] = {"__name__": "__main__"}
+ exec(compile(src, filename, "exec"), glbls)
+ return filename, glbls
+
+ def test_redefined_class_captures_live_definition(self) -> None:
+ """When a class name is defined twice, the stub must capture the
+ live (latest) definition's source, not a stale earlier one."""
+ src = textwrap.dedent(
+ """
+ class Dup:
+ def tag(self) -> str:
+ return "old"
+
+ class Dup:
+ def tag(self) -> str:
+ return "new"
+ """
+ ).strip()
+ filename, glbls = self._seed_cell(src)
+ try:
+ stub = ClassStub(glbls["Dup"], filename=filename)
+ assert '"new"' in stub.code
+ assert '"old"' not in stub.code
+ fresh: dict[str, Any] = {"__name__": "__main__"}
+ assert stub.load(fresh)().tag() == "new"
+ finally:
+ linecache.cache.pop(filename, None)
+
+ def test_staticmethod_only_class_resolves(self) -> None:
+ """A class whose only callable is a staticmethod has no plain
+ method `__code__`; the stub must unwrap the descriptor to find
+ the source filename."""
+ src = textwrap.dedent(
+ """
+ class OnlyStatic:
+ @staticmethod
+ def f() -> int:
+ return 7
+ """
+ ).strip()
+ filename, glbls = self._seed_cell(src)
+ try:
+ stub = ClassStub(glbls["OnlyStatic"], filename=filename)
+ assert "class OnlyStatic" in stub.code
+ fresh: dict[str, Any] = {"__name__": "__main__"}
+ assert stub.load(fresh).f() == 7
+ finally:
+ linecache.cache.pop(filename, None)
+
+ def test_attribute_only_class_resolves_with_hint(self) -> None:
+ """A body-only class (no callables at all) has no code object to
+ read a filename from; the cache layer's filename hint lets it
+ source from linecache anyway."""
+ src = textwrap.dedent(
+ """
+ class JustAttrs:
+ x = 1
+ y = 2
+ """
+ ).strip()
+ filename, glbls = self._seed_cell(src)
+ try:
+ stub = ClassStub(glbls["JustAttrs"], filename=filename)
+ fresh: dict[str, Any] = {"__name__": "__main__"}
+ restored = stub.load(fresh)
+ assert restored.x == 1
+ assert restored.y == 2
+ finally:
+ linecache.cache.pop(filename, None)
+
+
+class TestClassStubFailures:
+ @staticmethod
+ def test_unsourcable_class_raises_on_init() -> None:
+ """A class with no discoverable source (e.g. built via type())
+ cannot be ClassStub'd. The error must surface at construction
+ time so the save path can fall back to UnhashableStub before
+ writing a corrupt blob."""
+ # type(...) classes have no source file inspect can find.
+ DynCls = type("DynCls", (), {"x": 1})
+ with pytest.raises((TypeError, OSError)):
+ ClassStub(DynCls)
diff --git a/tests/_save/stubs/test_module_stub.py b/tests/_save/stubs/test_module_stub.py
new file mode 100644
index 0000000000..423c4b9ac6
--- /dev/null
+++ b/tests/_save/stubs/test_module_stub.py
@@ -0,0 +1,64 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Tests for ModuleStub — name-based serialization of module objects."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+import pytest
+
+from marimo._save.stubs.module_stub import MissingModule, ModuleStub
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+
+class TestModuleStubLoad:
+ @staticmethod
+ def test_load_existing_module() -> None:
+ """An importable module is returned as the real module."""
+ import json
+
+ stub = ModuleStub(json)
+ assert stub.load() is json
+
+ @staticmethod
+ def test_missing_module_returns_placeholder() -> None:
+ """A module absent from this environment restores to a
+ MissingModule placeholder rather than raising."""
+ stub = ModuleStub.__new__(ModuleStub)
+ stub.name = "marimo_definitely_not_a_real_module_xyz"
+ stub.hash = ""
+ result = stub.load()
+ assert isinstance(result, MissingModule)
+ assert result.__missing__ is True
+ # Accessing an attribute surfaces the deferred import error.
+ with pytest.raises(ModuleNotFoundError):
+ _ = result.some_attr
+
+ @staticmethod
+ def test_transitive_import_failure_reraises(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+ ) -> None:
+ """A module that *exists* but fails on an internal import of a
+ different missing module must NOT be masked as "this module is
+ missing" — the real ModuleNotFoundError is re-raised."""
+ mod_name = "_marimo_transitive_stub_test"
+ (tmp_path / f"{mod_name}.py").write_text(
+ "import a_module_that_truly_does_not_exist_zzz\n"
+ )
+ monkeypatch.syspath_prepend(str(tmp_path))
+ sys.modules.pop(mod_name, None)
+ try:
+ stub = ModuleStub.__new__(ModuleStub)
+ stub.name = mod_name
+ stub.hash = ""
+ with pytest.raises(ModuleNotFoundError) as exc_info:
+ stub.load()
+ # The error is about the transitive dep, not our module.
+ assert (
+ exc_info.value.name == "a_module_that_truly_does_not_exist_zzz"
+ )
+ finally:
+ sys.modules.pop(mod_name, None)
diff --git a/tests/_save/stubs/test_unhashable_stub.py b/tests/_save/stubs/test_unhashable_stub.py
new file mode 100644
index 0000000000..d1df7acb12
--- /dev/null
+++ b/tests/_save/stubs/test_unhashable_stub.py
@@ -0,0 +1,162 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""UnhashableStub semantics: data, tripwire, and Cache.restore handling.
+
+Split from the cached-lifecycle suite: these tests exercise only the
+stub serialization toolkit (no runtime lifecycle involvement).
+"""
+
+from __future__ import annotations
+
+import pickle
+
+import pytest
+
+from marimo._runtime.exceptions import (
+ MarimoCancelCellError,
+ MarimoUnhashableCacheError,
+)
+from marimo._save.cache import Cache
+from marimo._save.stubs.lazy_stub import UnhashableStub
+
+# ---------------------------------------------------------------------------
+# UnhashableStub: data + tripwire semantics
+# ---------------------------------------------------------------------------
+
+
+class TestUnhashableStub:
+ def test_init_captures_type_info(self) -> None:
+ stub = UnhashableStub(
+ lambda x: x, var_name="f", error_msg="lambdas not pickleable"
+ )
+ assert stub.var_name == "f"
+ assert "function" in stub.type_name.lower()
+ assert stub.error_msg == "lambdas not pickleable"
+
+ def test_load_raises_unhashable_error(self) -> None:
+ stub = UnhashableStub(None, var_name="f", error_msg="cannot pickle")
+ with pytest.raises(MarimoUnhashableCacheError) as exc_info:
+ stub.load({})
+ assert "f" in exc_info.value.variables
+ assert "cannot pickle" in exc_info.value.error_details
+
+ def test_inherits_cancel_cell_parent(self) -> None:
+ """MarimoUnhashableCacheError funnels through the parent class
+ in the runner's classifier."""
+ err = MarimoUnhashableCacheError(
+ cells_to_rerun=set(), variables=[], error_details=""
+ )
+ assert isinstance(err, MarimoCancelCellError)
+
+ def test_pickle_roundtrip(self) -> None:
+ original = UnhashableStub(None, var_name="f", error_msg="oops")
+ original.type_name = "builtins.function"
+ round_tripped = pickle.loads(pickle.dumps(original))
+ assert round_tripped.var_name == "f"
+ assert round_tripped.type_name == "builtins.function"
+ assert round_tripped.error_msg == "oops"
+
+ def test_isinstance_works(self) -> None:
+ """Tripwires must not interfere with isinstance — the restore
+ path uses isinstance to decide whether to install the marker."""
+ stub = UnhashableStub(None, var_name="f")
+ assert isinstance(stub, UnhashableStub)
+
+ def test_repr_does_not_trip(self) -> None:
+ """repr is safe to invoke for debugging / logging."""
+ stub = UnhashableStub(None, var_name="f", error_msg="oops")
+ stub.type_name = "builtins.function"
+ text = repr(stub)
+ assert "UnhashableStub" in text
+ assert "f" in text
+
+
+class TestUnhashableStubTripwire:
+ """`__call__` is the only tripwire (see UnhashableStub docstring).
+
+ Other accesses deliberately fall through to Python defaults so
+ framework probes (`getattr(value, "_repr_mimebundle_", None)`,
+ `isinstance`, `hasattr`, storage-engine introspection, etc.) stay
+ inert and don't cancel innocent cells.
+ """
+
+ def _stub(self) -> UnhashableStub:
+ return UnhashableStub(None, var_name="x", error_msg="cannot pickle")
+
+ def test_call_trips(self) -> None:
+ with pytest.raises(MarimoUnhashableCacheError) as ei:
+ self._stub()(42)
+ assert ei.value.variables == ["x"]
+
+ def test_getattr_does_not_trip(self) -> None:
+ # Falls through to Python's default: a missing attribute raises
+ # AttributeError, not the cache tripwire.
+ with pytest.raises(AttributeError):
+ _ = self._stub().some_method
+
+ def test_len_does_not_trip(self) -> None:
+ with pytest.raises(TypeError):
+ len(self._stub())
+
+ def test_iter_does_not_trip(self) -> None:
+ with pytest.raises(TypeError):
+ list(self._stub())
+
+ def test_internal_attrs_dont_trip(self) -> None:
+ """var_name / type_name / error_msg / load / to_bytes are
+ intentionally accessible — pickling and the runner's classifier
+ rely on them."""
+ s = self._stub()
+ assert s.var_name == "x"
+ assert s.type_name == "<unknown>"
+ assert s.error_msg == "cannot pickle"
+ # load() raises (by design); just confirm the method is reachable.
+ with pytest.raises(MarimoUnhashableCacheError):
+ s.load({})
+ # to_bytes() pickles successfully.
+ assert s.to_bytes() == pickle.dumps(s)
+
+
+# ---------------------------------------------------------------------------
+# Cache.restore — total-restore semantics for UnhashableStub
+# ---------------------------------------------------------------------------
+
+
+class TestRestoreUnhashableMarker:
+ def test_top_level_marker_preserved(self) -> None:
+ """UnhashableStub at the top level of defs is placed in scope as-is,
+ not loaded (which would raise)."""
+ stub = UnhashableStub(None, var_name="f", error_msg="cannot pickle")
+ cache = Cache(
+ defs={"f": stub},
+ hash="h",
+ cache_type="ExecutionPath",
+ stateful_refs=set(),
+ hit=True,
+ meta={},
+ )
+ scope: dict[str, object] = {}
+ cache.restore(scope)
+ assert isinstance(scope["f"], UnhashableStub)
+
+ def test_nested_marker_in_container_preserved(self) -> None:
+ """UnhashableStub nested in tuple/list/dict survives the recursive
+ restore unchanged — the marker propagates instead of triggering
+ `.load()` (which raises)."""
+ stub = UnhashableStub(None, var_name="g", error_msg="cannot pickle")
+ cache = Cache(
+ defs={
+ "in_tuple": (1, stub, 3),
+ "in_list": [stub, "x"],
+ "in_dict": {"k": stub},
+ },
+ hash="h",
+ cache_type="ExecutionPath",
+ stateful_refs=set(),
+ hit=True,
+ meta={},
+ )
+ scope: dict[str, object] = {}
+ cache.restore(scope)
+ assert scope["in_tuple"][1] is stub # type: ignore[index]
+ assert scope["in_list"][0] is stub # type: ignore[index]
+ assert scope["in_dict"]["k"] is stub # type: ignore[index]
diff --git a/tests/_save/test_class_dependency_restore.py b/tests/_save/test_class_dependency_restore.py
new file mode 100644
index 0000000000..4ea090377c
--- /dev/null
+++ b/tests/_save/test_class_dependency_restore.py
@@ -0,0 +1,139 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Dependency-ordered restore for cell-defined classes/functions.
+
+A cached block may define classes and functions that reference each other
+(and instances of each other). On a cache hit the block is skipped, so the
+loader must reconstruct everything — and it must do so in dependency order,
+or exec/unpickle hits a NameError / missing-class error.
+"""
+
+from __future__ import annotations
+
+import linecache
+import textwrap
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+ from pathlib import Path
+
+ import pytest
+
+from marimo._runtime.patches import (
+ create_main_module,
+ patch_main_module_context,
+)
+from marimo._save.cache import Cache
+from marimo._save.hash import HashKey
+from marimo._save.loaders import LazyLoader
+from marimo._save.stores.file import FileStore
+
+CELL_FILENAME = "__marimo__cell_dep_.py"
+
+
+def _seed_linecache(src: str) -> None:
+ linecache.cache[CELL_FILENAME] = (
+ len(src),
+ None,
+ [line + "\n" for line in src.splitlines()],
+ CELL_FILENAME,
+ )
+
+
+def _save_then_restart_restore(
+ src: str,
+ names: list[str],
+ tmp_path: Path,
+ monkeypatch: pytest.MonkeyPatch,
+) -> dict[str, Any]:
+ """Run `src` in a fresh kernel main module, cache its `names`, then
+ simulate a kernel restart and restore into a brand-new main module.
+ Returns the restored namespace.
+ """
+ monkeypatch.setattr(
+ Cache, "_cell_filename", staticmethod(lambda: CELL_FILENAME)
+ )
+ _seed_linecache(src)
+
+ loader = LazyLoader("t", store=FileStore(save_path=str(tmp_path)))
+ key = HashKey(hash="dephash", cache_type="Pure")
+
+ # Original run + save — all under a patched __main__ so instances of
+ # cell-defined classes pickle against the right module.
+ original = create_main_module(None, None)
+ with patch_main_module_context(original):
+ exec(compile(src, CELL_FILENAME, "exec"), original.__dict__)
+ defs = {name: original.__dict__[name] for name in names}
+ cache = Cache(
+ defs=dict(defs),
+ hash=key.hash,
+ cache_type=key.cache_type,
+ stateful_refs=set(),
+ hit=False,
+ meta={},
+ )
+ cache.update(dict(defs))
+ assert loader.save_cache(cache)
+ loader.flush()
+
+ # Simulated restart: a fresh main module with none of the cell defs.
+ restarted = create_main_module(None, None)
+ with patch_main_module_context(restarted):
+ loaded = loader.load_cache(key)
+ assert loaded is not None, "cache failed to load after restart"
+ loaded.restore(restarted.__dict__)
+ return dict(restarted.__dict__)
+
+
+def test_function_class_ordering(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """`Foo`'s body calls `foo()` at class-definition time, so `foo` must
+ be reconstructed before `Foo`."""
+ src = textwrap.dedent(
+ """
+ def foo():
+ return 21
+
+ class Foo:
+ doubled = foo() * 2
+ """
+ ).strip()
+ scope = _save_then_restart_restore(
+ src, ["foo", "Foo"], tmp_path, monkeypatch
+ )
+ assert scope["foo"]() == 21
+ assert scope["Foo"].doubled == 42
+
+
+def test_instance_of_cell_class_restores(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The caveat case: `_baz` is an instance of the cell-defined class
+ `Bar`, so `Bar` must be materialized before `_baz` unpickles; `Foo`
+ depends on both `Bar` (annotation) and `foo` (called in its body)."""
+ src = textwrap.dedent(
+ """
+ class Bar:
+ def __init__(self, x: int):
+ self.x = x
+
+ _baz = Bar(7)
+
+ def foo():
+ return _baz
+
+ class Foo:
+ bar: Bar = foo()
+ """
+ ).strip()
+ scope = _save_then_restart_restore(
+ src, ["Bar", "_baz", "foo", "Foo"], tmp_path, monkeypatch
+ )
+
+ assert scope["Bar"](7).x == 7
+ assert scope["_baz"].x == 7
+ assert isinstance(scope["_baz"], scope["Bar"])
+ # foo returns the restored module-level _baz
+ assert scope["foo"]() is scope["_baz"]
+ # Foo.bar was computed as foo() at class-def time
+ assert scope["Foo"].bar is scope["_baz"]