Add inset_element class and ggplot._insets attribute

Introduces the inset_element dataclass for placing a plot or composition
as an overlay on a host plot at NPC coordinates, and the ggplot._insets
list that stores them. Wiring into the draw and layout pipeline comes
in later commits.

Author: has2k1

plotnine/composition/__init__.py

@@ -1,5 +1,6 @@
 from ._beside import Beside
 from ._compose import Compose
+from ._inset_element import inset_element
 from ._plot_annotation import plot_annotation
 from ._plot_layout import plot_layout
 from ._plot_spacer import plot_spacer
@@ -11,6 +12,7 @@
     "Stack",
     "Beside",
     "Wrap",
+    "inset_element",
     "plot_annotation",
     "plot_layout",
     "plot_spacer",

plotnine/composition/_inset_element.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    from ..ggplot import ggplot
+    from ._compose import Compose
+
+
+@dataclass
+class inset_element:
+    """
+    Place a plot as an inset within another plot
+
+    The inset is rendered on top of the host. Adding an `inset_element`
+    to a composition attaches it to the most recently added plot in that
+    composition.
+
+    Parameters
+    ----------
+    obj :
+        The object to render as an inset.
+    left, bottom, right, top :
+        Bounding box of the inset in normalised parent coordinates,
+        in the range ``[0, 1]``. The bottom-left corner of the region
+        selected by `align_to` is ``(0, 0)`` and the top-right is
+        ``(1, 1)``.
+    align_to :
+        Which region of the host plot the bounding box is relative to:
+
+        - ``"panel"`` — the data area only (default).
+        - ``"plot"``  — the panel plus axes, labels, and plot margins.
+        - ``"full"``  — everything the host plot occupies, including
+          any titles, captions, and legends.
+    """
+
+    obj: ggplot | Compose
+    left: float
+    bottom: float
+    right: float
+    top: float
+    align_to: Literal["panel", "plot", "full"] = "panel"
+
+    def __post_init__(self):
+        from ..ggplot import ggplot
+        from ._compose import Compose
+
+        if not isinstance(self.obj, (ggplot, Compose)):
+            raise TypeError(
+                "inset_element requires a ggplot or Compose, got "
+                f"{type(self.obj).__name__!r}."
+            )
+
+        if not 0.0 <= self.left < self.right <= 1.0:
+            raise ValueError(
+                "inset_element requires 0.0 <= left < right <= 1.0, got "
+                f"left={self.left!r}, right={self.right!r}."
+            )
+
+        if not 0.0 <= self.bottom < self.top <= 1.0:
+            raise ValueError(
+                "inset_element requires 0.0 <= bottom < top <= 1.0, got "
+                f"bottom={self.bottom!r}, top={self.top!r}."
+            )
+
+    def __radd__(self, other: ggplot) -> ggplot:
+        """
+        Attach this inset to a ggplot
+        """
+        other._insets.append(deepcopy(self))
+        return other

plotnine/ggplot.py

@@ -55,7 +55,7 @@
     from plotnine import watermark
     from plotnine._mpl.gridspec import p9GridSpec
     from plotnine._mpl.layout_manager._plot_side_space import PlotSideSpaces
-    from plotnine.composition import Compose
+    from plotnine.composition import Compose, inset_element
     from plotnine.coords.coord import coord
     from plotnine.facets.facet import facet
     from plotnine.typing import DataLike, FigureFormat, MimeBundle
@@ -156,6 +156,7 @@ def __init__(
         self.environment = Environment.capture(1)
         self.layout = Layout()
         self.watermarks: list[watermark] = []
+        self._insets: list[inset_element] = []
 
         # build artefacts
         self._build_objs = NS(meta={})