plotnine 0.15.0a4__tar.gz → 0.15.0a6__tar.gz

{plotnine-0.15.0a4/plotnine.egg-info → plotnine-0.15.0a6}/PKG-INFO

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

{plotnine-0.15.0a4 → plotnine-0.15.0a6}/doc/_quartodoc.yml

@@ -532,6 +532,15 @@ quartodoc:
         - coord_flip
         - coord_trans
 
+    - title: Composing Plots
+      package: plotnine.composition
+      contents:
+        - name: Arrange
+          include_attributes: false
+        - Stack
+        - Beside
+        - plot_spacer
+
     - title: Options
       desc: |
         When working interactively, some of the options make it convenient to
@@ -589,6 +598,7 @@ quartodoc:
         - msleep
         - mtcars
         - pageviews
+        - penguins
         - presidential
         - seals
         - txhousing

plotnine-0.15.0a6/doc/_renderer.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import re
+from functools import cached_property
+from pathlib import Path
+from textwrap import dedent
+from typing import TYPE_CHECKING
+
+from qrenderer import (
+    QRenderer,
+    RenderDoc,
+    RenderDocClass,
+    exclude_parameters,
+)
+from qrenderer._pandoc.inlines import shortcode
+from quartodoc.pandoc.blocks import Blocks, CodeBlock, Div, Header, Para
+from quartodoc.pandoc.components import Attr
+from quartodoc.pandoc.inlines import Code
+
+if TYPE_CHECKING:
+    from typing import Literal
+
+
+DOC_DIR = Path(__file__).parent
+REFERENCE_DIR = DOC_DIR / "reference"
+EXAMPLES_DIR = REFERENCE_DIR / "examples"
+
+# We expect the usage to contain an indented block of code
+usage_pattern = re.compile(
+    r"^\*\*Usage\*\*"
+    r"\s+"
+    r"(?P<indented_block>(?:"
+    r"^\s{4}[^\n]+\n*"
+    r")+)",
+    re.MULTILINE,
+)
+signature_pattern = re.compile(r"([a-zA-Z_]\w*)\s*\(([^)]*)\)")
+
+
+class Renderer(QRenderer):
+    pass
+
+
+exclude_parameters(
+    {
+        "plotnine.scale_color_hue": ("s", "color_space"),
+    }
+)
+
+summary_name_lookup = {
+    "Beside": f"{Code('|')} Beside",
+    "Stack": f"{Code('/')} Stack",
+}
+
+
+class _RenderDoc(RenderDoc):
+    def render_body(self):
+        body = super().render_body()
+        if self.kind == "type":
+            return body
+
+        notebook = EXAMPLES_DIR / f"{self.obj.name}.ipynb"
+        if not notebook.exists():
+            return body
+
+        relpath = notebook.relative_to(REFERENCE_DIR)
+        embed_notebook = shortcode("embed", f"{relpath}", echo="true")
+        header = Header(self.level + 1, "Examples")
+        return Blocks([body, header, embed_notebook])
+
+    @property
+    def summary_name(self):
+        name = super().summary_name
+        if name.startswith("options."):
+            # Until quartodoc makes it possible to use a tilde to use
+            # and objects name and not the qualified path, we have to
+            # create exceptions for all the qualified paths that we want
+            # to be short.
+            # Ref: https://github.com/machow/quartodoc/issues/230
+            name = name[8:]
+        elif name in summary_name_lookup:
+            name = summary_name_lookup[name]
+        return name
+
+
+class _RenderDocClass(RenderDocClass):
+    @cached_property
+    def _usage(self) -> tuple[str, Literal["signature", "code"]] | None:
+        """
+        Parse the docstring **Usage** block
+        """
+        docstring = self.obj.docstring.value if self.obj.docstring else ""
+        if m := usage_pattern.search(docstring):
+            content = dedent(m.group("indented_block")).strip()
+            return (
+                content,
+                "signature" if signature_pattern.match(content) else "code",
+            )
+        return None
+
+    def __str__(self):
+        content = super().__str__()
+        # R
+        if res := self._usage:
+            # Render the content of the usage as code and if it looks
+            # a signature mark it as one.
+            usage, kind = res
+            before, classes = Para("Usage"), ["doc-class", "doc-usage"]
+            if kind == "signature":
+                before = None
+                classes.insert(0, "doc-signature")
+            new = Div(
+                [before, CodeBlock(usage, Attr(classes=["python"]))],
+                Attr(classes=classes),
+            )
+            content = usage_pattern.sub(f"{new}\n", content)
+        return content
+
+    def render_signature(self):
+        # A "Usage" that is a function signature voids the original
+        # signature
+        if (res := self._usage) and res[1] == "signature":
+            return None
+        return super().render_signature()

{plotnine-0.15.0a4 → plotnine-0.15.0a6}/doc/changelog.qmd

@@ -161,6 +161,9 @@ title: Changelog
 - Fixed bug in [](:class:`~plotnine.geom_hline`) where you could not map the `yintercept`
   aesthetic to a discrete variable.
 
+- Fixed bug in all manual scales (`scale_*_manual`) where if you set `values`
+  to a `dict` then setting the breaks would lead to an error. {{< issue 949 >}}
+
 ## v0.14.5
 (2025-01-02)
 [![](https://zenodo.org/badge/DOI/10.5281/zenodo.14587381.svg)](https://doi.org/10.5281/zenodo.14587381)

{plotnine-0.15.0a4 → plotnine-0.15.0a6}/doc/plotnine.scss

@@ -35,6 +35,12 @@ $signature-border-color: tint-color($primary, 25%);
   margin-right: .5rem;
 }
 
+.doc-usage:not(.doc-signature) > p {
+  margin-bottom: -1rem;
+  color: $gray-600;
+  font-size: 0.95rem;
+}
+
 /*-- scss:functions --*/
 
 /*-- scss:uses --*/

{plotnine-0.15.0a4 → plotnine-0.15.0a6}/plotnine/_mpl/layout_manager/_engine.py

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

{plotnine-0.15.0a4 → plotnine-0.15.0a6}/plotnine/_mpl/layout_manager/_layout_tree.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, cast
 
 import numpy as np
 
-from plotnine.plot_composition import OR
+from plotnine.composition import Beside
 
 from ._spaces import LayoutSpaces
 
@@ -16,7 +16,7 @@ if TYPE_CHECKING:
 
     from plotnine import ggplot
     from plotnine._mpl.gridspec import p9GridSpec
-    from plotnine.plot_composition import Compose
+    from plotnine.composition import Arrange
 
 
 @dataclass
@@ -82,7 +82,7 @@ class LayoutTree:
 
     @staticmethod
     def create(
-        cmp: Compose,
+        cmp: Arrange,
         lookup_spaces: dict[ggplot, LayoutSpaces],
     ) -> LayoutTree:
         """
@@ -109,7 +109,7 @@ class LayoutTree:
             else:
                 nodes.append(LayoutTree.create(item, lookup_spaces))
 
-        if isinstance(cmp, OR):
+        if isinstance(cmp, Beside):
             return ColumnsTree(cmp.gridspec, nodes)
         else:
             return RowsTree(cmp.gridspec, nodes)

{plotnine-0.15.0a4 → plotnine-0.15.0a6}/plotnine/_utils/__init__.py

@@ -1194,3 +1194,16 @@ def va_as_float(va: VerticalJustification | float) -> float:
         "center_baseline": 0.5,
     }
     return lookup[va] if isinstance(va, str) else va
+
+
+def has_alpha_channel(c: str | tuple) -> bool:
+    """
+    Return True if c a color with an alpha value
+
+    Either a 9 character hex string e.g. #AABBCC88 or
+    an RGBA tuple e.g. (.6, .7, .8, .5)
+    """
+    if isinstance(c, str):
+        return c.startswith("#") and len(c) == 9
+    else:
+        return color_utils.is_color_tuple(c) and len(c) == 4

plotnine-0.15.0a6/plotnine/composition/__init__.py

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

plotnine-0.15.0a4/plotnine/plot_composition/_compose.py → plotnine-0.15.0a6/plotnine/composition/_arrange.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import abc
 from copy import deepcopy
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from io import BytesIO
 from typing import TYPE_CHECKING
 
@@ -24,9 +24,15 @@ if TYPE_CHECKING:
     from plotnine.ggplot import PlotAddable, ggplot
 
 
-class Compose:
+@dataclass
+class Arrange:
     """
-    Arrange two or more plots
+    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.
 
     Parameters
     ----------
@@ -34,27 +40,26 @@ class Compose:
         The objects to be put together (composed).
     """
 
-    def __init__(self, operands: list[ggplot | Compose]):
-        self.operands = operands
+    operands: list[ggplot | Arrange]
 
-        # These are created in the _create_figure method
-        self.figure: Figure
-        self.plotspecs: list[plotspec]
-        self.gridspec: p9GridSpec
+    # These are created in the _create_figure method
+    figure: Figure = field(init=False, repr=False)
+    plotspecs: list[plotspec] = field(init=False, repr=False)
+    gridspec: p9GridSpec = field(init=False, repr=False)
 
     @abc.abstractmethod
-    def __or__(self, rhs: ggplot | Compose) -> Compose:
+    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
         """
         Add rhs as a column
         """
 
     @abc.abstractmethod
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
+    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
         """
         Add rhs as a row
         """
 
-    def __add__(self, rhs: ggplot | Compose | PlotAddable) -> Compose:
+    def __add__(self, rhs: ggplot | Arrange | PlotAddable) -> Arrange:
         """
         Add rhs to the composition
 
@@ -65,13 +70,13 @@ class Compose:
         """
         from plotnine import ggplot
 
-        if not isinstance(rhs, (ggplot, Compose)):
+        if not isinstance(rhs, (ggplot, Arrange)):
             cmp = deepcopy(self)
             cmp.last_plot = cmp.last_plot + rhs
             return cmp
         return self.__class__([*self, rhs])
 
-    def __sub__(self, rhs: ggplot | Compose) -> Compose:
+    def __sub__(self, rhs: ggplot | Arrange) -> Arrange:
         """
         Add the rhs besides the composition
 
@@ -82,7 +87,7 @@ class Compose:
         """
         return self.__class__([self, rhs])
 
-    def __and__(self, rhs: PlotAddable) -> Compose:
+    def __and__(self, rhs: PlotAddable) -> Arrange:
         """
         Add rhs to all plots in the composition
 
@@ -93,9 +98,9 @@ class Compose:
         """
         self = deepcopy(self)
 
-        def add_other(op: Compose):
+        def add_other(op: Arrange):
             for item in op:
-                if isinstance(item, Compose):
+                if isinstance(item, Arrange):
                     add_other(item)
                 else:
                     item += rhs
@@ -103,7 +108,7 @@ class Compose:
         add_other(self)
         return self
 
-    def __mul__(self, rhs: PlotAddable) -> Compose:
+    def __mul__(self, rhs: PlotAddable) -> Arrange:
         """
         Add rhs to the outermost nesting level of the composition
 
@@ -127,7 +132,7 @@ class Compose:
         """
         return len(self.operands)
 
-    def __iter__(self) -> Iterator[ggplot | Compose]:
+    def __iter__(self) -> Iterator[ggplot | Arrange]:
         """
         Return an iterable of all the operands
         """
@@ -227,7 +232,7 @@ class Compose:
         from plotnine._mpl.gridspec import p9GridSpec
 
         def _make_plotspecs(
-            cmp: Compose, parent_gridspec: p9GridSpec | None
+            cmp: Arrange, parent_gridspec: p9GridSpec | None
         ) -> Generator[plotspec]:
             """
             Return the plot specification for each subplot in the composition
@@ -289,7 +294,7 @@ class Compose:
 
     def draw(self, *, show: bool = False) -> Figure:
         """
-        Render the composed plots
+        Render the arranged plots
 
         Parameters
         ----------
@@ -315,9 +320,15 @@ class Compose:
             )
         return figure
 
-    def save(self, filename: str | Path | BytesIO, format: str | None = None):
+    def save(
+        self,
+        filename: str | Path | BytesIO,
+        format: str | None = None,
+        dpi: int | None = None,
+        **kwargs,
+    ):
         """
-        Save a Compose object as an image file
+        Save a composition as an image file
 
         Parameters
         ----------
@@ -326,14 +337,25 @@ class Compose:
         format :
             Image format to use, automatically extract from
             file name extension.
-        """
-        figure = self.draw()
+        dpi :
+            DPI to use for raster graphics. If None, defaults to using
+            the `dpi` of theme to the first plot.
+        kwargs :
+            These are ignored. Here to "softly" match the API of
+            `ggplot.save()`.
+        """
+        from plotnine import theme
+
+        # To set the dpi, we only need to change the dpi of
+        # the last plot and theme gets added to the last plot
+        plot = (self + theme(dpi=dpi)) if dpi else self
+        figure = plot.draw()
         figure.savefig(filename, format=format)
 
 
 @dataclass
 class plot_composition_context:
-    cmp: Compose
+    cmp: Arrange
     show: bool
 
     def __post_init__(self):
@@ -368,95 +390,3 @@ class plot_composition_context:
                 plt.close(self.cmp.figure)
 
         self._rc_context.__exit__(exc_type, exc_value, exc_traceback)
-
-
-class OR(Compose):
-    """
-    Compose by adding a column
-    """
-
-    @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 OR([*self, rhs])
-
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a row
-        """
-        return DIV([self, rhs])
-
-
-class DIV(Compose):
-    """
-    Compose by adding a row
-    """
-
-    @property
-    def nrow(self) -> int:
-        return len(self)
-
-    @property
-    def ncol(self) -> int:
-        return 1
-
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a row
-        """
-        # This is an adjacent div i.e. (DIV | rhs) so we collapse the
-        # operands into a single operation
-        return DIV([*self, rhs])
-
-    def __or__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a column
-        """
-        return OR([self, rhs])
-
-
-class ADD(Compose):
-    """
-    Compose by adding
-    """
-
-    @property
-    def nrow(self) -> int:
-        from plotnine.facets.facet_wrap import wrap_dims
-
-        return wrap_dims(len(self))[0]
-
-    @property
-    def ncol(self) -> int:
-        from plotnine.facets.facet_wrap import wrap_dims
-
-        return wrap_dims(len(self))[1]
-
-    def __or__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a column
-        """
-        return OR([self, rhs])
-
-    def __truediv__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a row
-        """
-        return DIV([self, rhs])
-
-    def __sub__(self, rhs: ggplot | Compose) -> Compose:
-        """
-        Add rhs as a column
-        """
-        return OR([self, rhs])

plotnine-0.15.0a6/plotnine/composition/_beside.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._arrange import Arrange
+
+if TYPE_CHECKING:
+    from plotnine.ggplot import ggplot
+
+
+class Beside(Arrange):
+    """
+    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.
+    """
+
+    @property
+    def nrow(self) -> int:
+        return 1
+
+    @property
+    def ncol(self) -> int:
+        return len(self)
+
+    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+        """
+        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 | Arrange) -> Arrange:
+        """
+        Add rhs as a row
+        """
+        from ._stack import Stack
+
+        return Stack([self, rhs])

plotnine-0.15.0a6/plotnine/composition/_plot_spacer.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+from copy import deepcopy
+
+from plotnine import element_rect, ggplot, theme, theme_void
+
+
+class plot_spacer(ggplot):
+    """
+    Blank area as wide or as tall as a plot
+
+    Parameters
+    ----------
+    fill :
+        Background color. The default is a transparent area, but it
+        can be changed through this parameter.
+
+        The color can also be modified by adding a [](`~plotnine.theme`)
+        and setting the [](`~plotnine.themes.themeable.plot_background`).
+    """
+
+    def __init__(
+        self,
+        fill: (
+            str
+            | tuple[float, float, float]
+            | tuple[float, float, float, float]
+            | None
+        ) = None,
+    ):
+        super().__init__()
+        self.theme = theme_void()
+        if fill:
+            self.theme += theme(plot_background=element_rect(fill=fill))
+
+    def __add__(self, rhs) -> plot_spacer:
+        """
+        Add to spacer
+
+        All added objects are no ops except the `plot_background` in
+        in a theme.
+        """
+        self = deepcopy(self)
+        if isinstance(rhs, theme):
+            fill = rhs.getp(("plot_background", "facecolor"))
+            self.theme += theme(
+                plot_background=element_rect(fill=fill),
+            )
+        return self

plotnine-0.15.0a6/plotnine/composition/_stack.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from ._arrange import Arrange
+
+if TYPE_CHECKING:
+    from plotnine.ggplot import ggplot
+
+
+class Stack(Arrange):
+    """
+    Place plots or compositions on top of each other
+
+    **Usage**
+
+        plot / plot
+        plot / composition
+        composition / plot
+        composition / composition
+
+    Typically, you will use this class through the `/` operator.
+    """
+
+    @property
+    def nrow(self) -> int:
+        return len(self)
+
+    @property
+    def ncol(self) -> int:
+        return 1
+
+    def __truediv__(self, rhs: ggplot | Arrange) -> Arrange:
+        """
+        Add rhs as a row
+        """
+        # This is an adjacent div i.e. (DIV | rhs) so we collapse the
+        # operands into a single operation
+        return Stack([*self, rhs])
+
+    def __or__(self, rhs: ggplot | Arrange) -> Arrange:
+        """
+        Add rhs as a column
+        """
+        from ._beside import Beside
+
+        return Beside([self, rhs])