ENH: Improve getting output with quarto and the knitr engine

closes #970

Author: has2k1

doc/changelog.qmd

@@ -9,6 +9,18 @@ title: Changelog
 
 - Added [](:class:`~plotnine.scale_stroke_identity`) which was conspicuously missing!
 
+- Added [](:class:`~plotnine.composition.Compose.show`), making it possible to output/show 
+  plot composition objects when they are not the last object in a cell.
+
+### Enhancements
+
+- In a jupyter environment, the output when the plot is the last in a cell is
+  now rendered without side effects. ({{< pr 969 >}})
+
+- When using the knitr engine in a Quarto document, you no longer need to
+  class `plot.show()` to get output if the `plot` is the last object in
+  the cell. ({{< issue 970 >}})
+
 ### Bug Fixes
 
 - Fixed labels set with the `labs` call so that they are only ever overwritten

plotnine/_utils/context.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 import pandas as pd
@@ -8,17 +9,40 @@
     from typing_extensions import Self
 
     from plotnine import ggplot
+    from plotnine.composition import Compose
+
+
+def reopen(fig):
+    """
+    Reopen an MPL figure that has been closed with plt.close
+
+    When drawing compositions, plot_composition_context will nest
+    plot_context. In this case, plot_context may close an MPL figure
+    that belongs to composition. A closed figure cannot be shown with
+    plt.show, so for compositions compose.show (if called) will do nothing.
+    """
+    from matplotlib._pylab_helpers import Gcf
+
+    Gcf.set_active(fig.canvas.manager)
+
+
+def is_closed(fig) -> bool:
+    """
+    Return True if figure is closed
+    """
+    import matplotlib.pyplot as plt
+
+    return not plt.fignum_exists(fig.number)
 
 
 class plot_context:
     """
-    Context to setup the environment within with the plot is built
+    Context within which the plot is built
 
     Parameters
     ----------
     plot :
         ggplot object to be built within the context.
-        exits.
     show :
         Whether to show the plot.
     """
@@ -66,3 +90,55 @@ def __exit__(self, exc_type, exc_value, exc_traceback):
 
         self.rc_context.__exit__(exc_type, exc_value, exc_traceback)
         self.pd_option_context.__exit__(exc_type, exc_value, exc_traceback)
+
+
+@dataclass
+class plot_composition_context:
+    """
+    Context within which a plot composition is built
+
+    Parameters
+    ----------
+    cmp :
+        composition object to be built within the context.
+    show :
+        Whether to show the plot.
+    """
+
+    cmp: Compose
+    show: bool
+
+    def __post_init__(self):
+        import matplotlib as mpl
+
+        # The dpi is needed when the figure is created, either as
+        # a parameter to plt.figure() or an rcParam.
+        # https://github.com/matplotlib/matplotlib/issues/24644
+        # When drawing the Composition, the dpi themeable is infective
+        # because it sets the rcParam after this figure is created.
+        rcParams = {"figure.dpi": self.cmp.last_plot.theme.getp("dpi")}
+        self._rc_context = mpl.rc_context(rcParams)
+
+    def __enter__(self) -> Self:
+        """
+        Enclose in matplolib & pandas environments
+        """
+        self._rc_context.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        import matplotlib.pyplot as plt
+
+        if exc_type is None:
+            if self.show:
+                if is_closed(self.cmp.figure):
+                    reopen(self.cmp.figure)
+                plt.show()
+            else:
+                plt.close(self.cmp.figure)
+        else:
+            # There is an exception, close any figure
+            if hasattr(self.cmp, "figure"):
+                plt.close(self.cmp.figure)
+
+        self._rc_context.__exit__(exc_type, exc_value, exc_traceback)

plotnine/_utils/quarto.py

@@ -1,4 +1,6 @@
 import os
+import sys
+from functools import lru_cache
 
 
 def is_quarto_environment() -> bool:
@@ -31,3 +33,22 @@ def set_options_from_quarto():
     set_option("dpi", dpi)
     set_option("figure_size", figure_size)
     set_option("figure_format", figure_format)
+
+
+# We do not expect the contents the file stored in the QUARTO_EXECUTE_INFO
+# variable to change. We can can cache the output
+@lru_cache()
+def is_knitr_engine() -> bool:
+    """
+    Return True if knitr is executing the code
+    """
+
+    if filename := os.environ.get("QUARTO_EXECUTE_INFO"):  # Quarto >= 1.8.21
+        import json
+        from pathlib import Path
+
+        info = json.loads(Path(filename).read_text())
+        return info["format"]["execute"]["engine"] == "knitr"
+    else:
+        # NOTE: Remove this branch some time after quarto 1.9 is released
+        return "rpytools" in sys.modules

plotnine/composition/_beside.py

@@ -9,7 +9,7 @@
     from plotnine.ggplot import ggplot
 
 
-@dataclass
+@dataclass(repr=False)
 class Beside(Compose):
     """
     Place plots or compositions side by side

plotnine/composition/_compose.py

@@ -6,18 +6,19 @@
 from io import BytesIO
 from typing import TYPE_CHECKING, overload
 
+from .._utils.context import plot_composition_context
 from .._utils.ipython import (
     get_ipython,
     get_mimebundle,
     is_inline_backend,
 )
-from .._utils.quarto import is_quarto_environment
+from .._utils.quarto import is_knitr_engine, is_quarto_environment
 from ..options import get_option
 from ._plotspec import plotspec
 
 if TYPE_CHECKING:
     from pathlib import Path
-    from typing import Generator, Iterator, Self
+    from typing import Generator, Iterator
 
     from matplotlib.figure import Figure
 
@@ -101,6 +102,22 @@ def __post_init__(self):
             for op in self.items
         ]
 
+    def __repr__(self):
+        """
+        repr
+
+        Notes
+        -----
+        Subclasses that are dataclasses should be declared with
+        `@dataclass(repr=False)`.
+        """
+        # knitr relies on __repr__ to automatically print the last object
+        # in a cell.
+        if is_knitr_engine():
+            self.show()
+            return ""
+        return super().__repr__()
+
     @abc.abstractmethod
     def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
@@ -321,6 +338,15 @@ def _create_gridspec(self, figure, nest_into):
             self.nrow, self.ncol, figure, nest_into=nest_into
         )
 
+    def _setup(self) -> Figure:
+        """
+        Setup this instance for the building process
+        """
+        if not hasattr(self, "figure"):
+            self._create_figure()
+
+        return self.figure
+
     def _create_figure(self):
         import matplotlib.pyplot as plt
 
@@ -364,6 +390,13 @@ def _make_plotspecs(
         self.figure = plt.figure()
         self.plotspecs = list(_make_plotspecs(self, None))
 
+    def _draw_plots(self):
+        """
+        Draw all plots in the composition
+        """
+        for ps in self.plotspecs:
+            ps.plot.draw()
+
     def show(self):
         """
         Display plot in the cells output
@@ -400,15 +433,9 @@ def draw(self, *, show: bool = False) -> Figure:
         from .._mpl.layout_manager import PlotnineCompositionLayoutEngine
 
         with plot_composition_context(self, show):
-            self._create_figure()
-            figure = self.figure
-
-            for ps in self.plotspecs:
-                ps.plot.draw()
-
-            self.figure.set_layout_engine(
-                PlotnineCompositionLayoutEngine(self)
-            )
+            figure = self._setup()
+            self._draw_plots()
+            figure.set_layout_engine(PlotnineCompositionLayoutEngine(self))
         return figure
 
     def save(
@@ -442,42 +469,3 @@ def save(
         plot = (self + theme(dpi=dpi)) if dpi else self
         figure = plot.draw()
         figure.savefig(filename, format=format)
-
-
-@dataclass
-class plot_composition_context:
-    cmp: Compose
-    show: bool
-
-    def __post_init__(self):
-        import matplotlib as mpl
-
-        # The dpi is needed when the figure is created, either as
-        # a parameter to plt.figure() or an rcParam.
-        # https://github.com/matplotlib/matplotlib/issues/24644
-        # When drawing the Composition, the dpi themeable is infective
-        # because it sets the rcParam after this figure is created.
-        rcParams = {"figure.dpi": self.cmp.last_plot.theme.getp("dpi")}
-        self._rc_context = mpl.rc_context(rcParams)
-
-    def __enter__(self) -> Self:
-        """
-        Enclose in matplolib & pandas environments
-        """
-        self._rc_context.__enter__()
-        return self
-
-    def __exit__(self, exc_type, exc_value, exc_traceback):
-        import matplotlib.pyplot as plt
-
-        if exc_type is None:
-            if self.show:
-                plt.show()
-            else:
-                plt.close(self.cmp.figure)
-        else:
-            # There is an exception, close any figure
-            if hasattr(self.cmp, "figure"):
-                plt.close(self.cmp.figure)
-
-        self._rc_context.__exit__(exc_type, exc_value, exc_traceback)

plotnine/composition/_stack.py

@@ -9,7 +9,7 @@
     from plotnine.ggplot import ggplot
 
 
-@dataclass
+@dataclass(repr=False)
 class Stack(Compose):
     """
     Place plots or compositions on top of each other

plotnine/ggplot.py

@@ -29,7 +29,7 @@
     get_mimebundle,
     is_inline_backend,
 )
-from ._utils.quarto import is_quarto_environment
+from ._utils.quarto import is_knitr_engine, is_quarto_environment
 from .coords import coord_cartesian
 from .exceptions import PlotnineError, PlotnineWarning
 from .facets import facet_null
@@ -137,6 +137,14 @@ def __str__(self) -> str:
         w, h = self.theme._figure_size_px
         return f"<ggplot: ({w} x {h})>"
 
+    def __repr__(self):
+        # knitr relies on __repr__ to automatically print the last object
+        # in a cell.
+        if is_knitr_engine():
+            self.show()
+            return ""
+        return super().__repr__()
+
     def _repr_mimebundle_(self, include=None, exclude=None) -> MimeBundle:
         """
         Return dynamic MIME bundle for plot display