Prefer _repr_mimebundle_ for notebook display

These changes replace `_ipython_display_` with `_repr_mimebundle_`
protocol displaying plots within notebooks. Previously, plotnine used
`_ipython_display_()` for display, which works via side effects and
assumes an IPython/Jupyter environment.

Since IPython 6.1 (May 2017), the `_repr_mimebundle_()` protocol allows
objects to return display data instead of triggering side effects. This
decouples rendering from IPython, letting any compatible frontend (e.g.,
Jupyter, marimo) handle presentation without requiring the object to be
aware of the runtime.

The repr continues to generate a single format (PNG, SVG, etc.) based on
configuration to match prior behavior with the `_ipython_display_`.

References:
- https://ipython.readthedocs.io/en/stable/config/integrating.html
- https://ipython.readthedocs.io/en/stable/api/generated/IPython.core.formatters.html

Author: manzt

plotnine/_utils/ipython.py

@@ -3,29 +3,29 @@
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from typing import Callable, Literal, TypeAlias
+    from typing import Callable, Literal, NotRequired, TypeAlias, TypedDict
 
     from IPython.core.interactiveshell import InteractiveShell
 
     FigureFormat: TypeAlias = Literal[
         "png", "retina", "jpeg", "jpg", "svg", "pdf"
     ]
 
+    class DisplayMetadata(TypedDict):
+        width: NotRequired[int]
+        height: NotRequired[int]
 
-def get_ipython() -> "InteractiveShell":
+
+def get_ipython() -> "None | InteractiveShell":
     """
     Return running IPython instance or None
     """
     try:
         from IPython.core.getipython import get_ipython as _get_ipython
-    except ImportError as err:
-        raise type(err)("IPython is has not been installed.") from err
-
-    ip = _get_ipython()
-    if ip is None:
-        raise RuntimeError("Not running in a juptyer session.")
+    except ImportError:
+        return None
 
-    return ip
+    return _get_ipython()
 
 
 def is_inline_backend():
@@ -39,44 +39,51 @@ def is_inline_backend():
     return "matplotlib_inline.backend_inline" in mpl.get_backend()
 
 
-def get_display_function(
-    format: FigureFormat, figure_size_px: tuple[int, int]
-) -> Callable[[bytes], None]:
+def get_display_function() -> Callable[
+    [dict[str, bytes], dict[str, DisplayMetadata]], None
+]:
     """
     Return a function that will display the plot image
     """
-    from IPython.display import (
-        SVG,
-        Image,
-        display_jpeg,
-        display_pdf,
-        display_png,
-        display_svg,
-    )
-
-    w, h = figure_size_px
-
-    def png(b: bytes):
-        display_png(Image(b, format="png", width=w, height=h))
+    from IPython.display import display
 
-    def retina(b: bytes):
-        display_png(Image(b, format="png", retina=True))
+    def display_func(
+        data: dict[str, bytes], metadata: dict[str, DisplayMetadata]
+    ) -> None:
+        display(data, metadata=metadata, raw=True)
 
-    def jpeg(b: bytes):
-        display_jpeg(Image(b, format="jpeg", width=w, height=h))
+    return display_func
 
-    def svg(b: bytes):
-        display_svg(SVG(b))
 
-    def pdf(b: bytes):
-        display_pdf(b, raw=True)
+def get_mimebundle(
+    b: bytes, format: FigureFormat, figure_size_px: tuple[int, int]
+):
+    """
+    Return a the display MIME bundle from image data
+
+    Parameters
+    ----------
+    format :
+        The figure format
+    figure_size_px :
+        The figure size in pixels (width, height)
+    """
 
     lookup = {
-        "png": png,
-        "retina": retina,
-        "jpeg": jpeg,
-        "jpg": jpeg,
-        "svg": svg,
-        "pdf": pdf,
+        "png": "image/png",
+        "retina": "image/png",
+        "jpeg": "image/jpeg",
+        "svg": "image/svg+xml",
+        "pdf": "application/pdf",
     }
-    return lookup[format]
+    mimetype = lookup[format]
+
+    metadata: dict[str, DisplayMetadata] = {}
+    w, h = figure_size_px
+    if format in ("png", "jpeg"):
+        metadata = {mimetype: {"width": w, "height": h}}
+    elif format == "retina":
+        # `retina=True` in IPython.display.Image just halves width/height
+        metadata = {mimetype: {"width": w // 2, "height": h // 2}}
+
+    return {mimetype: b}, metadata

plotnine/composition/_compose.py

@@ -6,11 +6,6 @@
 from io import BytesIO
 from typing import TYPE_CHECKING, overload
 
-from .._utils.ipython import (
-    get_display_function,
-    get_ipython,
-)
-from ..options import get_option
 from ._plotspec import plotspec
 
 if TYPE_CHECKING:
@@ -20,8 +15,8 @@
     from matplotlib.figure import Figure
 
     from plotnine._mpl.gridspec import p9GridSpec
-    from plotnine._utils.ipython import FigureFormat
     from plotnine.ggplot import PlotAddable, ggplot
+    from plotnine.typing import FigureFormat
 
 
 @dataclass
@@ -218,11 +213,28 @@ def __getitem__(
     def __setitem__(self, key, value):
         self.items[key] = value
 
-    def _ipython_display_(self):
+    def _repr_mimebundle_(self, **kwargs):
         """
-        Display plot in the output of the cell
+        Return dynamic MIME bundle for composition display
         """
-        return self._display()
+        from plotnine._utils.ipython import get_ipython, get_mimebundle
+        from plotnine.options import get_option
+
+        ip = get_ipython()
+        format: FigureFormat = (
+            get_option("figure_format")
+            or (ip and ip.config.InlineBackend.get("figure_format"))
+            or "retina"
+        )
+
+        if format == "retina":
+            self = deepcopy(self)
+            self._to_retina()
+
+        buf = BytesIO()
+        self.save(buf, "png" if format == "retina" else format)
+        figure_size_px = self.last_plot.theme._figure_size_px
+        return get_mimebundle(buf.getvalue(), format, figure_size_px)
 
     @property
     def nrow(self) -> int:
@@ -357,20 +369,11 @@ def _display(self):
         It draws the plot to an io buffer then uses ipython display
         methods to show the result.
         """
-        ip = get_ipython()
-        format: FigureFormat = get_option(
-            "figure_format"
-        ) or ip.config.InlineBackend.get("figure_format", "retina")
+        from plotnine._utils.ipython import get_display_function
 
-        if format == "retina":
-            self = deepcopy(self)
-            self._to_retina()
-
-        buf = BytesIO()
-        self.save(buf, "png" if format == "retina" else format)
-        figure_size_px = self.last_plot.theme._figure_size_px
-        display_func = get_display_function(format, figure_size_px)
-        display_func(buf.getvalue())
+        data, metadata = self._repr_mimebundle_()
+        display_func = get_display_function()
+        display_func(data, metadata)
 
     def draw(self, *, show: bool = False) -> Figure:
         """

plotnine/ggplot.py

@@ -27,6 +27,7 @@
 from ._utils.ipython import (
     get_display_function,
     get_ipython,
+    get_mimebundle,
     is_inline_backend,
 )
 from ._utils.quarto import is_quarto_environment
@@ -55,7 +56,7 @@
     from plotnine.composition import Compose
     from plotnine.coords.coord import coord
     from plotnine.facets.facet import facet
-    from plotnine.typing import DataLike
+    from plotnine.typing import DataLike, FigureFormat
 
     class PlotAddable(Protocol):
         """
@@ -137,14 +138,29 @@ def __str__(self) -> str:
         w, h = self.theme._figure_size_px
         return f"<ggplot: ({w} x {h})>"
 
-    def _ipython_display_(self):
+    def _repr_mimebundle_(self, **kwargs):
         """
-        Display plot in the output of the cell
+        Return dynamic MIME bundle for plot display
 
-        This method will always be called when a ggplot object is the
-        last in the cell.
+        This method is called when a ggplot object is the last in the cell.
         """
-        self._display()
+        ip = get_ipython()
+        format: FigureFormat = (
+            get_option("figure_format")
+            or (ip and ip.config.InlineBackend.get("figure_format"))
+            or "retina"
+        )
+
+        # While jpegs can be displayed as retina, we restrict the output
+        # of "retina" to png
+        if format == "retina":
+            self = copy(self)
+            self.theme = self.theme.to_retina()
+
+        buf = BytesIO()
+        self.save(buf, "png" if format == "retina" else format, verbose=False)
+        figure_size_px = self.theme._figure_size_px
+        return get_mimebundle(buf.getvalue(), format, figure_size_px)
 
     def show(self):
         """
@@ -174,21 +190,9 @@ def _display(self):
         It plots the plot to an io buffer, then uses ipython display
         methods to show the result
         """
-        ip = get_ipython()
-        format = get_option("figure_format") or ip.config.InlineBackend.get(
-            "figure_format", "retina"
-        )
-        # While jpegs can be displayed as retina, we restrict the output
-        # of "retina" to png
-        if format == "retina":
-            self = copy(self)
-            self.theme = self.theme.to_retina()
-
-        buf = BytesIO()
-        self.save(buf, "png" if format == "retina" else format, verbose=False)
-        figure_size_px = self.theme._figure_size_px
-        display_func = get_display_function(format, figure_size_px)
-        display_func(buf.getvalue())
+        data, metadata = self._repr_mimebundle_()
+        display_func = get_display_function()
+        display_func(data, metadata)
 
     def __deepcopy__(self, memo: dict[Any, Any]) -> ggplot:
         """