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
# Copyright 2026 Marimo. All rights reserved.
from __future__ import annotations
import threading
from unittest.mock import AsyncMock, MagicMock
import pytest
from dirty_equals import IsPositiveFloat, IsStr
from marimo._data._external_storage.models import (
StorageEntry,
StorageListResult,
)
from marimo._data._external_storage.storage import Obstore
from marimo._dependencies.dependencies import DependencyManager
from marimo._messaging.notification import (
StorageDownloadReadyNotification,
StorageEntriesNotification,
)
from marimo._runtime.commands import (
ExecuteCellCommand,
StorageDownloadCommand,
StorageListEntriesCommand,
)
from marimo._types.ids import CellId_t, RequestId, VariableName
from tests.conftest import MockedKernel
HAS_OBSTORE = DependencyManager.obstore.has()
STORAGE_VAR = "my_store"
class TestExternalStorageErrors:
"""Error-handling tests that don't require a real storage backend."""
async def test_list_entries_variable_not_found(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
request = StorageListEntriesCommand(
request_id=RequestId("req-1"),
namespace="nonexistent_var",
limit=100,
prefix=None,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-1"),
entries=[],
namespace="nonexistent_var",
prefix=None,
error="Variable 'nonexistent_var' not found",
)
]
async def test_list_entries_incompatible_backend(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code='not_storage = "just a string"',
),
]
)
request = StorageListEntriesCommand(
request_id=RequestId("req-2"),
namespace="not_storage",
limit=100,
prefix=None,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-2"),
entries=[],
namespace="not_storage",
prefix=None,
error=(
"Variable 'not_storage' is not a compatible "
"storage backend (expected obstore, huggingface_hub.HfApi, or fsspec)"
),
)
]
async def test_download_variable_not_found(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
request = StorageDownloadCommand(
request_id=RequestId("req-3"),
namespace="nonexistent_var",
path="data/file.csv",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-3"),
url=None,
filename=None,
error="Variable 'nonexistent_var' not found",
)
]
async def test_download_incompatible_backend(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code="not_storage = 42",
),
]
)
request = StorageDownloadCommand(
request_id=RequestId("req-4"),
namespace="not_storage",
path="data/file.csv",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-4"),
url=None,
filename=None,
error=(
"Variable 'not_storage' is not a compatible "
"storage backend (expected obstore, huggingface_hub.HfApi, or fsspec)"
),
)
]
@pytest.mark.skipif(not HAS_OBSTORE, reason="obstore not installed")
class TestExternalStorageCallbacks:
"""Integration tests using a real obstore MemoryStore."""
async def test_list_entries(self, mocked_kernel: MockedKernel) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("data/file1.csv", b"a,b,c")
await store.put_async("data/file2.txt", b"hello")
request = StorageListEntriesCommand(
request_id=RequestId("req-10"),
namespace=STORAGE_VAR,
limit=100,
prefix="data/",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-10"),
entries=[
StorageEntry(
path="data/file1.csv",
kind="object",
size=5,
last_modified=IsPositiveFloat(), # pyright: ignore[reportArgumentType]
metadata={"e_tag": IsStr()},
mime_type="text/csv",
),
StorageEntry(
path="data/file2.txt",
kind="object",
size=5,
last_modified=IsPositiveFloat(), # pyright: ignore[reportArgumentType]
metadata={"e_tag": IsStr()},
mime_type="text/plain",
),
],
namespace=STORAGE_VAR,
prefix="data/",
)
]
async def test_list_entries_with_limit(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("a.txt", b"1")
await store.put_async("b.txt", b"2")
await store.put_async("c.txt", b"3")
request = StorageListEntriesCommand(
request_id=RequestId("req-11"),
namespace=STORAGE_VAR,
limit=2,
prefix=None,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-11"),
entries=[
StorageEntry(
path="a.txt",
kind="object",
size=1,
last_modified=IsPositiveFloat(), # pyright: ignore[reportArgumentType]
metadata={"e_tag": IsStr()},
mime_type="text/plain",
),
StorageEntry(
path="b.txt",
kind="object",
size=1,
last_modified=IsPositiveFloat(), # pyright: ignore[reportArgumentType]
metadata={"e_tag": IsStr()},
mime_type="text/plain",
),
],
namespace=STORAGE_VAR,
prefix=None,
next_page_token="2",
)
]
request = StorageListEntriesCommand(
request_id=RequestId("req-11-page-2"),
namespace=STORAGE_VAR,
limit=2,
prefix=None,
page_token="2",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
and op.request_id == RequestId("req-11-page-2")
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-11-page-2"),
entries=[
StorageEntry(
path="c.txt",
kind="object",
size=1,
last_modified=IsPositiveFloat(), # pyright: ignore[reportArgumentType]
metadata={"e_tag": IsStr()},
mime_type="text/plain",
),
],
namespace=STORAGE_VAR,
prefix=None,
)
]
async def test_list_entries_empty(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
request = StorageListEntriesCommand(
request_id=RequestId("req-12"),
namespace=STORAGE_VAR,
limit=100,
prefix=None,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-12"),
entries=[],
namespace=STORAGE_VAR,
prefix=None,
)
]
async def test_list_entries_backend_exception(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
# Use a real Obstore backend with a broken list_entries
store = k.globals[VariableName(STORAGE_VAR)]
broken_backend = Obstore(store, VariableName(STORAGE_VAR))
broken_backend.list_entries = MagicMock( # type: ignore[method-assign]
side_effect=RuntimeError("connection timeout"),
)
with pytest.MonkeyPatch.context() as mp:
mp.setattr(
k.external_storage_callbacks,
"_get_storage_backend",
lambda _: (broken_backend, None),
)
request = StorageListEntriesCommand(
request_id=RequestId("req-13"),
namespace=STORAGE_VAR,
limit=100,
prefix=None,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-13"),
entries=[],
namespace=STORAGE_VAR,
prefix=None,
error="Failed to list entries: connection timeout",
)
]
async def test_list_entries_runs_in_background_thread(
self, mocked_kernel: MockedKernel
) -> None:
"""list_entries dispatches to a thread via asyncio.to_thread."""
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
real_backend = Obstore(store, VariableName(STORAGE_VAR))
call_thread_name: str | None = None
original_list = real_backend.list_entries
def spy_list_entries(
prefix: str | None,
*,
limit: int = 100,
page_token: str | None = None,
) -> StorageListResult:
nonlocal call_thread_name
call_thread_name = threading.current_thread().name
return original_list(prefix, limit=limit, page_token=page_token)
real_backend.list_entries = spy_list_entries # type: ignore[method-assign]
with pytest.MonkeyPatch.context() as mp:
mp.setattr(
k.external_storage_callbacks,
"_get_storage_backend",
lambda _: (real_backend, None),
)
request = StorageListEntriesCommand(
request_id=RequestId("req-14"),
namespace=STORAGE_VAR,
limit=100,
prefix=None,
)
await k.handle_message(request)
# asyncio.to_thread runs the callable in a worker thread,
# not the main thread
assert call_thread_name is not None
assert call_thread_name != threading.main_thread().name
results = [
op
for op in stream.operations
if isinstance(op, StorageEntriesNotification)
]
assert results == [
StorageEntriesNotification(
request_id=RequestId("req-14"),
entries=[],
namespace=STORAGE_VAR,
prefix=None,
)
]
async def test_download(self, mocked_kernel: MockedKernel) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("reports/data.csv", b"a,b,c\n1,2,3")
request = StorageDownloadCommand(
request_id=RequestId("req-20"),
namespace=STORAGE_VAR,
path="reports/data.csv",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-20"),
url=IsStr(), # pyright: ignore[reportArgumentType]
filename="data.csv",
)
]
async def test_download_uses_signed_url_when_available(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
backend = Obstore(store, VariableName(STORAGE_VAR))
backend.sign_download_url = AsyncMock( # type: ignore[method-assign]
return_value="https://signed.example.com/data.csv?token=abc",
)
# download_file should NOT be called when signing succeeds
backend.download_file = AsyncMock( # type: ignore[method-assign]
side_effect=AssertionError("should not be called"),
)
with pytest.MonkeyPatch.context() as mp:
mp.setattr(
k.external_storage_callbacks,
"_get_storage_backend",
lambda _: (backend, None),
)
request = StorageDownloadCommand(
request_id=RequestId("req-22"),
namespace=STORAGE_VAR,
path="reports/data.csv",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-22"),
url="https://signed.example.com/data.csv?token=abc",
filename="data.csv",
)
]
async def test_download_falls_back_when_signing_returns_none(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("local/readme.txt", b"hello world")
# MemoryStore can't sign, so sign_download_url returns None
# and the handler falls back to virtual file
request = StorageDownloadCommand(
request_id=RequestId("req-23"),
namespace=STORAGE_VAR,
path="local/readme.txt",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-23"),
url=IsStr(), # pyright: ignore[reportArgumentType]
filename="readme.txt",
)
]
async def test_download_fallback_schedules_cleanup(
self, mocked_kernel: MockedKernel
) -> None:
import asyncio
k = mocked_kernel.k
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("tmp/file.bin", b"data")
request = StorageDownloadCommand(
request_id=RequestId("req-24"),
namespace=STORAGE_VAR,
path="tmp/file.bin",
)
loop = asyncio.get_running_loop()
scheduled: list[tuple[float, object]] = []
original_call_later = loop.call_later
def spy_call_later(
delay: float, callback: object, *args: object
) -> asyncio.TimerHandle:
scheduled.append((delay, callback))
return original_call_later(delay, callback, *args)
with pytest.MonkeyPatch.context() as mp:
mp.setattr(loop, "call_later", spy_call_later)
await k.handle_message(request)
assert len(scheduled) == 1
delay, _callback = scheduled[0]
assert delay == 60
async def test_download_backend_exception(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
broken_backend = Obstore(store, VariableName(STORAGE_VAR))
broken_backend.download_file = AsyncMock( # type: ignore[method-assign]
side_effect=PermissionError("access denied"),
)
with pytest.MonkeyPatch.context() as mp:
mp.setattr(
k.external_storage_callbacks,
"_get_storage_backend",
lambda _: (broken_backend, None),
)
request = StorageDownloadCommand(
request_id=RequestId("req-21"),
namespace=STORAGE_VAR,
path="secret/file.bin",
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-21"),
url=None,
filename=None,
error="Failed to download: access denied",
)
]
async def test_download_preview(self, mocked_kernel: MockedKernel) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("docs/readme.txt", b"hello world")
request = StorageDownloadCommand(
request_id=RequestId("req-30"),
namespace=STORAGE_VAR,
path="docs/readme.txt",
preview=True,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-30"),
url=IsStr(), # pyright: ignore[reportArgumentType]
filename="readme.txt",
error=None,
)
]
notif = results[0]
assert notif.url is not None
# Preview returns a virtual file URL, not a signed URL
assert "@file/" in notif.url
async def test_download_preview_skips_signed_url(
self, mocked_kernel: MockedKernel
) -> None:
"""Preview mode should use read_range, never sign_download_url."""
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("file.py", b"print('hello')")
backend = Obstore(store, VariableName(STORAGE_VAR))
backend.sign_download_url = AsyncMock( # type: ignore[method-assign]
side_effect=AssertionError("should not be called"),
)
with pytest.MonkeyPatch.context() as mp:
mp.setattr(
k.external_storage_callbacks,
"_get_storage_backend",
lambda _: (backend, None),
)
request = StorageDownloadCommand(
request_id=RequestId("req-31"),
namespace=STORAGE_VAR,
path="file.py",
preview=True,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-31"),
url=IsStr(), # pyright: ignore[reportArgumentType]
filename="file.py",
error=None,
)
]
async def test_download_preview_schedules_cleanup(
self, mocked_kernel: MockedKernel
) -> None:
import asyncio
k = mocked_kernel.k
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
await store.put_async("tmp/preview.txt", b"data")
request = StorageDownloadCommand(
request_id=RequestId("req-32"),
namespace=STORAGE_VAR,
path="tmp/preview.txt",
preview=True,
)
loop = asyncio.get_running_loop()
scheduled: list[tuple[float, object]] = []
original_call_later = loop.call_later
def spy_call_later(
delay: float, callback: object, *args: object
) -> asyncio.TimerHandle:
scheduled.append((delay, callback))
return original_call_later(delay, callback, *args) # pyright: ignore[reportArgumentType]
with pytest.MonkeyPatch.context() as mp:
mp.setattr(loop, "call_later", spy_call_later)
await k.handle_message(request)
assert len(scheduled) == 1
delay, _callback = scheduled[0]
assert delay == 60
async def test_download_preview_backend_exception(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
await k.run(
[
ExecuteCellCommand(
cell_id=CellId_t("0"),
code=(
"from obstore.store import MemoryStore\n"
f"{STORAGE_VAR} = MemoryStore()"
),
),
]
)
store = k.globals[VariableName(STORAGE_VAR)]
broken_backend = Obstore(store, VariableName(STORAGE_VAR))
broken_backend.read_range = AsyncMock( # type: ignore[method-assign]
side_effect=OSError("read failed"),
)
with pytest.MonkeyPatch.context() as mp:
mp.setattr(
k.external_storage_callbacks,
"_get_storage_backend",
lambda _: (broken_backend, None),
)
request = StorageDownloadCommand(
request_id=RequestId("req-33"),
namespace=STORAGE_VAR,
path="broken/file.txt",
preview=True,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-33"),
url=None,
filename=None,
error="Failed to download: read failed",
)
]
async def test_download_preview_variable_not_found(
self, mocked_kernel: MockedKernel
) -> None:
k = mocked_kernel.k
stream = mocked_kernel.stream
request = StorageDownloadCommand(
request_id=RequestId("req-34"),
namespace="nonexistent_var",
path="file.txt",
preview=True,
)
await k.handle_message(request)
results = [
op
for op in stream.operations
if isinstance(op, StorageDownloadReadyNotification)
]
assert results == [
StorageDownloadReadyNotification(
request_id=RequestId("req-34"),
url=None,
filename=None,
error="Variable 'nonexistent_var' not found",
)
]