plotnine 0.15.0.dev3__py3-none-any.whl → 0.15.2__py3-none-any.whl

plotnine/ggplot.py

@@ -13,7 +13,6 @@ from typing import (
     Iterable,
     Optional,
     cast,
-    overload,
 )
 from warnings import warn
 
@@ -26,20 +25,20 @@ from ._utils import (
 )
 from ._utils.context import plot_context
 from ._utils.ipython import (
-    get_display_function,
     get_ipython,
+    get_mimebundle,
     is_inline_backend,
 )
-from ._utils.quarto import is_quarto_environment
+from ._utils.quarto import is_knitr_engine, is_quarto_environment
 from .coords import coord_cartesian
 from .exceptions import PlotnineError, PlotnineWarning
 from .facets import facet_null
 from .facets.layout import Layout
 from .geoms.geom_blank import geom_blank
 from .guides.guides import guides
-from .iapi import mpl_save_view
+from .iapi import labels_view, mpl_save_view
 from .layer import Layers
-from .mapping.aes import aes, make_labels
+from .mapping.aes import aes
 from .options import get_option
 from .scales.scales import Scales
 from .themes.theme import theme, theme_get
@@ -53,18 +52,17 @@ if TYPE_CHECKING:
 
     from plotnine import watermark
     from plotnine._mpl.gridspec import p9GridSpec
+    from plotnine.composition import Compose
     from plotnine.coords.coord import coord
     from plotnine.facets.facet import facet
-    from plotnine.layer import layer
-    from plotnine.plot_composition import Compose
-    from plotnine.typing import DataLike
+    from plotnine.typing import DataLike, FigureFormat, MimeBundle
 
     class PlotAddable(Protocol):
         """
         Object that can be added to a ggplot object
         """
 
-        def __radd__(self, plot: ggplot) -> ggplot:
+        def __radd__(self, other: ggplot) -> ggplot:
             """
             Add to ggplot object
 
@@ -119,7 +117,7 @@ class ggplot:
         self.data = data
         self.mapping = mapping if mapping is not None else aes()
         self.facet: facet = facet_null()
-        self.labels = make_labels(self.mapping)
+        self.labels = labels_view()
         self.layers = Layers()
         self.guides = guides()
         self.scales = Scales()
@@ -139,21 +137,47 @@ class ggplot:
         w, h = self.theme._figure_size_px
         return f"<ggplot: ({w} x {h})>"
 
-    def _ipython_display_(self):
+    def __repr__(self):
+        # knitr relies on __repr__ to automatically print the last object
+        # in a cell.
+        if is_knitr_engine():
+            self.show()
+            return ""
+        return super().__repr__()
+
+    def _repr_mimebundle_(self, include=None, exclude=None) -> MimeBundle:
         """
-        Display plot in the output of the cell
+        Return dynamic MIME bundle for plot display
+
+        This method is called when a ggplot object is the last in the cell.
 
-        This method will always be called when a ggplot object is the
-        last in the cell.
+        Notes
+        -----
+        - https://ipython.readthedocs.io/en/stable/config/integrating.html
         """
-        self._display()
+        ip = get_ipython()
+        format: FigureFormat = (
+            get_option("figure_format")
+            or (ip and ip.config.InlineBackend.get("figure_format"))
+            or "retina"
+        )
+
+        # While jpegs can be displayed as retina, we restrict the output
+        # of "retina" to png
+        if format == "retina":
+            self = copy(self)
+            self.theme = self.theme.to_retina()
+
+        buf = BytesIO()
+        self.save(buf, "png" if format == "retina" else format, verbose=False)
+        figure_size_px = self.theme._figure_size_px
+        return get_mimebundle(buf.getvalue(), format, figure_size_px)
 
     def show(self):
         """
         Show plot using the matplotlib backend set by the user
 
-        Users should prefer this method instead of printing or repring
-        the object.
+        This function is called for its side-effects.
         """
         # Prevent against any modifications to the users
         # ggplot object. Do the copy here as we may/may not
@@ -161,37 +185,13 @@ class ggplot:
         self = deepcopy(self)
 
         if is_inline_backend() or is_quarto_environment():
-            # Take charge of the display because we have to make
-            # adjustments for retina output.
-            self._display()
+            from IPython.display import display
+
+            data, metadata = self._repr_mimebundle_()
+            display(data, metadata=metadata, raw=True)
         else:
             self.draw(show=True)
 
-    def _display(self):
-        """
-        Display plot in the cells output
-
-        This function is called for its side-effects.
-
-        It plots the plot to an io buffer, then uses ipython display
-        methods to show the result
-        """
-        ip = get_ipython()
-        format = get_option("figure_format") or ip.config.InlineBackend.get(
-            "figure_format", "retina"
-        )
-        # While jpegs can be displayed as retina, we restrict the output
-        # of "retina" to png
-        if format == "retina":
-            self = copy(self)
-            self.theme = self.theme.to_retina()
-
-        buf = BytesIO()
-        self.save(buf, "png" if format == "retina" else format, verbose=False)
-        figure_size_px = self.theme._figure_size_px
-        display_func = get_display_function(format, figure_size_px)
-        display_func(buf.getvalue())
-
     def __deepcopy__(self, memo: dict[Any, Any]) -> ggplot:
         """
         Deep copy without copying the dataframe and environment
@@ -230,18 +230,10 @@ class ggplot:
             other.__radd__(self)
         return self
 
-    @overload
-    def __add__(
-        self, rhs: PlotAddable | list[PlotAddable] | None
-    ) -> ggplot: ...
-
-    @overload
-    def __add__(self, rhs: ggplot | Compose) -> Compose: ...
-
     def __add__(
         self,
-        rhs: PlotAddable | list[PlotAddable] | None | ggplot | Compose,
-    ) -> ggplot | Compose:
+        rhs: PlotAddable | list[PlotAddable] | None,
+    ) -> ggplot:
         """
         Add to ggplot
 
@@ -251,11 +243,6 @@ class ggplot:
             Either an object that knows how to "radd"
             itself to a ggplot, or a list of such objects.
         """
-        from .plot_composition import ADD, Compose
-
-        if isinstance(rhs, (ggplot, Compose)):
-            return ADD([self, rhs])
-
         self = deepcopy(self)
         return self.__iadd__(rhs)
 
@@ -263,25 +250,25 @@ class ggplot:
         """
         Compose 2 plots columnwise
         """
-        from .plot_composition import OR
+        from .composition import Beside
 
-        return OR([self, rhs])
+        return Beside([self, rhs])
 
     def __truediv__(self, rhs: ggplot | Compose) -> Compose:
         """
         Compose 2 plots rowwise
         """
-        from .plot_composition import DIV
+        from .composition import Stack
 
-        return DIV([self, rhs])
+        return Stack([self, rhs])
 
     def __sub__(self, rhs: ggplot | Compose) -> Compose:
         """
         Compose 2 plots columnwise
         """
-        from .plot_composition import OR
+        from .composition import Beside
 
-        return OR([self, rhs])
+        return Beside([self, rhs])
 
     def __rrshift__(self, other: DataLike) -> ggplot:
         """
@@ -315,10 +302,7 @@ class ggplot:
         from ._mpl.layout_manager import PlotnineLayoutEngine
 
         with plot_context(self, show=show):
-            if not hasattr(self, "figure"):
-                self._create_figure()
-            figure = self.figure
-
+            figure = self._setup()
             self._build()
 
             # setup
@@ -341,6 +325,16 @@ class ggplot:
 
         return figure
 
+    def _setup(self) -> Figure:
+        """
+        Setup this instance for the building process
+        """
+        if not hasattr(self, "figure"):
+            self._create_figure()
+
+        self.labels.add_defaults(self.mapping.labels)
+        return self.figure
+
     def _create_figure(self):
         """
         Create gridspec for the panels
@@ -562,21 +556,6 @@ class ggplot:
         hash_token = abs(self.__hash__())
         return Path(f"plotnine-save-{hash_token}.{ext}")
 
-    def _update_labels(self, layer: layer):
-        """
-        Update label data for the ggplot
-
-        Parameters
-        ----------
-        layer : layer
-            New layer that has just been added to the ggplot
-            object.
-        """
-        mapping = make_labels(layer.mapping)
-        default = make_labels(layer.stat.DEFAULT_AES)
-        mapping.add_defaults(default)
-        self.labels.add_defaults(mapping)
-
     def save_helper(
         self: ggplot,
         filename: Optional[str | Path | BytesIO] = None,

plotnine/guides/guide.py

@@ -23,13 +23,13 @@ if TYPE_CHECKING:
     from plotnine.typing import (
         LegendPosition,
         Orientation,
-        SidePosition,
+        Side,
     )
 
     from .guides import GuidesElements
 
     AlignDict: TypeAlias = dict[
-        Literal["ha", "va"], dict[tuple[Orientation, SidePosition], str]
+        Literal["ha", "va"], dict[tuple[Orientation, Side], str]
     ]
 
 
@@ -122,10 +122,7 @@ class guide(ABC, metaclass=Register):
     @property
     def _resolved_position_justification(
         self,
-    ) -> (
-        tuple[SidePosition, float]
-        | tuple[tuple[float, float], tuple[float, float]]
-    ):
+    ) -> tuple[Side, float] | tuple[tuple[float, float], tuple[float, float]]:
         """
         Return the final position & justification to draw the guide
         """
@@ -213,7 +210,7 @@ class GuideElements:
         )
 
     @cached_property
-    def text_position(self) -> SidePosition:
+    def text_position(self) -> Side:
         raise NotImplementedError
 
     @cached_property
@@ -225,7 +222,7 @@ class GuideElements:
         return getattr(_margin, _loc)
 
     @cached_property
-    def title_position(self) -> SidePosition:
+    def title_position(self) -> Side:
         if not (pos := self.theme.getp("legend_title_position")):
             pos = "top" if self.is_vertical else "left"
         return pos
@@ -244,7 +241,7 @@ class GuideElements:
         return direction
 
     @cached_property
-    def position(self) -> SidePosition | tuple[float, float]:
+    def position(self) -> Side | tuple[float, float]:
         if (guide_pos := self.guide.position) == "inside":
             guide_pos = self._position_inside
 
@@ -256,7 +253,7 @@ class GuideElements:
         return pos
 
     @cached_property
-    def _position_inside(self) -> SidePosition | tuple[float, float]:
+    def _position_inside(self) -> Side | tuple[float, float]:
         pos = self.theme.getp("legend_position_inside")
         if isinstance(pos, tuple):
             return pos

plotnine/guides/guide_colorbar.py

@@ -27,7 +27,7 @@ if TYPE_CHECKING:
 
     from plotnine import theme
     from plotnine.scales.scale import scale
-    from plotnine.typing import SidePosition
+    from plotnine.typing import Side
 
 
 @dataclass
@@ -242,7 +242,7 @@ class guide_colorbar(guide):
         targets.legend_frame = frame
 
         # title + colorbar(with labels)
-        lookup: dict[SidePosition, tuple[type[PackerBase], slice]] = {
+        lookup: dict[Side, tuple[type[PackerBase], slice]] = {
             "right": (HPacker, reverse),
             "left": (HPacker, obverse),
             "bottom": (VPacker, reverse),
@@ -495,7 +495,7 @@ class GuideElementsColorbar(GuideElements):
         )
 
     @cached_property
-    def text_position(self) -> SidePosition:
+    def text_position(self) -> Side:
         if not (position := self.theme.getp("legend_text_position")):
             position = "right" if self.is_vertical else "bottom"
 

plotnine/guides/guide_legend.py

@@ -25,7 +25,7 @@ if TYPE_CHECKING:
 
     from plotnine.geoms.geom import geom
     from plotnine.layer import layer
-    from plotnine.typing import SidePosition
+    from plotnine.typing import Side
 
 
 # See guides.py for terminology
@@ -281,7 +281,7 @@ class guide_legend(guide):
         targets.legend_key = drawings
 
         # Match Drawings with labels to create the entries
-        lookup: dict[SidePosition, tuple[type[PackerBase], slice]] = {
+        lookup: dict[Side, tuple[type[PackerBase], slice]] = {
             "right": (HPacker, reverse),
             "left": (HPacker, obverse),
             "bottom": (VPacker, reverse),
@@ -380,7 +380,7 @@ class GuideElementsLegend(GuideElements):
         )
 
     @cached_property
-    def text_position(self) -> SidePosition:
+    def text_position(self) -> Side:
         if not (pos := self.theme.getp("legend_text_position")):
             pos = "right"
         return pos

plotnine/guides/guides.py

@@ -35,7 +35,7 @@ if TYPE_CHECKING:
         NoGuide,
         Orientation,
         ScaledAestheticsName,
-        SidePosition,
+        Side,
         TextJustification,
     )
 
@@ -104,7 +104,7 @@ class guides:
             raise ValueError("Got a guide for color and colour, choose one.")
         rename_aesthetics(self)
 
-    def __radd__(self, plot: ggplot):
+    def __radd__(self, other: ggplot):
         """
         Add guides to the plot
 
@@ -120,9 +120,9 @@ class guides:
         """
         for f in fields(self):
             if (g := getattr(self, f.name)) is not None:
-                setattr(plot.guides, f.name, g)
+                setattr(other.guides, f.name, g)
 
-        return plot
+        return other
 
     def _build(self) -> Sequence[guide]:
         """
@@ -326,7 +326,7 @@ class guides:
 
         # Group together guides for each position
         groups: dict[
-            tuple[SidePosition, float]
+            tuple[Side, float]
             | tuple[tuple[float, float], tuple[float, float]],
             list[PackerBase],
         ] = defaultdict(list)
@@ -369,7 +369,7 @@ class guides:
         # place the guides according to the guide.order
         default = max(g.order for g in gdefs) + 1
         orders = [default if g.order == 0 else g.order for g in gdefs]
-        idx: list[int] = list(np.argsort(orders))
+        idx = cast("Sequence[int]", np.argsort(orders))
         gdefs = [gdefs[i] for i in idx]
 
         # Draw each guide into a box

plotnine/helpers.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from typing import Sequence
+
+    from plotnine import ggplot
+
+__all__ = ("get_aesthetic_limits",)
+
+
+def get_aesthetic_limits(
+    plot: ggplot,
+    ae: str,
+) -> (
+    tuple[float, float]
+    | Sequence[str]
+    | list[tuple[float]]
+    | list[Sequence[str]]
+):
+    """
+    Get the limits of an aesthetic
+
+    These are the limits before they are expanded.
+
+    Parameters
+    ----------
+    plot :
+        ggplot object
+
+    ae :
+        Name of aesthetic
+
+    Returns
+    -------
+    out :
+        The limits of the aesthetic. If the plot is facetted, (has many
+        panels), it is a sequence of limits, one for each panel.
+    """
+    plot = deepcopy(plot)
+    plot._build()
+    limits = [
+        getattr(panel, ae).limits
+        for panel in plot._build_objs.layout.panel_params
+    ]
+
+    return limits[0] if len(limits) == 1 else limits

plotnine/iapi.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import itertools
 from copy import copy
 from dataclasses import dataclass, field, fields
+from functools import cached_property
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -19,6 +20,7 @@ if TYPE_CHECKING:
     from matplotlib.figure import Figure
 
     from plotnine.scales.scale import scale
+    from plotnine.themes.elements.margin import margin
     from plotnine.typing import (
         CoordRange,
         FloatArrayLike,
@@ -231,13 +233,27 @@ class strip_draw_info:
     Information required to draw strips
     """
 
-    x: float
-    y: float
+    bg_x: float
+    """Left of the strip background in transAxes"""
+
+    bg_y: float
+    """Bottom of the strip background in transAxes"""
+
     ha: HorizontalJustification | float
+    """Horizontal justification of strip text within the background"""
+
     va: VerticalJustification | float
-    box_width: float
-    box_height: float
-    strip_text_margin: float
+    """Vertical justification of strip text within the background"""
+
+    bg_width: float
+    """Width of the strip background in transAxes"""
+
+    bg_height: float
+    """Height of the strip background in transAxes"""
+
+    margin: margin
+    """Strip text margin with the units in lines"""
+
     strip_align: float
     position: StripPosition
     label: str
@@ -245,6 +261,13 @@ class strip_draw_info:
     rotation: float
     layout: layout_details
 
+    @cached_property
+    def is_oneline(self) -> bool:
+        """
+        Whether the strip text is a single line
+        """
+        return len(self.label.split("\n")) == 1
+
 
 @dataclass
 class strip_label_details:

plotnine/labels.py

@@ -103,12 +103,12 @@ class labs:
         }
         self.labels = labels_view(**rename_aesthetics(kwargs))
 
-    def __radd__(self, plot: p9.ggplot) -> p9.ggplot:
+    def __radd__(self, other: p9.ggplot) -> p9.ggplot:
         """
         Add labels to ggplot object
         """
-        plot.labels.update(self.labels)
-        return plot
+        other.labels.update(self.labels)
+        return other
 
 
 class xlab(labs):