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.

fix: _repr_mimebundle_ for img and tuple outputs (#6165)

Myles Scolnick9f5b27d05f0d
diff --git a/docs/guides/integrating_with_marimo/displaying_objects.md b/docs/guides/integrating_with_marimo/displaying_objects.md
index 86e74fd95f..450a8800c3 100644
--- a/docs/guides/integrating_with_marimo/displaying_objects.md
+++ b/docs/guides/integrating_with_marimo/displaying_objects.md
@@ -76,6 +76,8 @@ We support the following methods:
- `_repr_latex_`
- `_repr_text_`
+**Note:** marimo currently does not handle any optional metadata returned by `_repr_mimebundle_`.
+
## Option 3: Implement a `_mime_` method
When displaying an object, marimo's media viewer checks for the presence of a
diff --git a/marimo/_output/formatters/repr_formatters.py b/marimo/_output/formatters/repr_formatters.py
index 03c24dfb68..b6ab393143 100644
--- a/marimo/_output/formatters/repr_formatters.py
+++ b/marimo/_output/formatters/repr_formatters.py
@@ -1,13 +1,20 @@
# Copyright 2024 Marimo. All rights reserved.
from __future__ import annotations
-from typing import Any, Callable, Optional
+from typing import Any, Callable, Optional, cast
from marimo._messaging.mimetypes import KnownMimeType
from marimo._output.formatters.iframe import maybe_wrap_in_iframe
from marimo._plugins.core.media import io_to_data_url
from marimo._utils.methods import is_callable_method
+MEDIA_MIME_PREFIXES = (
+ "image/",
+ "audio/",
+ "video/",
+ "application/pdf",
+)
+
def maybe_get_repr_formatter(
obj: Any,
@@ -44,6 +51,7 @@ def maybe_get_repr_formatter(
continue
method = getattr(obj, attr)
+ contents: Any
# Try to call _repr_mimebundle_ with include/exclude parameters
if attr == "_repr_mimebundle_":
try:
@@ -51,6 +59,27 @@ def maybe_get_repr_formatter(
except TypeError:
# If that fails, call the method without parameters
contents = method()
+
+ # Handle tuple return format: (data, metadata)
+ # According to Jupyter spec, _repr_mimebundle_ can return either:
+ # 1. A dict (just the data)
+ # 2. A tuple of (data_dict, metadata_dict)
+ if isinstance(contents, tuple) and len(contents) == 2:
+ contents, _metadata = cast(
+ tuple[dict[str, Any], dict[str, Any]], contents
+ )
+
+ # Convert binary or audio/video data to data URLs for web display
+ if isinstance(contents, dict):
+ for mime_key, data in list(contents.items()):
+ # image/*, audio/*, video/*, and application/pdf are common binary types
+ if mime_key.startswith(
+ MEDIA_MIME_PREFIXES
+ ) and isinstance(data, bytes):
+ data_url = io_to_data_url(data, mime_key)
+ if data_url:
+ contents[mime_key] = data_url
+
# Remove text/plain from the mimebundle if it's present
# since there are other representations available
# N.B. We cannot pass this as an argument to the method
diff --git a/marimo/_smoke_tests/ipython/img_mimebundle.py b/marimo/_smoke_tests/ipython/img_mimebundle.py
new file mode 100644
index 0000000000..1df78eed22
--- /dev/null
+++ b/marimo/_smoke_tests/ipython/img_mimebundle.py
@@ -0,0 +1,38 @@
+import marimo
+
+__generated_with = "0.15.0"
+app = marimo.App(width="medium")
+
+
+def _():
+ from io import BytesIO
+ from PIL import Image, ImageDraw
+
+
+ class BlueOnGray:
+ def __init__(self, text, retina=False):
+ self.text = text
+ self.retina = retina
+
+ def _repr_mimebundle_(self, include=None, exclude=None):
+ w, h = 200, 80
+ f = 2 if self.retina else 1
+ img = Image.new("RGB", (w, h), color="lightgray")
+ metadata = {"image/png": {"width": w // f, "height": h // f}}
+ draw = ImageDraw.Draw(img)
+ draw.text((10, 30), self.text, fill="blue")
+ buffer = BytesIO()
+ img.save(buffer, format="PNG")
+ return {
+ "image/png": buffer.getvalue(),
+ "text/html": f"<span style='color: blue; background-color: gray'>{self.text}</span>",
+ }, metadata
+
+
+ BlueOnGray("Blue text on gray background")
+ return
+
+
+if __name__ == "__main__":
+ app.run()
diff --git a/tests/_output/formatters/test_formatters.py b/tests/_output/formatters/test_formatters.py
index 1e00a77820..0248bd4055 100644
--- a/tests/_output/formatters/test_formatters.py
+++ b/tests/_output/formatters/test_formatters.py
@@ -468,6 +468,54 @@ def test_repr_mimebundle_with_latex():
}
+def test_repr_mimebundle_with_tuple_return():
+ """Test _repr_mimebundle_ that returns (data, metadata) tuple."""
+
+ class ReprMimeBundleTuple:
+ def _repr_mimebundle_(self):
+ data = {
+ "text/html": "<h1>Hello, World!</h1>",
+ "text/plain": "Hello, World!",
+ }
+ metadata = {"text/html": {"width": 100, "height": 50}}
+ return data, metadata
+
+ obj = ReprMimeBundleTuple()
+ formatter = get_formatter(obj)
+ assert formatter is not None
+ mime, content = formatter(obj)
+ assert mime == "application/vnd.marimo+mimebundle"
+ # Should contain the HTML (text/plain should be removed since other repr exists)
+ assert content == {"text/html": "<h1>Hello, World!</h1>"}
+
+
+def test_repr_mimebundle_with_tuple_return_image():
+ """Test _repr_mimebundle_ with tuple return containing binary image data."""
+
+ class ReprMimeBundleWithImage:
+ def _repr_mimebundle_(self):
+ # Simulate binary PNG data (minimal valid PNG header)
+ fake_png_data = b"\x89PNG\r\n\x1a\nfake_png_data"
+ data = {
+ "image/png": fake_png_data,
+ "text/html": "<span>Image representation</span>",
+ }
+ metadata = {"image/png": {"width": 200, "height": 80}}
+ return data, metadata
+
+ obj = ReprMimeBundleWithImage()
+ formatter = get_formatter(obj)
+ assert formatter is not None
+ mime, content = formatter(obj)
+ assert mime == "application/vnd.marimo+mimebundle"
+ # Should contain both image and HTML
+ assert "image/png" in content
+ assert "text/html" in content
+ # Image data should be converted to data URL
+ assert content["image/png"].startswith("data:image/png;base64,")
+ assert content["text/html"] == "<span>Image representation</span>"
+
+
def test_display_protocol_takes_precedence() -> None:
register_formatters()