Tighten Self annotations on ggplot and Compose operators

Promote return types from ggplot/Compose to Self where the body
preserves the runtime class — ggplot's __deepcopy__, __add__ overloads,
__or__/__truediv__/__sub__/__rrshift__, and Compose's __and__/__mul__.
The other Compose operators (__or__, __truediv__, __sub__, __add__)
keep Compose as their return type because they cross-construct
(e.g. Stack | x → Beside) and would be unsound as Self.

Also type the rhs of plot_spacer's __add__/__iadd__ explicitly so the
override is visible to pyright.

Author: has2k1

plotnine/composition/_compose.py

@@ -24,6 +24,7 @@
     from typing import Iterator
 
     from matplotlib.figure import Figure
+    from typing_extensions import Self
 
     from plotnine._mpl.gridspec import p9GridSpec
     from plotnine._mpl.layout_manager._composition_side_space import (
@@ -278,7 +279,7 @@ def __sub__(self, rhs: ggplot | Compose) -> Compose:
 
         return Beside([self, rhs])
 
-    def __and__(self, rhs: PlotAddable) -> Compose:
+    def __and__(self, rhs: PlotAddable) -> Self:
         """
         Add rhs to all plots in the composition
 
@@ -302,7 +303,7 @@ def __and__(self, rhs: PlotAddable) -> Compose:
 
         return self
 
-    def __mul__(self, rhs: PlotAddable) -> Compose:
+    def __mul__(self, rhs: PlotAddable) -> Self:
         """
         Add rhs to the outermost nesting level of the composition
 

plotnine/ggplot.py

@@ -222,7 +222,7 @@ def show(self):
         else:
             self.draw(show=True)
 
-    def __deepcopy__(self, memo: dict[Any, Any]) -> ggplot:
+    def __deepcopy__(self, memo: dict[Any, Any]) -> Self:
         """
         Deep copy without copying the dataframe and environment
         """
@@ -264,15 +264,15 @@ def __iadd__(self, other: PlotAddable | list[PlotAddable] | None) -> Self:
     def __add__(
         self,
         rhs: PlotAddable | list[PlotAddable] | None,
-    ) -> ggplot: ...
+    ) -> Self: ...
 
     @overload
-    def __add__(self, rhs: ggplot) -> Compose: ...
+    def __add__(self, rhs: Self) -> Compose: ...
 
     def __add__(
         self,
-        rhs: PlotAddable | list[PlotAddable] | None | ggplot,
-    ) -> ggplot | Compose:
+        rhs: PlotAddable | list[PlotAddable] | None | Self,
+    ) -> Self | Compose:
         """
         Add to ggplot
 
@@ -293,31 +293,31 @@ def __add__(
 
         return self.__iadd__(rhs)
 
-    def __or__(self, rhs: ggplot | Compose) -> Compose:
+    def __or__(self, rhs: Self | Compose) -> Compose:
         """
         Compose 2 plots columnwise
         """
         from .composition import Beside
 
         return Beside([self, rhs])
 
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+    def __truediv__(self, rhs: Self | Compose) -> Compose:
         """
         Compose 2 plots rowwise
         """
         from .composition import Stack
 
         return Stack([self, rhs])
 
-    def __sub__(self, rhs: ggplot | Compose) -> Compose:
+    def __sub__(self, rhs: Self | Compose) -> Compose:
         """
         Compose 2 plots columnwise
         """
         from .composition import Beside
 
         return Beside([self, rhs])
 
-    def __rrshift__(self, other: DataLike) -> ggplot:
+    def __rrshift__(self, other: DataLike) -> Self:
         """
         Overload the >> operator to receive a dataframe
         """