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.
Python artificial-intelligencedagdata-sciencedata-visualizationdataflowdeveloper-toolsmachine-learningnotebookspipelinepythonreactivesqlweb-app
feat: expand cache api to match functools api (#6660)
Dylan Madisetti52663748b66d
diff --git a/marimo/_save/cache.py b/marimo/_save/cache.pyindex bc1d3fac84..6747b75d9a 100644--- a/marimo/_save/cache.py+++ b/marimo/_save/cache.py@@ -13,9 +13,21 @@ from marimo._plugins.ui._core.ui_element import S, T, UIElementfrom marimo._runtime.context import ContextNotInitializedError, get_contextfrom marimo._runtime.state import SetFunctor+# Many assertions are for typing and should always pass. This message is a+# catch all to motive users to report if something does fail.+UNEXPECTED_FAILURE_BOILERPLATE = (+ "— this is"+ " unexpected and is likely a bug in marimo. "+ "Please file an issue at "+ "https://github.com/marimo-team/marimo/issues"+)++if TYPE_CHECKING:from marimo._ast.visitor import Name+ from marimo._runtime.state import Statefrom marimo._save.hash import HashKey+ from marimo._save.loaders import Loader# NB. Increment on cache breaking changes.MARIMO_CACHE_VERSION: int = 3@@ -39,7 +51,11 @@ CACHE_PREFIX: dict[CacheType, str] = {}ValidCacheSha = namedtuple("ValidCacheSha", ("sha", "cache_type"))-MetaKey = Literal["return", "version"]+MetaKey = Literal["return", "version", "runtime"]+# Matches functools+CacheInfo = namedtuple(+ "CacheInfo", ["hits", "misses", "maxsize", "currsize", "time_saved"]+)class ModuleStub:@@ -351,3 +367,66 @@ class Cache:hit=True,meta=loaded.meta,)+++class CacheContext:+ """Tracks cache loader state and statistics.+ Base class for cache interfaces."""++ __slots__ = "_loader"+ _loader: Optional[State[Loader]]++ # Match functools api+ def cache_info(self) -> CacheInfo:+ return CacheInfo(+ hits=self.hits,+ misses=self.misses,+ maxsize=self.maxsize,+ currsize=self.currsize,+ time_saved=self.time_saved,+ )++ @property+ def loader(self) -> Loader:+ assert self._loader is not None, UNEXPECTED_FAILURE_BOILERPLATE+ return self._loader()++ def cache_clear(self) -> None:+ if self._loader is not None:+ self.loader.clear()++ @property+ def hits(self) -> int:+ if self._loader is None:+ return 0+ return self.loader.hits++ @property+ def misses(self) -> int:+ # Not something explicitly recorded.+ return 0++ @property+ def maxsize(self) -> int | None:+ if self._loader is None:+ return None+ maxsize = getattr(self.loader, "_max_size", -1)+ if maxsize < 0:+ return None+ return maxsize++ @property+ def currsize(self) -> int:+ if self._loader is None:+ return 0+ # Use current_size if available, otherwise fall back to misses+ if hasattr(self.loader, "current_size"):+ return int(self.loader.current_size)+ # Assume all misses leave an entry+ return self.misses++ @property+ def time_saved(self) -> float:+ if self._loader is None:+ return 0.0+ return self.loader.time_saveddiff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.pyindex f91fd6a839..89aba1ba84 100644--- a/marimo/_save/loaders/loader.py+++ b/marimo/_save/loaders/loader.py@@ -2,6 +2,7 @@from __future__ import annotationsimport re+import timefrom abc import ABC, abstractmethodfrom pathlib import Pathfrom typing import TYPE_CHECKING, Any, Optional@@ -109,6 +110,7 @@ class Loader(ABC):def __init__(self, name: str) -> None:self.name = nameself._hits = 0+ self._time_saved = 0.0def build_path(self, key: HashKey) -> Path:prefix = CACHE_PREFIX.get(key.cache_type, "U_")@@ -120,15 +122,25 @@ class Loader(ABC):key: HashKey,stateful_refs: set[Name],) -> Cache:+ start_time = time.time()loaded = self.load_cache(key)if not loaded:return Cache.empty(defs=defs, key=key, stateful_refs=stateful_refs)+ load_time = time.time() - start_time+# TODO: Consider more robust verificationif loaded.hash != key.hash:raise LoaderError("Hash mismatch in loaded cache.")if (defs | stateful_refs) != set(loaded.defs):raise LoaderError("Variable mismatch in loaded cache.")self._hits += 1++ # Track time savings: original runtime - time to load from cache+ runtime = loaded.meta.get("runtime", 0)+ if runtime > 0:+ time_saved = runtime - load_time+ self._time_saved += max(0, time_saved)+return Cache.new(loaded=loaded,key=key,@@ -139,6 +151,10 @@ class Loader(ABC):def hits(self) -> int:return self._hits+ @property+ def time_saved(self) -> float:+ return self._time_saved+@classmethoddef partial(cls, **kwargs: Any) -> LoaderPartial:return LoaderPartial(cls, **kwargs)@@ -170,6 +186,11 @@ class Loader(ABC):def save_cache(self, cache: Cache) -> bool:"""Save Cache"""+ def clear(self) -> None:+ """Clear all cached items. Default implementation does nothing."""+ # Default implementation: no-op for loaders that don't support clearing+ return+class BasePersistenceLoader(Loader):"""Abstract base for cache written to disk."""@@ -216,6 +237,23 @@ class BasePersistenceLoader(Loader):except FileNotFoundError as e:raise LoaderError("Unexpected cache miss.") from e+ def clear(self) -> None:+ """Clear all cached items for this loader."""+ # Clear all files in the loader's directory+ import glob++ from marimo._save.stores.file import FileStore++ # Only FileStore has save_path, so we need to check+ if not isinstance(self.store, FileStore):+ return++ pattern = str(Path(self.name) / f"*.{self.suffix}")+ # Get all matching cache files through the store's base path+ for cache_file in glob.glob(str(self.store.save_path / pattern)):+ key = str(Path(cache_file).relative_to(self.store.save_path))+ self.store.clear(key)+@abstractmethoddef restore_cache(self, key: HashKey, blob: bytes) -> Cache:"""May throw FileNotFoundError"""diff --git a/marimo/_save/loaders/memory.py b/marimo/_save/loaders/memory.pyindex 68ef7e95fa..e63bc8a001 100644--- a/marimo/_save/loaders/memory.py+++ b/marimo/_save/loaders/memory.py@@ -107,3 +107,11 @@ class MemoryLoader(Loader):@max_size.setterdef max_size(self, value: int) -> None:self.resize(value)++ @property+ def current_size(self) -> int:+ return len(self._cache)++ def clear(self) -> None:+ """Clear all cached items."""+ self._maybe_lock(lambda: self._cache.clear())diff --git a/marimo/_save/save.py b/marimo/_save/save.pyindex 5952d0d1c1..b09af7e84c 100644--- a/marimo/_save/save.py+++ b/marimo/_save/save.py@@ -6,6 +6,7 @@ import functoolsimport inspectimport ioimport sys+import timeimport tracebackfrom collections import abc@@ -33,7 +34,12 @@ from marimo._messaging.tracebacks import write_tracebackfrom marimo._runtime.context import get_context, safe_get_contextfrom marimo._runtime.side_effect import SideEffectfrom marimo._runtime.state import State-from marimo._save.cache import Cache, CacheException+from marimo._save.cache import (+ UNEXPECTED_FAILURE_BOILERPLATE,+ Cache,+ CacheContext,+ CacheException,+)from marimo._save.hash import (DEFAULT_HASH,BlockHasher,@@ -53,15 +59,6 @@ from marimo._save.toplevel import get_cell_id_from_scope, graph_from_scopefrom marimo._types.ids import CellId_tfrom marimo._utils.with_skip import SkipContext-# Many assertions are for typing and should always pass. This message is a-# catch all to motive users to report if something does fail.-UNEXPECTED_FAILURE_BOILERPLATE = (- "— this is"- " unexpected and is likely a bug in marimo. "- "Please file an issue at "- "https://github.com/marimo-team/marimo/issues"-)-if TYPE_CHECKING:from types import FrameType, TracebackType@@ -69,7 +66,7 @@ if TYPE_CHECKING:from marimo._save.stores import Store-class _cache_call:+class _cache_call(CacheContext):"""Like functools.cache but notebook-aware. See `cache` docstring"""__slots__ = (@@ -81,6 +78,7 @@ class _cache_call:"_args","_var_arg","_var_kwarg",+ "_misses","_loader","_loader_partial","_bound",@@ -98,6 +96,7 @@ class _cache_call:_args: list[str]_var_arg: Optional[str]_var_kwarg: Optional[str]+ _misses: int_loader: Optional[State[Loader]]_loader_partial: LoaderPartial_bound: Optional[dict[str, Any]]@@ -126,6 +125,7 @@ class _cache_call:self._last_hash = Noneself._var_arg = Noneself._var_kwarg = None+ self._misses = 0self._loader = Noneself._bound = {}self._external = False@@ -134,12 +134,6 @@ class _cache_call:else:self._set_context(_fn)- @property- def hits(self) -> int:- if self._loader is None:- return 0- return self.loader.hits-def _set_context(self, fn: Callable[..., Any]) -> None:ctx = safe_get_context()@@ -256,9 +250,10 @@ class _cache_call:)@property- def loader(self) -> Loader:- assert self._loader is not None, UNEXPECTED_FAILURE_BOILERPLATE- return self._loader()+ def misses(self) -> int:+ if self._loader is None:+ return 0+ return self._misses@propertydef __name__(self) -> str:@@ -384,12 +379,18 @@ class _cache_call:if attempt.hit:attempt.restore(scope)return attempt.meta["return"]++ start_time = time.time()response = self.__wrapped__(*args, **kwargs)+ runtime = time.time() - start_time+# stateful variables may be globalscope = {k: v for k, v in scope.items() if k in attempt.stateful_refs}- attempt.update(scope, meta={"return": response})+ attempt.update(+ scope, meta={"return": response, "runtime": runtime}+ )self.loader.save_cache(attempt)except Exception as e:failed = True@@ -398,10 +399,11 @@ class _cache_call:# NB. Exceptions raise their own side effects.if ctx and not failed:ctx.cell_lifecycle_registry.add(SideEffect(attempt.hash))+ self._misses += 1return response-class _cache_context(SkipContext):+class _cache_context(SkipContext, CacheContext):def __init__(self,name: str,@@ -418,7 +420,9 @@ class _cache_context(SkipContext):# TODO: Consider having a user level setting.self.pin_modules = pin_modulesself.hash_type = hash_type- self._loader = loader+ # Wrap loader in State to match CacheContext's _loader type+ self._loader = State(loader, _name=name)+ self._start_time: float = 0.0@propertydef hit(self) -> bool:@@ -472,7 +476,7 @@ class _cache_context(SkipContext):graph,cell_id,{**globals(), **with_frame.f_locals},- loader=self._loader,+ loader=self.loader,context=pre_module,pin_modules=self.pin_modules,hash_type=self.hash_type,@@ -483,6 +487,9 @@ class _cache_context(SkipContext):# whitespace in `With`, changes behavior.self._body_start = save_module.body[0].lineno+ # Start timing for runtime tracking+ self._start_time = time.time()+if self._cache and self._cache.hit:if lineno >= self._body_start:self.skip()@@ -532,10 +539,11 @@ class _cache_context(SkipContext):return True# Fill the cache object and save.- self._cache.update(self._frame.f_locals)+ runtime = time.time() - self._start_time+ self._cache.update(self._frame.f_locals, meta={"runtime": runtime})try:- self._loader.save_cache(self._cache)+ self.loader.save_cache(self._cache)except Exception as e:sys.stderr.write("An exception was raised when attempting to cache this code "@@ -661,11 +669,10 @@ def _invoke_context("hash_type": kwargs.pop("hash_type", DEFAULT_HASH),}# Create through partial for meaningful error message.- loader = (- cast(Loader, loader)- .partial(**kwargs)- .create_or_reconfigure(name)()+ loader_state = (+ cast(Loader, loader).partial(**kwargs).create_or_reconfigure(name))+ loader = loader_state()kwargs = cache_argsreturn _cache_context(name, loader, *args, **kwargs)diff --git a/marimo/_save/stores/file.py b/marimo/_save/stores/file.pyindex 6983e6a47e..0f8a4615db 100644--- a/marimo/_save/stores/file.py+++ b/marimo/_save/stores/file.py@@ -47,3 +47,11 @@ class FileStore(Store):def hit(self, key: str) -> bool:path = self.save_path / keyreturn _valid_path(path)++ def clear(self, key: str) -> bool:+ path = self.save_path / key+ path.parent.mkdir(parents=True, exist_ok=True)+ if not _valid_path(path):+ return False+ path.unlink()+ return Truediff --git a/marimo/_save/stores/store.py b/marimo/_save/stores/store.pyindex b95e3b2e2e..d835fc406c 100644--- a/marimo/_save/stores/store.py+++ b/marimo/_save/stores/store.py@@ -18,5 +18,10 @@ class Store(ABC):def hit(self, key: str) -> bool:"""Check if the cache is in the store"""+ def clear(self, key: str) -> bool:+ """Check if the cache is in the store"""+ del key+ return False+StoreType = type[Store]diff --git a/tests/_save/stores/test_file.py b/tests/_save/stores/test_file.pyindex f4312a6eb3..18d3baa6cb 100644--- a/tests/_save/stores/test_file.py+++ b/tests/_save/stores/test_file.py@@ -22,3 +22,23 @@ class TestFileStore:# Store is actually createdassert (tmp_path / "test_store").exists()assert (tmp_path / "test_store" / "key").exists()++ def test_clear(self, tmp_path) -> None:+ """Test clear functionality of FileStore."""+ store = FileStore(tmp_path / "test_store")+ data = b"test data"++ # Put some data+ store.put("key1", data)+ assert store.hit("key1")+ assert store.get("key1") == data++ # Clear the key+ result = store.clear("key1")+ assert result is True+ assert not store.hit("key1")+ assert store.get("key1") is None++ # Clear non-existent key+ result = store.clear("nonexistent")+ assert result is Falsediff --git a/tests/_save/test_cache.py b/tests/_save/test_cache.pyindex 542691a093..dc48299fde 100644--- a/tests/_save/test_cache.py+++ b/tests/_save/test_cache.py@@ -280,8 +280,8 @@ class TestScriptCache:X = 7assert X == 7assert cache._cache.defs == {"X": 7, "Y": 8}- assert cache._loader._saved- assert not cache._loader._loaded+ assert cache.loader._saved+ assert not cache.loader._loadedreturn X, Y, persistent_cache# Coverage's trace override conflicts with cache introspection. Letting@@ -310,8 +310,8 @@ class TestScriptCache:X = 10assert X == 7assert cache._cache.defs == {"X": 7, "Y": 8}- assert not cache._loader._saved- assert cache._loader._loaded+ assert not cache.loader._saved+ assert cache.loader._loadedreturn X, Y, persistent_cache@staticmethod@@ -325,8 +325,8 @@ class TestScriptCache:X = 10assert X == 7assert cache._cache.defs == {"X": 7, "Y": 8}- assert not cache._loader._saved- assert cache._loader._loaded+ assert not cache.loader._saved+ assert cache.loader._loadedreturn X, Y@staticmethod@@ -346,8 +346,8 @@ class TestScriptCache:# fmt: onassert X == 7assert cache._cache.defs == {"X": 7, "Y": 8}- assert not cache._loader._saved- assert cache._loader._loaded+ assert not cache.loader._saved+ assert cache.loader._loadedreturn X, Y, persistent_cache@staticmethod@@ -2572,3 +2572,167 @@ class TestPersistentCache:)assert not k.stdout.messages, k.stdoutassert not k.stderr.messages, k.stderr+++class TestCacheStatistics:+ """Tests for cache statistics API (cache_info(), cache_clear())"""++ async def test_cache_info_and_clear(+ self, k: Kernel, exec_req: ExecReqProvider+ ) -> None:+ """Verify cache_info() and cache_clear() work correctly."""+ await k.run(+ [+ exec_req.get(+ """+ from marimo._save.save import cache, lru_cache++ @cache+ def func(x):+ return x * 2++ @lru_cache(maxsize=2)+ def lru_func(x):+ return x * 3++ # Test basic cache_info+ info0 = func.cache_info()+ func(1)+ func(1) # hit+ func(2) # miss+ info1 = func.cache_info()++ # Test lru_cache maxsize+ lru_info = lru_func.cache_info()++ # Test cache_clear+ func.cache_clear()+ info2 = func.cache_info()+ """+ ),+ ]+ )++ assert not k.stderr.messages, k.stderr++ # Initial state+ info0 = k.globals["info0"]+ assert info0.hits == 0+ assert info0.misses == 0+ assert info0.maxsize is None+ assert info0.currsize == 0+ assert info0.time_saved == 0.0++ # After calls+ info1 = k.globals["info1"]+ assert info1.hits == 1+ assert info1.misses == 2+ assert info1.currsize == 2++ # LRU maxsize+ lru_info = k.globals["lru_info"]+ assert lru_info.maxsize == 2++ # After clear+ info2 = k.globals["info2"]+ assert info2.currsize == 0++ async def test_persistent_cache_clear(+ self, k: Kernel, exec_req: ExecReqProvider+ ) -> None:+ """Verify cache_clear() works with persistent cache decorator."""+ await k.run(+ [+ exec_req.get("""+ from marimo._save.loaders.memory import MemoryLoader+ from marimo._save.save import persistent_cache++ @persistent_cache(_loader=MemoryLoader)+ def calc(x):+ return x * 2++ # First call - miss+ r1 = calc(5)+ info1 = calc.cache_info()++ # Second call - hit+ r2 = calc(5)+ info2 = calc.cache_info()++ # Clear+ calc.cache_clear()+ info3 = calc.cache_info()++ # Call again - should be miss+ r3 = calc(5)+ info4 = calc.cache_info()+ """),+ ]+ )++ assert not k.stderr.messages, k.stderr++ # Should have 1 hit before clear+ info2 = k.globals["info2"]+ assert info2.hits == 1++ # After clear: should be empty+ info3 = k.globals["info3"]+ assert info3.currsize == 0++ # After calling again: should be a miss+ info4 = k.globals["info4"]+ assert info4.misses >= 1++ async def test_cache_time_tracking(+ self, k: Kernel, exec_req: ExecReqProvider+ ) -> None:+ """Verify time_saved is tracked and included in cache_info()."""+ await k.run(+ [+ exec_req.get("""+ import time+ from marimo._save.save import cache++ @cache+ def slow_func(x):+ time.sleep(0.01) # Simulate slow operation+ return x * 2++ # Initial state+ info0 = slow_func.cache_info()++ # First call - miss (should record runtime)+ r1 = slow_func(5)+ info1 = slow_func.cache_info()++ # Second call - hit (should add to time_saved)+ r2 = slow_func(5)+ info2 = slow_func.cache_info()++ # Third call - another hit (should accumulate time_saved)+ r3 = slow_func(5)+ info3 = slow_func.cache_info()+ """),+ ]+ )++ assert not k.stderr.messages, k.stderr++ # Initial state: no time saved yet+ info0 = k.globals["info0"]+ assert info0.time_saved == 0.0++ # After first call (miss): still no time saved+ info1 = k.globals["info1"]+ assert info1.time_saved == 0.0++ # After first hit: should have some time saved+ info2 = k.globals["info2"]+ assert info2.time_saved > 0.0+ first_saving = info2.time_saved++ # After second hit: time_saved should accumulate+ info3 = k.globals["info3"]+ assert info3.time_saved > first_saving+ assert info3.hits == 2