plotnine 0.15.0a7__tar.gz → 0.15.0a8__tar.gz

{plotnine-0.15.0a7/plotnine.egg-info → plotnine-0.15.0a8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotnine
-Version: 0.15.0a7
+Version: 0.15.0a8
 Summary: A Grammar of Graphics for Python
 Author-email: Hassan Kibirige <has2k1@gmail.com>
 License: The MIT License (MIT)

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/doc/_quartodoc.yml

@@ -535,7 +535,7 @@ quartodoc:
     - title: Composing Plots
       package: plotnine.composition
       contents:
-        - name: Arrange
+        - name: Compose
           include_attributes: false
         - Stack
         - Beside

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/_mpl/layout_manager/_engine.py

@@ -13,7 +13,7 @@ if TYPE_CHECKING:
     from matplotlib.figure import Figure
 
     from plotnine import ggplot
-    from plotnine.composition import Arrange
+    from plotnine.composition import Compose
 
 
 class PlotnineLayoutEngine(LayoutEngine):
@@ -54,7 +54,7 @@ class PlotnineCompositionLayoutEngine(LayoutEngine):
     _adjust_compatible = True
     _colorbar_gridspec = False
 
-    def __init__(self, composition: Arrange):
+    def __init__(self, composition: Compose):
         self.composition = composition
 
     def execute(self, fig: Figure):

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/_mpl/layout_manager/_layout_tree.py

@@ -16,7 +16,7 @@ if TYPE_CHECKING:
 
     from plotnine import ggplot
     from plotnine._mpl.gridspec import p9GridSpec
-    from plotnine.composition import Arrange
+    from plotnine.composition import Compose
 
 
 @dataclass
@@ -82,7 +82,7 @@ class LayoutTree:
 
     @staticmethod
     def create(
-        cmp: Arrange,
+        cmp: Compose,
         lookup_spaces: dict[ggplot, LayoutSpaces],
     ) -> LayoutTree:
         """

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/composition/__init__.py

@@ -1,10 +1,10 @@
-from ._arrange import Arrange
 from ._beside import Beside
+from ._compose import Compose
 from ._plot_spacer import plot_spacer
 from ._stack import Stack
 
 __all__ = (
-    "Arrange",
+    "Compose",
     "Stack",
     "Beside",
     "plot_spacer",

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/composition/_beside.py

@@ -3,14 +3,14 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from ._arrange import Arrange
+from ._compose import Compose
 
 if TYPE_CHECKING:
     from plotnine.ggplot import ggplot
 
 
 @dataclass
-class Beside(Arrange):
+class Beside(Compose):
     """
     Place plots or compositions side by side
 
@@ -27,6 +27,7 @@ class Beside(Arrange):
     --------
     plotnine.composition.Stack : To arrange plots vertically
     plotnine.composition.plot_spacer : To add a blank space between plots
+    plotnine.composition.Compose : For more on composing plots
     """
 
     @property
@@ -37,7 +38,7 @@ class Beside(Arrange):
     def ncol(self) -> int:
         return len(self)
 
-    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a column
         """
@@ -45,7 +46,7 @@ class Beside(Arrange):
         # operands into a single operation
         return Beside([*self, rhs])
 
-    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a row
         """

plotnine-0.15.0a7/plotnine/composition/_arrange.py → plotnine-0.15.0a8/plotnine/composition/_compose.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
 import abc
-from copy import deepcopy
+from copy import copy, deepcopy
 from dataclasses import dataclass, field
 from io import BytesIO
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, overload
 
 from .._utils.ipython import (
     get_display_function,
@@ -25,19 +25,53 @@ if TYPE_CHECKING:
 
 
 @dataclass
-class Arrange:
+class Compose:
     """
     Base class for those that create plot compositions
 
     As a user, you will never directly work with this class, except
-    the operators [`|`](`plotnine.composition.Beside`) and
-    [`/`](`plotnine.composition.Stack`) that are powered by subclasses
-    of this class.
+    through the operators that it makes possible.
+    The operators are of two kinds:
 
-    Parameters
-    ----------
-    operands:
-        The objects to be put together (composed).
+    ### 1. Composing Operators
+
+    The combine plots or compositions into a single composition.
+    Both operands are either a plot or a composition.
+
+    `/`
+
+    :   Arrange operands side by side.
+        Powered by the subclass [](`~plotnine.composition.Beside`).
+
+    `|`
+
+    :   Arrange operands vertically.
+        Powered by the subclass [](`~plotnine.composition.Stack`).
+
+    `-`
+
+    :   Arrange operands side by side _and_ at the same nesting level.
+        Also powered by the subclass [](`~plotnine.composition.Beside`).
+
+    ### 2. Plot Modifying Operators
+
+    The modify all or some of the plots in a composition.
+    The left operand is a composition and the right operand is a
+    _plotaddable_; any object that can be added to a `ggplot` object
+    e.g. _geoms_, _stats_, _themes_, _facets_, ... .
+
+    `&`
+
+    :   Add right hand side to all plots in the composition.
+
+    `*`
+
+    :   Add right hand side to all plots in the top-most nesting
+        level of the composition.
+
+    `+`
+
+    :    Add right hand side to the last plot in the composition.
 
     See Also
     --------
@@ -46,7 +80,10 @@ class Arrange:
     plotnine.composition.plot_spacer : To add a blank space between plots
     """
 
-    operands: list[ggplot | Arrange]
+    items: list[ggplot | Compose]
+    """
+    The objects to be arranged (composed).
+    """
 
     # These are created in the _create_figure method
     figure: Figure = field(init=False, repr=False)
@@ -57,24 +94,24 @@ class Arrange:
         # The way we handle the plots has consequences that would
         # prevent having a duplicate plot in the composition.
         # Using copies prevents this.
-        self.operands = [
-            op if isinstance(op, Arrange) else deepcopy(op)
-            for op in self.operands
+        self.items = [
+            op if isinstance(op, Compose) else deepcopy(op)
+            for op in self.items
         ]
 
     @abc.abstractmethod
-    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a column
         """
 
     @abc.abstractmethod
-    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a row
         """
 
-    def __add__(self, rhs: ggplot | Arrange | PlotAddable) -> Arrange:
+    def __add__(self, rhs: ggplot | Compose | PlotAddable) -> Compose:
         """
         Add rhs to the composition
 
@@ -85,13 +122,16 @@ class Arrange:
         """
         from plotnine import ggplot
 
-        if not isinstance(rhs, (ggplot, Arrange)):
+        if not isinstance(rhs, (ggplot, Compose)):
             cmp = deepcopy(self)
             cmp.last_plot = cmp.last_plot + rhs
             return cmp
-        return self.__class__([*self, rhs])
 
-    def __sub__(self, rhs: ggplot | Arrange) -> Arrange:
+        t1, t2 = type(self).__name__, type(rhs).__name__
+        msg = f"unsupported operand type(s) for +: '{t1}' and '{t2}'"
+        raise TypeError(msg)
+
+    def __sub__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add the rhs onto the composition
 
@@ -100,9 +140,18 @@ class Arrange:
         rhs:
             What to place besides the composition
         """
-        return self.__class__([self, rhs])
+        from plotnine import ggplot
+
+        from . import Beside
+
+        if not isinstance(rhs, (ggplot, Compose)):
+            t1, t2 = type(self).__name__, type(rhs).__name__
+            msg = f"unsupported operand type(s) for -: '{t1}' and '{t2}'"
+            raise TypeError(msg)
+
+        return Beside([self, rhs])
 
-    def __and__(self, rhs: PlotAddable) -> Arrange:
+    def __and__(self, rhs: PlotAddable) -> Compose:
         """
         Add rhs to all plots in the composition
 
@@ -113,17 +162,17 @@ class Arrange:
         """
         self = deepcopy(self)
 
-        def add_other(op: Arrange):
-            for item in op:
-                if isinstance(item, Arrange):
+        def add_other(cmp: Compose):
+            for i, item in enumerate(cmp):
+                if isinstance(item, Compose):
                     add_other(item)
                 else:
-                    item += rhs
+                    cmp[i] = item + copy(rhs)
 
         add_other(self)
         return self
 
-    def __mul__(self, rhs: PlotAddable) -> Arrange:
+    def __mul__(self, rhs: PlotAddable) -> Compose:
         """
         Add rhs to the outermost nesting level of the composition
 
@@ -136,22 +185,38 @@ class Arrange:
 
         self = deepcopy(self)
 
-        for item in self:
+        for i, item in enumerate(self):
             if isinstance(item, ggplot):
-                item += rhs
+                self[i] = item + copy(rhs)
+
         return self
 
     def __len__(self) -> int:
         """
         Number of operand
         """
-        return len(self.operands)
+        return len(self.items)
 
-    def __iter__(self) -> Iterator[ggplot | Arrange]:
+    def __iter__(self) -> Iterator[ggplot | Compose]:
         """
-        Return an iterable of all the operands
+        Return an iterable of all the items
         """
-        return iter(self.operands)
+        return iter(self.items)
+
+    @overload
+    def __getitem__(self, index: int) -> ggplot | Compose: ...
+
+    @overload
+    def __getitem__(self, index: slice) -> list[ggplot | Compose]: ...
+
+    def __getitem__(
+        self,
+        index: int | slice,
+    ) -> ggplot | Compose | list[ggplot | Compose]:
+        return self.items[index]
+
+    def __setitem__(self, key, value):
+        self.items[key] = value
 
     def _ipython_display_(self):
         """
@@ -180,7 +245,7 @@ class Arrange:
         """
         from plotnine import ggplot
 
-        last_operand = self.operands[-1]
+        last_operand = self.items[-1]
         if isinstance(last_operand, ggplot):
             return last_operand
         else:
@@ -193,9 +258,9 @@ class Arrange:
         """
         from plotnine import ggplot
 
-        last_operand = self.operands[-1]
+        last_operand = self.items[-1]
         if isinstance(last_operand, ggplot):
-            self.operands[-1] = plot
+            self.items[-1] = plot
         else:
             last_operand.last_plot = plot
 
@@ -247,7 +312,7 @@ class Arrange:
         from plotnine._mpl.gridspec import p9GridSpec
 
         def _make_plotspecs(
-            cmp: Arrange, parent_gridspec: p9GridSpec | None
+            cmp: Compose, parent_gridspec: p9GridSpec | None
         ) -> Generator[plotspec]:
             """
             Return the plot specification for each subplot in the composition
@@ -355,7 +420,7 @@ class Arrange:
         dpi :
             DPI to use for raster graphics. If None, defaults to using
             the `dpi` of theme to the first plot.
-        kwargs :
+        **kwargs :
             These are ignored. Here to "softly" match the API of
             `ggplot.save()`.
         """
@@ -370,7 +435,7 @@ class Arrange:
 
 @dataclass
 class plot_composition_context:
-    cmp: Arrange
+    cmp: Compose
     show: bool
 
     def __post_init__(self):

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/composition/_plot_spacer.py

@@ -22,7 +22,7 @@ class plot_spacer(ggplot):
     --------
     plotnine.composition.Beside : To arrange plots side by side
     plotnine.composition.Stack : To arrange plots vertically
-    plotnine.composition.Arrange : For more on arranging plots
+    plotnine.composition.Compose : For more on composing plots
     """
 
     def __init__(

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/composition/_stack.py

@@ -3,14 +3,14 @@ from __future__ import annotations
 from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
-from ._arrange import Arrange
+from ._compose import Compose
 
 if TYPE_CHECKING:
     from plotnine.ggplot import ggplot
 
 
 @dataclass
-class Stack(Arrange):
+class Stack(Compose):
     """
     Place plots or compositions on top of each other
 
@@ -27,6 +27,7 @@ class Stack(Arrange):
     --------
     plotnine.composition.Beside : To arrange plots side by side
     plotnine.composition.plot_spacer : To add a blank space between plots
+    plotnine.composition.Compose : For more on composing plots
     """
 
     @property
@@ -37,7 +38,7 @@ class Stack(Arrange):
     def ncol(self) -> int:
         return 1
 
-    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a row
         """
@@ -45,7 +46,7 @@ class Stack(Arrange):
         # operands into a single operation
         return Stack([*self, rhs])
 
-    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
         Add rhs as a column
         """

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/ggplot.py

@@ -52,7 +52,7 @@ if TYPE_CHECKING:
 
     from plotnine import watermark
     from plotnine._mpl.gridspec import p9GridSpec
-    from plotnine.composition import Arrange
+    from plotnine.composition import Compose
     from plotnine.coords.coord import coord
     from plotnine.facets.facet import facet
     from plotnine.layer import layer
@@ -245,7 +245,7 @@ class ggplot:
         self = deepcopy(self)
         return self.__iadd__(rhs)
 
-    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
         """
         Compose 2 plots columnwise
         """
@@ -253,7 +253,7 @@ class ggplot:
 
         return Beside([self, rhs])
 
-    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
         Compose 2 plots rowwise
         """
@@ -261,7 +261,7 @@ class ggplot:
 
         return Stack([self, rhs])
 
-    def __sub__(self, rhs: ggplot | Arrange) -> Arrange:
+    def __sub__(self, rhs: ggplot | Compose) -> Compose:
         """
         Compose 2 plots columnwise
         """

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine/themes/theme.py

@@ -72,7 +72,7 @@ class theme:
         ```
 
         will only modify the x-axis text.
-    kwargs: dict
+    kwargs: Any
         kwargs are `themeables`. The themeables are elements that are
         subclasses of `themeable`. Many themeables are defined using
         theme elements i.e

{plotnine-0.15.0a7 → plotnine-0.15.0a8/plotnine.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plotnine
-Version: 0.15.0a7
+Version: 0.15.0a8
 Summary: A Grammar of Graphics for Python
 Author-email: Hassan Kibirige <has2k1@gmail.com>
 License: The MIT License (MIT)

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/plotnine.egg-info/SOURCES.txt

@@ -76,8 +76,8 @@ plotnine/_utils/quarto.py
 plotnine/_utils/registry.py
 plotnine/_utils/yippie.py
 plotnine/composition/__init__.py
-plotnine/composition/_arrange.py
 plotnine/composition/_beside.py
+plotnine/composition/_compose.py
 plotnine/composition/_plot_spacer.py
 plotnine/composition/_plotspec.py
 plotnine/composition/_stack.py
@@ -565,13 +565,17 @@ tests/baseline_images/test_layout/plot_topright_margin_in_fig.png
 tests/baseline_images/test_layout/plot_topright_margin_in_pt.png
 tests/baseline_images/test_layout/plot_xycoords.png
 tests/baseline_images/test_layout/turn_off_guide.png
+tests/baseline_images/test_plot_composition/and_operator.png
 tests/baseline_images/test_plot_composition/basic_horizontal_align_resize.png
 tests/baseline_images/test_plot_composition/basic_vertical_align_resize.png
 tests/baseline_images/test_plot_composition/complex_composition.png
 tests/baseline_images/test_plot_composition/facets.png
 tests/baseline_images/test_plot_composition/horizontal_tag_align.png
+tests/baseline_images/test_plot_composition/minus.png
+tests/baseline_images/test_plot_composition/mul_operator.png
 tests/baseline_images/test_plot_composition/nested_horizontal_align_resize.png
 tests/baseline_images/test_plot_composition/nested_vertical_align_resize.png
+tests/baseline_images/test_plot_composition/plus_operator.png
 tests/baseline_images/test_plot_composition/test_nested_horizontal_align_1.png
 tests/baseline_images/test_plot_composition/test_nested_horizontal_align_2.png
 tests/baseline_images/test_plot_composition/test_nested_vertical_align_1.png

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/tests/conftest.py

@@ -11,7 +11,7 @@ import matplotlib.pyplot as plt
 from matplotlib.testing.compare import compare_images
 
 from plotnine import ggplot, theme
-from plotnine.composition import Arrange, Beside, Stack
+from plotnine.composition import Beside, Compose, Stack
 from plotnine.themes.theme import DEFAULT_RCPARAMS
 
 TOLERANCE = 2  # Default tolerance for the tests
@@ -235,7 +235,7 @@ def layer_data(p, i=0):
     return p.layers.data[i]
 
 
-def composition_equals(cmp: Arrange, name: str) -> bool:
+def composition_equals(cmp: Compose, name: str) -> bool:
     """
     Compare plot composition to image determined by `right`
 
@@ -246,7 +246,7 @@ def composition_equals(cmp: Arrange, name: str) -> bool:
     name :
         Identifier for the test image
 
-    This function is meant to monkey patch Arrange.__eq__
+    This function is meant to monkey patch Compose.__eq__
     so that tests can use the `assert` statement.
     """
     test_file = inspect.stack()[1][1]
@@ -273,6 +273,6 @@ def composition_equals(cmp: Arrange, name: str) -> bool:
 
 # Note that, dataclass subclasses have their own __eq__ and not that of the
 # parent class.
-Arrange.__eq__ = composition_equals  # pyright: ignore[reportAttributeAccessIssue]
+Compose.__eq__ = composition_equals  # pyright: ignore[reportAttributeAccessIssue]
 Beside.__eq__ = composition_equals  # pyright: ignore[reportAttributeAccessIssue]
 Stack.__eq__ = composition_equals  # pyright: ignore[reportAttributeAccessIssue]

{plotnine-0.15.0a7 → plotnine-0.15.0a8}/tests/test_plot_composition.py

@@ -1,4 +1,4 @@
-from plotnine import element_text, facet_grid, facet_wrap, theme
+from plotnine import element_text, facet_grid, facet_wrap, theme, theme_gray
 from plotnine._utils.yippie import geom as g
 from plotnine._utils.yippie import legend, plot, rotate, tag
 
@@ -115,3 +115,39 @@ def test_complex_composition():
     )
     p = p1 | p2 | p3 / p4 / (p5 | p6)
     assert p == "complex_composition"
+
+
+def test_minus_operator():
+    p1 = plot.red
+    p2 = plot.green
+    p3 = plot.blue
+    p4 = plot.brown
+    p = (p1 / p2) - p3 - p4
+    assert p == "minus"
+
+
+def test_and_operator():
+    p1 = plot.red
+    p2 = plot.green
+    p3 = plot.blue
+    p4 = plot.brown
+    p = (p1 | p2 | (p3 / p4)) & theme_gray()
+    assert p == "and_operator"
+
+
+def test_mul_operator():
+    p1 = plot.red
+    p2 = plot.green
+    p3 = plot.blue
+    p4 = plot.brown
+    p = (p1 | p2 | (p3 / p4)) * theme_gray()
+    assert p == "mul_operator"
+
+
+def test_plus_operator():
+    p1 = plot.red
+    p2 = plot.green
+    p3 = plot.blue
+    p4 = plot.brown
+    p = (p1 | p2 | (p3 / p4)) + theme_gray()
+    assert p == "plus_operator"