plotnine 0.14.4__py3-none-any.whl → 0.15.0.dev1__py3-none-any.whl

plotnine/themes/elements/element_text.py

@@ -8,10 +8,10 @@ from contextlib import suppress
 from typing import TYPE_CHECKING
 
 from .element_base import element_base
-from .margin import Margin
+from .margin import margin as Margin
 
 if TYPE_CHECKING:
-    from typing import Any, Literal, Optional, Sequence
+    from typing import Any, Literal, Sequence
 
     from plotnine import theme
 
@@ -56,7 +56,7 @@ class element_text(element_base):
         Margin around the text. The keys are
         `t`, `b`, `l`, `r` and `units`.
         The `tblr` keys are floats.
-        The `units` is one of `pt`, `lines` or `in`.
+        The `unit` is one of `pt`, `lines` or `in`.
         Not all text themeables support margin parameters and other
         than the `units`, only some of the other keys may apply.
     kwargs :
@@ -71,10 +71,10 @@ class element_text(element_base):
 
     def __init__(
         self,
-        family: Optional[str | list[str]] = None,
-        style: Optional[str | Sequence[str]] = None,
-        weight: Optional[int | str | Sequence[int | str]] = None,
-        color: Optional[
+        family: str | list[str] | None = None,
+        style: str | Sequence[str] | None = None,
+        weight: int | str | Sequence[int | str] | None = None,
+        color: (
             str
             | tuple[float, float, float]
             | tuple[float, float, float, float]
@@ -83,22 +83,25 @@ class element_text(element_base):
                 | tuple[float, float, float]
                 | tuple[float, float, float, float]
             ]
-        ] = None,
-        size: Optional[float | Sequence[float]] = None,
-        ha: Optional[Literal["center", "left", "right"] | float] = None,
-        va: Optional[
+            | None
+        ) = None,
+        size: float | Sequence[float] | None = None,
+        ha: Literal["center", "left", "right"] | float | None = None,
+        va: (
             Literal["center", "top", "bottom", "baseline", "center_baseline"]
             | float
-        ] = None,
-        ma: Optional[Literal["center", "left", "right"] | float] = None,
-        rotation: Optional[
+            | None
+        ) = None,
+        ma: Literal["center", "left", "right"] | float | None = None,
+        rotation: (
             Literal["vertical", "horizontal"]
             | float
             | Sequence[Literal["vertical", "horizontal"]]
             | Sequence[float]
-        ] = None,
-        linespacing: Optional[float] = None,
-        backgroundcolor: Optional[
+            | None
+        ) = None,
+        linespacing: float | None = None,
+        backgroundcolor: (
             str
             | tuple[float, float, float]
             | tuple[float, float, float, float]
@@ -107,10 +110,11 @@ class element_text(element_base):
                 | tuple[float, float, float]
                 | tuple[float, float, float, float]
             ]
-        ] = None,
-        margin: Optional[
-            dict[Literal["t", "b", "l", "r", "units"], Any]
-        ] = None,
+            | None
+        ) = None,
+        margin: (
+            Margin | dict[Literal["t", "b", "l", "r", "unit"], Any] | None
+        ) = None,
         rotation_mode: Literal["default", "anchor"] | None = None,
         **kwargs: Any,
     ):
@@ -139,8 +143,15 @@ class element_text(element_base):
 
         super().__init__()
         self.properties.update(**kwargs)
+
         if margin is not None:
-            self.properties["margin"] = Margin(self, **margin)
+            if isinstance(margin, dict):
+                if "units" in margin:
+                    # for backward compatibility
+                    margin["unit"] = margin.pop("units")  # pyright: ignore[reportArgumentType]
+                margin = Margin(**margin)
+
+            self.properties["margin"] = margin
 
         # Use the parameters that have been set
         names = (
@@ -166,8 +177,7 @@ class element_text(element_base):
         Setup the theme_element before drawing
         """
         if m := self.properties.get("margin"):
-            m.theme = theme
-            m.themeable_name = themeable_name
+            m = m.setup(theme, themeable_name)
 
     def _translate_hjust(
         self, just: float

plotnine/themes/elements/margin.py

@@ -4,7 +4,9 @@ Theme elements used to decorate the graph.
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from contextlib import suppress
+from copy import copy
+from dataclasses import dataclass, field
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
@@ -12,80 +14,91 @@ if TYPE_CHECKING:
 
     from plotnine import theme
 
-    from .element_base import element_base
-
 
 @dataclass
-class Margin:
-    element: element_base
+class margin:
     t: float = 0
+    r: float = 0
     b: float = 0
     l: float = 0
-    r: float = 0
-    units: Literal["pt", "in", "lines", "fig"] = "pt"
-
-    def __post_init__(self):
-        self.theme: theme
-        self.themeable_name: str
-
-        if self.units in ("pts", "points", "px", "pixels"):
-            self.units = "pt"
-        elif self.units in ("in", "inch", "inches"):
-            self.units = "in"
-        elif self.units in ("line", "lines"):
-            self.units = "lines"
-
-    def __eq__(self, other: object) -> bool:
-        def _size(m: Margin):
-            return m.element.properties.get("size")
-
-        return other is self or (
-            isinstance(other, type(self))
-            and other.t == self.t
-            and other.b == self.b
-            and other.l == self.l
-            and other.r == self.r
-            and other.units == self.units
-            and _size(other) == _size(self)
-        )
-
-    def get_as(
-        self,
-        loc: Literal["t", "b", "l", "r"],
-        units: Literal["pt", "in", "lines", "fig"] = "pt",
-    ) -> float:
+    unit: Literal["pt", "in", "lines", "fig"] = "pt"
+
+    # These are set by the themeable when it is applied
+    fontsize: float = field(init=False, default=0)
+    figure_size: tuple[float, float] = field(init=False, default=(0, 0))
+
+    def setup(self, theme: theme, themeable_name: str):
+        self.fontsize = theme.getp((themeable_name, "size"), 11)
+        self.figure_size = theme.getp("figure_size")
+
+    @property
+    def pt(self) -> margin:
+        """
+        Return margin in points
+        """
+        return self.to("pt")
+
+    @property
+    def inch(self) -> margin:
+        """
+        Return margin in inches
+        """
+        return self.to("in")
+
+    @property
+    def lines(self) -> margin:
+        """
+        Return margin in lines units
+        """
+        return self.to("lines")
+
+    @property
+    def fig(self) -> margin:
+        """
+        Return margin in figure units
         """
-        Return key in given units
+        return self.to("fig")
+
+    def to(self, unit: Literal["pt", "in", "lines", "fig"]) -> margin:
         """
+        Return margin in request unit
+        """
+        m = copy(self)
+        if self.unit == unit:
+            return m
+
+        conversion = f"{self.unit}-{unit}"
+        W, H = self.figure_size
+
+        with suppress(ZeroDivisionError):
+            m.t = self._convert(conversion, H, self.t)
+        with suppress(ZeroDivisionError):
+            m.r = self._convert(conversion, W, self.r)
+        with suppress(ZeroDivisionError):
+            m.b = self._convert(conversion, H, self.b)
+        with suppress(ZeroDivisionError):
+            m.l = self._convert(conversion, W, self.l)
+
+        m.unit = unit
+        return m
+
+    def _convert(self, conversion: str, D: float, value: float) -> float:
         dpi = 72
-        size: float = self.theme.getp((self.themeable_name, "size"), 11)
-        from_units = self.units
-        to_units = units
-        W: float
-        H: float
-        W, H = self.theme.getp("figure_size")  # inches
-        L = (W * dpi) if loc in "tb" else (H * dpi)  # pts
+        L = D * dpi  # pts
 
         functions: dict[str, Callable[[float], float]] = {
             "fig-in": lambda x: x * L / dpi,
-            "fig-lines": lambda x: x * L / size,
+            "fig-lines": lambda x: x * L / self.fontsize,
             "fig-pt": lambda x: x * L,
             "in-fig": lambda x: x * dpi / L,
-            "in-lines": lambda x: x * dpi / size,
+            "in-lines": lambda x: x * dpi / self.fontsize,
             "in-pt": lambda x: x * dpi,
-            "lines-fig": lambda x: x * size / L,
-            "lines-in": lambda x: x * size / dpi,
-            "lines-pt": lambda x: x * size,
+            "lines-fig": lambda x: x * self.fontsize / L,
+            "lines-in": lambda x: x * self.fontsize / dpi,
+            "lines-pt": lambda x: x * self.fontsize,
             "pt-fig": lambda x: x / L,
             "pt-in": lambda x: x / dpi,
-            "pt-lines": lambda x: x / size,
+            "pt-lines": lambda x: x / self.fontsize,
         }
 
-        value: float = getattr(self, loc)
-        if from_units != to_units:
-            conversion = f"{self.units}-{units}"
-            try:
-                value = functions[conversion](value)
-            except ZeroDivisionError:
-                value = 0
-        return value
+        return functions[conversion](value)

plotnine/themes/targets.py

@@ -37,7 +37,9 @@ class ThemeTargets:
     panel_border: list[Rectangle] = field(default_factory=list)
     plot_caption: Optional[Text] = None
     plot_subtitle: Optional[Text] = None
+    plot_tag: Optional[Text] = None
     plot_title: Optional[Text] = None
+    plot_background: Optional[Rectangle] = None
     strip_background_x: list[StripTextPatch] = field(default_factory=list)
     strip_background_y: list[StripTextPatch] = field(default_factory=list)
     strip_text_x: list[StripText] = field(default_factory=list)

plotnine/themes/theme.py

@@ -19,6 +19,8 @@ if typing.TYPE_CHECKING:
 
     from plotnine import ggplot
 
+    from .elements import margin
+
 
 # All complete themes are initiated with these rcparams. They
 # can be overridden.
@@ -122,6 +124,11 @@ class theme:
         plot_title=None,
         plot_subtitle=None,
         plot_caption=None,
+        plot_tag=None,
+        plot_title_position=None,
+        plot_caption_position=None,
+        plot_tag_location=None,
+        plot_tag_position=None,
         strip_text_x=None,
         strip_text_y=None,
         strip_text=None,
@@ -169,13 +176,6 @@ class theme:
         axis_ticks_length_minor_y=None,
         axis_ticks_length_minor=None,
         axis_ticks_length=None,
-        axis_ticks_pad_major_x=None,
-        axis_ticks_pad_major_y=None,
-        axis_ticks_pad_major=None,
-        axis_ticks_pad_minor_x=None,
-        axis_ticks_pad_minor_y=None,
-        axis_ticks_pad_minor=None,
-        axis_ticks_pad=None,
         panel_spacing_x=None,
         panel_spacing_y=None,
         panel_spacing=None,
@@ -270,6 +270,12 @@ class theme:
         """
         return self.themeables.getp
 
+    def get_margin(self, name: str) -> margin:
+        """
+        Return the margin propery of a element_text themeables
+        """
+        return self.themeables.getp((name, "margin"))
+
     def apply(self):
         """
         Apply this theme, then apply additional modifications in order.

plotnine/themes/theme_gray.py

@@ -1,6 +1,12 @@
 from .._utils.registry import alias
 from ..options import get_option
-from .elements import element_blank, element_line, element_rect, element_text
+from .elements import (
+    element_blank,
+    element_line,
+    element_rect,
+    element_text,
+    margin,
+)
 from .theme import theme
 
 
@@ -40,29 +46,28 @@ class theme_gray(theme):
                 size=base_size,
                 linespacing=0.9,
                 rotation=0,
-                margin={},
+                margin=margin(),
             ),
             aspect_ratio=get_option("aspect_ratio"),
             axis_line=element_line(),
             axis_line_x=element_blank(),
             axis_line_y=element_blank(),
             axis_text=element_text(size=base_size * 0.8, color="#4D4D4D"),
-            axis_text_x=element_text(va="top", margin={"t": fifth_line}),
-            axis_text_y=element_text(ha="right", margin={"r": fifth_line}),
+            axis_text_x=element_text(va="top", margin=margin(t=fifth_line)),
+            axis_text_y=element_text(ha="right", margin=margin(r=fifth_line)),
             axis_ticks=element_line(color="#333333"),
             axis_ticks_length=0,
             axis_ticks_length_major=quarter_line,
             axis_ticks_length_minor=eighth_line,
             axis_ticks_minor=element_blank(),
-            axis_ticks_pad=2,
             axis_title_x=element_text(
-                va="bottom", ha="center", margin={"t": m, "units": "fig"}
+                va="bottom", ha="center", margin=margin(t=m, unit="fig")
             ),
             axis_title_y=element_text(
                 angle=90,
                 va="center",
                 ha="left",
-                margin={"r": m, "units": "fig"},
+                margin=margin(r=m, unit="fig"),
             ),
             dpi=get_option("dpi"),
             figure_size=get_option("figure_size"),
@@ -83,23 +88,11 @@ class theme_gray(theme):
             legend_spacing=10,  # points
             legend_text=element_text(
                 size=base_size * 0.8,
-                margin={
-                    "t": m / 1.5,
-                    "b": m / 1.5,
-                    "l": m / 1.5,
-                    "r": m / 1.5,
-                    "units": "fig",
-                },
+                margin=margin(m / 1.5, m / 1.5, m / 1.5, m / 1.5, "fig"),
             ),
             legend_ticks=element_line(color="#CCCCCC", size=1),
             legend_title=element_text(
-                margin={
-                    "t": m,
-                    "b": m / 2,
-                    "l": m * 2,
-                    "r": m * 2,
-                    "units": "fig",
-                },
+                margin=margin(t=m, l=m * 2, b=m / 2, r=m * 2, unit="fig")
             ),
             panel_background=element_rect(fill="#EBEBEB"),
             panel_border=element_blank(),
@@ -112,20 +105,29 @@ class theme_gray(theme):
                 ha="right",
                 va="bottom",
                 ma="left",
-                margin={"t": m, "units": "fig"},
+                margin=margin(t=m, unit="fig"),
             ),
             plot_margin=m,
             plot_subtitle=element_text(
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
             plot_title=element_text(
                 size=base_size * 1.2,
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
+            plot_tag=element_text(
+                size=base_size * 1.2,
+                va="center",
+                ha="center",
+            ),
+            plot_title_position="panel",
+            plot_caption_position="panel",
+            plot_tag_location="margin",
+            plot_tag_position="topleft",
             strip_align=0,
             strip_background=element_rect(color="none", fill="#D9D9D9"),
             strip_background_x=element_rect(width=1),
@@ -134,13 +136,7 @@ class theme_gray(theme):
                 color="#1A1A1A",
                 size=base_size * 0.8,
                 linespacing=1.0,
-                margin={
-                    "t": 1 / 3,
-                    "b": 1 / 3,
-                    "l": 1 / 3,
-                    "r": 1 / 3,
-                    "units": "lines",
-                },
+                margin=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
             ),
             strip_text_y=element_text(rotation=-90),
             complete=True,

plotnine/themes/theme_matplotlib.py

@@ -1,5 +1,11 @@
 from ..options import get_option
-from .elements import element_blank, element_line, element_rect, element_text
+from .elements import (
+    element_blank,
+    element_line,
+    element_rect,
+    element_text,
+    margin,
+)
 from .theme import theme
 
 
@@ -38,16 +44,16 @@ class theme_matplotlib(theme):
                 margin={},
             ),
             aspect_ratio=get_option("aspect_ratio"),
-            axis_text=element_text(margin={"t": 2.4, "r": 2.4, "units": "pt"}),
+            axis_text=element_text(margin=margin(t=2.4, r=2.4, unit="pt")),
             axis_title_x=element_text(
-                va="bottom", ha="center", margin={"t": m, "units": "fig"}
+                va="bottom", ha="center", margin=margin(t=m, unit="fig")
             ),
             axis_line=element_blank(),
             axis_title_y=element_text(
                 angle=90,
                 va="center",
                 ha="left",
-                margin={"r": m, "units": "fig"},
+                margin=margin(r=m, unit="fig"),
             ),
             dpi=get_option("dpi"),
             figure_size=get_option("figure_size"),
@@ -64,24 +70,12 @@ class theme_matplotlib(theme):
             legend_position="right",
             legend_spacing=10,
             legend_text=element_text(
-                margin={
-                    "t": m / 2,
-                    "b": m / 2,
-                    "l": m / 2,
-                    "r": m / 2,
-                    "units": "fig",
-                }
+                margin=margin(m / 2, m / 2, m / 2, m / 2, "fig")
             ),
             legend_ticks=element_line(color="black"),
             legend_title=element_text(
                 ha="left",
-                margin={
-                    "t": m,
-                    "b": m / 2,
-                    "l": m * 2,
-                    "r": m * 2,
-                    "units": "fig",
-                },
+                margin=margin(t=m, l=m * 2, b=m / 2, r=m * 2, unit="fig"),
             ),
             panel_border=element_rect(color="black"),
             panel_grid=element_blank(),
@@ -90,32 +84,35 @@ class theme_matplotlib(theme):
                 ha="right",
                 va="bottom",
                 ma="left",
-                margin={"t": m, "units": "fig"},
+                margin=margin(t=m, unit="fig"),
             ),
             plot_margin=m,
             plot_subtitle=element_text(
                 size=base_size * 0.9,
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
             plot_title=element_text(
                 va="top",
                 ma="left",
-                margin={"b": m, "units": "fig"},
+                margin=margin(b=m, unit="fig"),
             ),
+            plot_tag=element_text(
+                size=base_size * 1.2,
+                va="center",
+                ha="center",
+            ),
+            plot_title_position="panel",
+            plot_caption_position="panel",
+            plot_tag_location="margin",
+            plot_tag_position="topleft",
             strip_align=0,
             strip_background=element_rect(
                 fill="#D9D9D9", color="black", size=linewidth
             ),
             strip_text=element_text(
-                margin={
-                    "t": 1 / 3,
-                    "b": 1 / 3,
-                    "l": 1 / 3,
-                    "r": 1 / 3,
-                    "units": "lines",
-                },
+                margin=margin(1 / 3, 1 / 3, 1 / 3, 1 / 3, "lines"),
             ),
             strip_text_y=element_text(rotation=-90),
             complete=True,