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: expand cache api to match functools api (#6660)

Dylan Madisetti52663748b66d
diff --git a/marimo/_save/cache.py b/marimo/_save/cache.py
index 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, UIElement
from marimo._runtime.context import ContextNotInitializedError, get_context
from 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 State
from 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_saved
diff --git a/marimo/_save/loaders/loader.py b/marimo/_save/loaders/loader.py
index f91fd6a839..89aba1ba84 100644
--- a/marimo/_save/loaders/loader.py
+++ b/marimo/_save/loaders/loader.py
@@ -2,6 +2,7 @@
from __future__ import annotations
import re
+import time
from abc import ABC, abstractmethod
from pathlib import Path
from typing import TYPE_CHECKING, Any, Optional
@@ -109,6 +110,7 @@ class Loader(ABC):
def __init__(self, name: str) -> None:
self.name = name
self._hits = 0
+ self._time_saved = 0.0
def 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 verification
if 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
+
@classmethod
def 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)
+
@abstractmethod
def restore_cache(self, key: HashKey, blob: bytes) -> Cache:
"""May throw FileNotFoundError"""
diff --git a/marimo/_save/loaders/memory.py b/marimo/_save/loaders/memory.py
index 68ef7e95fa..e63bc8a001 100644
--- a/marimo/_save/loaders/memory.py
+++ b/marimo/_save/loaders/memory.py
@@ -107,3 +107,11 @@ class MemoryLoader(Loader):
@max_size.setter
def 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.py
index 5952d0d1c1..b09af7e84c 100644
--- a/marimo/_save/save.py
+++ b/marimo/_save/save.py
@@ -6,6 +6,7 @@ import functools
import inspect
import io
import sys
+import time
import traceback
from collections import abc
@@ -33,7 +34,12 @@ from marimo._messaging.tracebacks import write_traceback
from marimo._runtime.context import get_context, safe_get_context
from marimo._runtime.side_effect import SideEffect
from 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_scope
from marimo._types.ids import CellId_t
from 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 = None
self._var_arg = None
self._var_kwarg = None
+ self._misses = 0
self._loader = None
self._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
@property
def __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 global
scope = {
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 += 1
return 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_modules
self.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
@property
def 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_args
return _cache_context(name, loader, *args, **kwargs)
diff --git a/marimo/_save/stores/file.py b/marimo/_save/stores/file.py
index 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 / key
return _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 True
diff --git a/marimo/_save/stores/store.py b/marimo/_save/stores/store.py
index 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.py
index 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 created
assert (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 False
diff --git a/tests/_save/test_cache.py b/tests/_save/test_cache.py
index 542691a093..dc48299fde 100644
--- a/tests/_save/test_cache.py
+++ b/tests/_save/test_cache.py
@@ -280,8 +280,8 @@ class TestScriptCache:
X = 7
assert X == 7
assert cache._cache.defs == {"X": 7, "Y": 8}
- assert cache._loader._saved
- assert not cache._loader._loaded
+ assert cache.loader._saved
+ assert not cache.loader._loaded
return X, Y, persistent_cache
# Coverage's trace override conflicts with cache introspection. Letting
@@ -310,8 +310,8 @@ class TestScriptCache:
X = 10
assert X == 7
assert cache._cache.defs == {"X": 7, "Y": 8}
- assert not cache._loader._saved
- assert cache._loader._loaded
+ assert not cache.loader._saved
+ assert cache.loader._loaded
return X, Y, persistent_cache
@staticmethod
@@ -325,8 +325,8 @@ class TestScriptCache:
X = 10
assert X == 7
assert cache._cache.defs == {"X": 7, "Y": 8}
- assert not cache._loader._saved
- assert cache._loader._loaded
+ assert not cache.loader._saved
+ assert cache.loader._loaded
return X, Y
@staticmethod
@@ -346,8 +346,8 @@ class TestScriptCache:
# fmt: on
assert X == 7
assert cache._cache.defs == {"X": 7, "Y": 8}
- assert not cache._loader._saved
- assert cache._loader._loaded
+ assert not cache.loader._saved
+ assert cache.loader._loaded
return X, Y, persistent_cache
@staticmethod
@@ -2572,3 +2572,167 @@ class TestPersistentCache:
)
assert not k.stdout.messages, k.stdout
assert 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