Draw insets into the host figure

Adds ggplot._draw_insets to render each attached inset into the host's
figure as the final step of draw(). Refactors _create_figure on both
ggplot and Compose into independent guards for the figure and the
gridspec so a pre-assigned figure (an inset reusing its host's) still
flows through to gridspec creation. Adds a _zorder class default on
ggplot and Compose that the inset path raises above the host.

Author: has2k1

plotnine/composition/_compose.py

@@ -130,6 +130,15 @@ class Compose:
     """
     _sidespaces: CompositionSideSpaces
 
+    _zorder: int = 0
+    """
+    Drawing zorder for every axes in this composition
+
+    It is propagated down the tree at draw time so sub-plots inherit their
+    parent's value, and raised on inset compositions so their axes paint
+    above the host.
+    """
+
     def __init__(self, items: list[ggplot | Compose]):
         # The way we handle the plots has consequences that would
         # prevent having a duplicate plot in the composition.
@@ -461,19 +470,21 @@ def _create_figure(self):
         """
         Create figure & gridspecs for all sub compositions
         """
-        if hasattr(self, "figure"):
-            return
+        if not hasattr(self, "figure"):
+            import matplotlib.pyplot as plt
 
-        import matplotlib.pyplot as plt
+            from plotnine._mpl.layout_manager import PlotnineLayoutEngine
 
-        from plotnine._mpl.gridspec import p9GridSpec
-        from plotnine._mpl.layout_manager import PlotnineLayoutEngine
+            self.figure = plt.figure()
+            self.figure.set_layout_engine(PlotnineLayoutEngine(self))
 
-        figure = plt.figure()
-        self._generate_gridspecs(
-            figure, p9GridSpec(1, 1, figure, nest_into=None)
-        )
-        figure.set_layout_engine(PlotnineLayoutEngine(self))
+        if not hasattr(self, "_gridspec"):
+            from plotnine._mpl.gridspec import p9GridSpec
+
+            self._generate_gridspecs(
+                self.figure,
+                p9GridSpec(1, 1, self.figure, nest_into=None),
+            )
 
     def _generate_gridspecs(self, figure: Figure, container_gs: p9GridSpec):
         from plotnine import ggplot

plotnine/ggplot.py

@@ -135,6 +135,14 @@ class ggplot:
 
     _sidespaces: PlotSideSpaces
 
+    _zorder: int = 0
+    """
+    Drawing zorder for every axes created for this plot
+
+    The default (``0``) keeps the plot at the base layer. `_draw_insets`
+    raises this on inset plots so they render above their host.
+    """
+
     def __init__(
         self,
         data: Optional[DataLike] = None,
@@ -373,6 +381,10 @@ def draw(self, *, show: bool = False) -> Figure:
             # Artist object theming
             self.theme.apply()
 
+            # Insets render after host theming is finalised so their
+            # own draw picks up a fully-realised host figure.
+            self._draw_insets()
+
         return figure
 
     def _setup(self) -> Figure:
@@ -387,17 +399,18 @@ def _create_figure(self):
         """
         Create gridspec for the panels
         """
-        if hasattr(self, "figure"):
-            return
+        if not hasattr(self, "figure"):
+            import matplotlib.pyplot as plt
 
-        import matplotlib.pyplot as plt
+            from ._mpl.layout_manager import PlotnineLayoutEngine
 
-        from ._mpl.gridspec import p9GridSpec
-        from ._mpl.layout_manager import PlotnineLayoutEngine
+            self.figure = plt.figure()
+            self.figure.set_layout_engine(PlotnineLayoutEngine(self))
 
-        self.figure = plt.figure()
-        self._gridspec = p9GridSpec(1, 1, self.figure)
-        self.figure.set_layout_engine(PlotnineLayoutEngine(self))
+        if not hasattr(self, "_gridspec"):
+            from ._mpl.gridspec import p9GridSpec
+
+            self._gridspec = p9GridSpec(1, 1, self.figure)
 
     def _build(self):
         """
@@ -593,6 +606,20 @@ def _draw_watermarks(self):
         for wm in self.watermarks:
             wm.draw(self.figure)
 
+    def _draw_insets(self):
+        """
+        Draw every inset attached to this plot into the host figure
+
+        Each inset reuses the host's figure instead of creating its own.
+        The inset's zorder is raised above the host's so its axes paint
+        on top; for Compose insets this zorder is propagated down the
+        sub-tree when the composition is drawn.
+        """
+        for inset in self._insets:
+            inset.obj.figure = self.figure
+            inset.obj._zorder = self._zorder + 1
+            inset.obj.draw()
+
     def _draw_plot_background(self):
         from matplotlib.lines import Line2D
         from matplotlib.patches import Rectangle