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

plotnine/_utils/context.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from dataclasses import dataclass
 from typing import TYPE_CHECKING
 
 import pandas as pd
@@ -8,17 +9,40 @@ if TYPE_CHECKING:
     from typing_extensions import Self
 
     from plotnine import ggplot
+    from plotnine.composition import Compose
+
+
+def reopen(fig):
+    """
+    Reopen an MPL figure that has been closed with plt.close
+
+    When drawing compositions, plot_composition_context will nest
+    plot_context. In this case, plot_context may close an MPL figure
+    that belongs to composition. A closed figure cannot be shown with
+    plt.show, so for compositions compose.show (if called) will do nothing.
+    """
+    from matplotlib._pylab_helpers import Gcf
+
+    Gcf.set_active(fig.canvas.manager)
+
+
+def is_closed(fig) -> bool:
+    """
+    Return True if figure is closed
+    """
+    import matplotlib.pyplot as plt
+
+    return not plt.fignum_exists(fig.number)
 
 
 class plot_context:
     """
-    Context to setup the environment within with the plot is built
+    Context within which the plot is built
 
     Parameters
     ----------
     plot :
         ggplot object to be built within the context.
-        exits.
     show :
         Whether to show the plot.
     """
@@ -66,3 +90,55 @@ class plot_context:
 
         self.rc_context.__exit__(exc_type, exc_value, exc_traceback)
         self.pd_option_context.__exit__(exc_type, exc_value, exc_traceback)
+
+
+@dataclass
+class plot_composition_context:
+    """
+    Context within which a plot composition is built
+
+    Parameters
+    ----------
+    cmp :
+        composition object to be built within the context.
+    show :
+        Whether to show the plot.
+    """
+
+    cmp: Compose
+    show: bool
+
+    def __post_init__(self):
+        import matplotlib as mpl
+
+        # The dpi is needed when the figure is created, either as
+        # a parameter to plt.figure() or an rcParam.
+        # https://github.com/matplotlib/matplotlib/issues/24644
+        # When drawing the Composition, the dpi themeable is infective
+        # because it sets the rcParam after this figure is created.
+        rcParams = {"figure.dpi": self.cmp.last_plot.theme.getp("dpi")}
+        self._rc_context = mpl.rc_context(rcParams)
+
+    def __enter__(self) -> Self:
+        """
+        Enclose in matplolib & pandas environments
+        """
+        self._rc_context.__enter__()
+        return self
+
+    def __exit__(self, exc_type, exc_value, exc_traceback):
+        import matplotlib.pyplot as plt
+
+        if exc_type is None:
+            if self.show:
+                if is_closed(self.cmp.figure):
+                    reopen(self.cmp.figure)
+                plt.show()
+            else:
+                plt.close(self.cmp.figure)
+        else:
+            # There is an exception, close any figure
+            if hasattr(self.cmp, "figure"):
+                plt.close(self.cmp.figure)
+
+        self._rc_context.__exit__(exc_type, exc_value, exc_traceback)

plotnine/_utils/ipython.py

@@ -3,32 +3,24 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from typing import Callable, Literal, TypeAlias
-
     from IPython.core.interactiveshell import InteractiveShell
 
-    FigureFormat: TypeAlias = Literal[
-        "png", "retina", "jpeg", "jpg", "svg", "pdf"
-    ]
+    from ..typing import DisplayMetadata, FigureFormat, MimeBundle
 
 
-def get_ipython() -> "InteractiveShell":
+def get_ipython() -> "None | InteractiveShell":
     """
     Return running IPython instance or None
     """
     try:
         from IPython.core.getipython import get_ipython as _get_ipython
-    except ImportError as err:
-        raise type(err)("IPython is has not been installed.") from err
-
-    ip = _get_ipython()
-    if ip is None:
-        raise RuntimeError("Not running in a juptyer session.")
+    except ImportError:
+        return None
 
-    return ip
+    return _get_ipython()
 
 
-def is_inline_backend():
+def is_inline_backend() -> bool:
     """
     Return True if the inline_backend is on
 
@@ -36,47 +28,39 @@ def is_inline_backend():
     """
     import matplotlib as mpl
 
-    return "matplotlib_inline.backend_inline" in mpl.get_backend()
+    backend = mpl.get_backend()
+    return backend in ("inline", "module://matplotlib_inline.backend_inline")
 
 
-def get_display_function(
-    format: FigureFormat, figure_size_px: tuple[int, int]
-) -> Callable[[bytes], None]:
+def get_mimebundle(
+    b: bytes, format: FigureFormat, figure_size_px: tuple[int, int]
+) -> MimeBundle:
     """
-    Return a function that will display the plot image
+    Return a the display MIME bundle from image data
+
+    Parameters
+    ----------
+    format :
+        The figure format
+    figure_size_px :
+        The figure size in pixels (width, height)
     """
-    from IPython.display import (
-        SVG,
-        Image,
-        display_jpeg,
-        display_pdf,
-        display_png,
-        display_svg,
-    )
-
-    w, h = figure_size_px
-
-    def png(b: bytes):
-        display_png(Image(b, format="png", width=w, height=h))
-
-    def retina(b: bytes):
-        display_png(Image(b, format="png", retina=True))
-
-    def jpeg(b: bytes):
-        display_jpeg(Image(b, format="jpeg", width=w, height=h))
-
-    def svg(b: bytes):
-        display_svg(SVG(b))
-
-    def pdf(b: bytes):
-        display_pdf(b, raw=True)
 
     lookup = {
-        "png": png,
-        "retina": retina,
-        "jpeg": jpeg,
-        "jpg": jpeg,
-        "svg": svg,
-        "pdf": pdf,
+        "png": "image/png",
+        "retina": "image/png",
+        "jpeg": "image/jpeg",
+        "svg": "image/svg+xml",
+        "pdf": "application/pdf",
     }
-    return lookup[format]
+    mimetype = lookup[format]
+
+    metadata: dict[str, DisplayMetadata] = {}
+    w, h = figure_size_px
+    if format in ("png", "jpeg"):
+        metadata = {mimetype: {"width": w, "height": h}}
+    elif format == "retina":
+        # `retina=True` in IPython.display.Image just halves width/height
+        metadata = {mimetype: {"width": w // 2, "height": h // 2}}
+
+    return {mimetype: b}, metadata

plotnine/_utils/quarto.py

@@ -1,4 +1,6 @@
 import os
+import sys
+from functools import lru_cache
 
 
 def is_quarto_environment() -> bool:
@@ -31,3 +33,27 @@ def set_options_from_quarto():
     set_option("dpi", dpi)
     set_option("figure_size", figure_size)
     set_option("figure_format", figure_format)
+
+
+# We do not expect the contents the file stored in the QUARTO_EXECUTE_INFO
+# variable to change. We can can cache the output
+@lru_cache()
+def is_knitr_engine() -> bool:
+    """
+    Return True if knitr is executing the code
+    """
+
+    if filename := os.environ.get("QUARTO_EXECUTE_INFO"):  # Quarto >= 1.8.21
+        import json
+        from pathlib import Path
+
+        try:
+            info = json.loads(Path(filename).read_text())
+        except FileNotFoundError:
+            # NOTE: Remove this branch some time after quarto 1.9 is released
+            # https://github.com/quarto-dev/quarto-cli/issues/13613
+            return "rpytools" in sys.modules
+        return info["format"]["execute"].get("engine") == "knitr"
+    else:
+        # NOTE: Remove this branch some time after quarto 1.9 is released
+        return "rpytools" in sys.modules

plotnine/_utils/yippie.py

@@ -0,0 +1,115 @@
+"""
+Functions/class to quickly create plots for development and testing
+"""
+
+import pandas as pd
+
+from plotnine import (
+    aes,
+    element_blank,
+    element_rect,
+    element_text,
+    geom_col,
+    geom_point,
+    ggplot,
+    labs,
+    theme,
+)
+
+__all__ = ("geom", "legend", "plot", "rotate", "tag")
+
+
+class _Plot:
+    """
+    Create a plot
+    """
+
+    def __getattr__(self, color: str):
+        """
+        Create a blank plot with given background color
+        """
+        return (
+            ggplot()
+            + labs(
+                x="x-axis",
+                y="y-axis",
+                title=color.title(),
+            )
+            + theme(
+                figure_size=(8, 6),
+                text=element_text(color="black", size=11),
+                panel_background=element_rect(fill=color, size=1),
+                plot_background=element_rect(fill=color, alpha=0.2),
+                panel_border=element_rect(color="black"),
+                strip_background=element_rect(color="black"),
+                panel_grid=element_blank(),
+                legend_key_size=12,
+            )
+        )
+
+
+class _Geom:
+    """
+    Create some simple geoms
+    """
+
+    data = pd.DataFrame(
+        {
+            "cat": ["a", "b", "c", "d"],
+            "cat2": ["r", "r", "s", "s"],
+            "value": [1, 2, 3, 4],
+        }
+    )
+
+    @property
+    def points(self):
+        return geom_point(aes("cat", "value", color="cat"), self.data, size=2)
+
+    @property
+    def cols(self):
+        return geom_col(aes("cat", "value", fill="cat"), self.data)
+
+
+class _Legend:
+    """
+    Position Legends
+    """
+
+    @property
+    def left(self):
+        return theme(legend_position="left")
+
+    @property
+    def bottom(self):
+        return theme(legend_position="bottom")
+
+    @property
+    def right(self):
+        return theme(legend_position="right")
+
+    @property
+    def top(self):
+        return theme(legend_position="top")
+
+
+class _Rotate:
+    """
+    Rotate a text themeable
+    """
+
+    def __getattr__(self, name):
+        angle = 0 if name[-2:] == "_y" else 90
+        return theme(**{name: element_text(angle=angle)})  # pyright: ignore[reportArgumentType]
+
+
+def tag(s, position="topleft"):
+    """
+    Create a tag at a position
+    """
+    return [labs(tag=s), theme(plot_tag_position=position)]
+
+
+plot = _Plot()
+geom = _Geom()
+legend = _Legend()
+rotate = _Rotate()

plotnine/composition/__init__.py

@@ -0,0 +1,11 @@
+from ._beside import Beside
+from ._compose import Compose
+from ._plot_spacer import plot_spacer
+from ._stack import Stack
+
+__all__ = (
+    "Compose",
+    "Stack",
+    "Beside",
+    "plot_spacer",
+)

plotnine/composition/_beside.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from ._compose import Compose
+
+if TYPE_CHECKING:
+    from plotnine.ggplot import ggplot
+
+
+@dataclass(repr=False)
+class Beside(Compose):
+    """
+    Place plots or compositions side by side
+
+    **Usage**
+
+        plot | plot
+        plot | composition
+        composition | plot
+        composition | composition
+
+    Typically, you will use this class through the `|` operator.
+
+    See Also
+    --------
+    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
+    def nrow(self) -> int:
+        return 1
+
+    @property
+    def ncol(self) -> int:
+        return len(self)
+
+    def __or__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a column
+        """
+        # This is adjacent or i.e. (OR | rhs) so we collapse the
+        # operands into a single operation
+        return Beside([*self, rhs])
+
+    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+        """
+        Add rhs as a row
+        """
+        from ._stack import Stack
+
+        return Stack([self, rhs])