Broadcast & / * from a host plot into its insets

`(host + inset_element(p, ...)) & theme(...)` now themes both the
host and the inset; `*` is host-only. Both operators are guarded on
`_insets` and return `NotImplemented` on a bare ggplot, so the
existing `+` remains the answer there.

The broadcast lives on `Insets.__and__`, mirroring how
`Compose.__and__` iterates `self.items`. `Compose.__and__` now
descends into ggplot children that carry insets so themes broadcast
on a composition reach every attached inset.

Author: has2k1

plotnine/composition/_compose.py

@@ -284,20 +284,25 @@ def __and__(self, rhs: PlotAddable) -> Self:
         """
         Add rhs to all plots in the composition
 
+        Recurses into ggplot insets too: a plot with insets receives
+        `item & rhs` (which broadcasts to its own host and insets).
+
         Parameters
         ----------
         rhs:
             What to add.
         """
-        from plotnine import theme
+        from plotnine import ggplot, theme
 
         self = deepcopy(self)
 
         if isinstance(rhs, theme):
             self.annotation.theme = self.annotation.theme + rhs
 
         for i, item in enumerate(self):
-            if isinstance(item, Compose):
+            if isinstance(item, Compose) or (
+                isinstance(item, ggplot) and item._insets
+            ):
                 self[i] = item & rhs
             else:
                 item += copy(rhs)

plotnine/composition/_inset_element.py

@@ -262,3 +262,23 @@ def draw(self, which: Literal["above", "below"]):
 
         for inset in insets:
             inset._draw_in_host()
+
+    def __and__(self, rhs) -> Insets:
+        """
+        Apply rhs to every inset's obj, recursing into nested structure
+
+        Insets that themselves have insets receive `obj & rhs` so the
+        broadcast reaches every nested child.
+        """
+        from ..ggplot import ggplot
+        from ._compose import Compose
+
+        new = Insets(deepcopy(self))
+        for inset in new:
+            if isinstance(inset.obj, Compose) or (
+                isinstance(inset.obj, ggplot) and inset.obj._insets
+            ):
+                inset.obj = inset.obj & rhs
+            else:
+                inset.obj = inset.obj + rhs
+        return new

plotnine/ggplot.py

@@ -312,6 +312,35 @@ def __truediv__(self, rhs: Self | Compose) -> Compose:
 
         return Stack([self, rhs])
 
+    def __and__(self, rhs: PlotAddable) -> Self:
+        """
+        Broadcast rhs to this plot and every inset
+
+        Only defined when the plot has insets. On a plot with no insets
+        use `+` instead.
+        """
+        if not self._insets:
+            return NotImplemented
+
+        new = deepcopy(self)
+        new += rhs
+        new._insets = new._insets & rhs
+        return new
+
+    def __mul__(self, rhs: PlotAddable) -> Self:
+        """
+        Apply rhs to this plot only, leaving insets untouched
+
+        Only defined when the plot has insets. On a plot with no insets
+        use `+` instead.
+        """
+        if not self._insets:
+            return NotImplemented
+
+        new = deepcopy(self)
+        new += rhs
+        return new
+
     def __sub__(self, rhs: Self | Compose) -> Compose:
         """
         Compose 2 plots columnwise