plot-io 0.1.0__py3-none-any.whl

plot_io/settings.py

@@ -0,0 +1,281 @@
+"""Settings: declared, validated and inherited.
+
+Every object of the model (figure, plot, axis, series, …) declares its settings in a
+``SETTINGS`` table of :class:`Setting`.  Values are checked when they are set, and read
+with :meth:`Settings.get`, which falls back to the parent chain (series → plot → figure)
+for inherited settings, then to the figure's theme, then to the default in
+:data:`plot_io.defaults.DEFAULTS`.
+"""
+
+import difflib
+import enum
+import math
+from collections.abc import Callable, Iterable
+from typing import Any, Self
+
+from .defaults import default_of, inherited
+
+__all__ = ["Setting", "Settings", "THEME", "ALIASES", "route", "unknown_message", "canonical"]
+
+#: Short names accepted for settings, on every class that has the canonical setting.
+ALIASES = {"c": "color", "s": "size", "cmap": "color_map", "smap": "size_map"}
+
+
+def canonical(name: str, table: Any) -> str:
+    """``name``, or the setting it is an alias of when ``table`` has that setting."""
+    if name not in table:
+        target = ALIASES.get(name)
+        if target is not None and target in table:
+            return target
+    return name
+
+
+def canonical_kwargs(kwargs: dict[str, Any], table: Any, what: str) -> dict[str, Any]:
+    """``kwargs`` with aliases replaced; an alias given with its setting is an error."""
+    out: dict[str, Any] = {}
+    for name, value in kwargs.items():
+        key = canonical(name, table)
+        if key in out:
+            raise ValueError(f"{what}: {name!r} and {key!r} are the same setting; give one")
+        out[key] = value
+    return out
+
+#: Inherited settings at the top of the chain (the bare names of ``DEFAULTS``).  A figure's
+#: style (see :mod:`plot_io.styles`) is merged over it.
+THEME: dict[str, Any] = inherited()
+
+
+class Setting:
+    """One declared setting: ``check(value)`` validates and normalizes a value (raising
+    ``ValueError``).  Defaults are in :data:`plot_io.defaults.DEFAULTS`."""
+
+    __slots__ = ("name", "check", "inherited", "doc", "length")
+
+    def __init__(self, check: Callable[[Any], Any] | None = None, *,
+                 inherited: bool = False, doc: str = "", length: bool = False) -> None:
+        self.name = ""
+        self.check = check
+        self.inherited = inherited
+        self.doc = doc
+        self.length = length        # multiplied by a figure's `scaling`
+
+
+def table(**settings: Setting) -> dict[str, Setting]:
+    """A ``SETTINGS`` table, with each setting's name filled in."""
+    for name, s in settings.items():
+        s.name = name
+    return settings
+
+
+def unknown_message(name: str, candidates: Iterable[str], what: str) -> str:
+    if name == "theme":
+        return ("unknown setting 'theme': use style= (a style name, or a dict of settings "
+                "with an optional \"base\")")
+    near = difflib.get_close_matches(name, list(candidates), n=1, cutoff=0.6)
+    hint = f" (did you mean {near[0]!r}?)" if near else ""
+    return f"unknown {what} setting {name!r}{hint}"
+
+
+class Settings:
+    """Base of every object with settings."""
+
+    SETTINGS: dict[str, Setting] = {}
+
+    def __init__(self, **settings: Any) -> None:
+        self._values: dict[str, Any] = {}
+        self.set(**settings)
+
+    def _parent(self) -> "Settings | None":
+        return None
+
+    def _theme(self) -> dict[str, Any]:
+        p = self._parent()
+        return p._theme() if p is not None else THEME
+
+    @property
+    def kind(self) -> str:
+        return type(self).__name__
+
+    def set(self, **settings: Any) -> Self:
+        """Set settings; ``None`` goes back to the inherited or default value."""
+        settings = canonical_kwargs(settings, self.SETTINGS, self.kind)
+        checked = {}
+        for name, value in settings.items():
+            s = self.SETTINGS.get(name)
+            if s is None:
+                raise ValueError(unknown_message(name, self.SETTINGS, self.kind))
+            if value is not None and s.check is not None:
+                try:
+                    value = s.check(value)
+                except (TypeError, ValueError) as e:
+                    raise ValueError(f"{self.kind} setting {name!r}: {e}") from None
+            checked[name] = value
+        for name, value in checked.items():
+            if value is None:
+                self._values.pop(name, None)
+            else:
+                self._values[name] = value
+        return self
+
+    def _theme_keys(self, name: str) -> tuple[str, ...]:
+        """Theme keys of a setting, most specific first."""
+        return (f"{self.kind}.{name}",)
+
+    def is_set(self, name: str) -> bool:
+        return name in self._values
+
+    def get(self, name: str) -> Any:
+        """The resolved value of a setting."""
+        if name in self._values:
+            return self._values[name]
+        s = self.SETTINGS[name]
+        theme = self._theme()
+        for key in self._theme_keys(name):
+            if key in theme:
+                return theme[key]
+        if s.inherited:
+            p = self._parent()
+            while p is not None:
+                if name in p.SETTINGS:
+                    return p.get(name)
+                p = p._parent()
+            return theme.get(name)
+        return default_of(self, name)
+
+    def settings(self) -> dict[str, Any]:
+        """The settings set explicitly on this object."""
+        return dict(self._values)
+
+
+def route(kwargs: dict[str, Any], levels: list[type[Settings]],
+          extra: dict[int, Iterable[str]] | None = None) -> list[dict[str, Any]]:
+    """Split ``kwargs`` among ``levels`` (lowest first): each name goes to the lowest
+    level declaring it (``extra`` adds names a level accepts besides its settings)."""
+    out: list[dict[str, Any]] = [{} for _ in levels]
+    for name, value in kwargs.items():
+        for i, cls in enumerate(levels):
+            key = canonical(name, cls.SETTINGS)
+            if key in cls.SETTINGS or (extra and name in extra.get(i, ())):
+                if key in out[i]:
+                    raise ValueError(f"{cls.__name__}: {name!r} and {key!r} are the same "
+                                     f"setting; give one")
+                out[i][key] = value
+                break
+        else:
+            names = set().union(*(cls.SETTINGS for cls in levels))
+            raise ValueError(unknown_message(name, names, levels[0].__name__))
+    return out
+
+
+# ---------------------------------------------------------------------------
+# Validators
+# ---------------------------------------------------------------------------
+
+def number(lo: float | None = None, hi: float | None = None, positive: bool = False,
+           integer: bool = False) -> Callable[[Any], float]:
+    def check(v):
+        if isinstance(v, bool) or not isinstance(v, (int, float)):
+            raise ValueError(f"expected a number, got {v!r}")
+        v = int(v) if integer else float(v)
+        if integer and not float(v).is_integer():
+            raise ValueError(f"expected an integer, got {v!r}")
+        if not math.isfinite(v):
+            raise ValueError("expected a finite number")
+        if positive and not v > 0:
+            raise ValueError(f"expected a positive number, got {v!r}")
+        if lo is not None and v < lo:
+            raise ValueError(f"expected at least {lo}, got {v!r}")
+        if hi is not None and v > hi:
+            raise ValueError(f"expected at most {hi}, got {v!r}")
+        return v
+    return check
+
+
+def boolean(v: Any) -> bool:
+    if not isinstance(v, bool):
+        raise ValueError(f"expected True or False, got {v!r}")
+    return v
+
+
+def one_of(*choices: str, aliases: dict[str, str] | None = None) -> Callable[[Any], str]:
+    def check(v):
+        if isinstance(v, enum.Enum):
+            v = v.value
+        if isinstance(v, str):
+            key = v.strip().lower().replace("-", "_")
+            key = (aliases or {}).get(key, key)
+            if key in choices:
+                return key
+        raise ValueError(f"expected one of {', '.join(map(repr, choices))}, got {v!r}")
+    return check
+
+
+def text(v: Any) -> Any:
+    """A string or rich content (a list of strings and spans)."""
+    if isinstance(v, str):
+        return v
+    if isinstance(v, (list, tuple)):
+        return list(v)
+    if hasattr(v, "text"):
+        return [v]
+    return str(v)
+
+
+def anything(v: Any) -> Any:
+    return v
+
+
+def either(*checks: Callable[[Any], Any]) -> Callable[[Any], Any]:
+    def check(v):
+        errors = []
+        for c in checks:
+            try:
+                return c(v)
+            except (TypeError, ValueError) as e:
+                errors.append(str(e))
+        raise ValueError("; ".join(errors))
+    return check
+
+
+def literal(*values: Any) -> Callable[[Any], Any]:
+    def check(v):
+        for w in values:
+            if v == w and type(v) is type(w):
+                return v
+        raise ValueError(f"expected one of {', '.join(map(repr, values))}, got {v!r}")
+    return check
+
+
+def color(v: Any) -> Any:
+    """A color pdf_io accepts, or a palette reference ``"C0"``, ``"C1"``, …"""
+    from pdf_io.colors import to_rgba
+
+    if isinstance(v, str) and len(v) >= 2 and v[0] in "Cc" and v[1:].isdigit():
+        return "C" + v[1:]
+    try:
+        rgba = to_rgba(v)
+    except (TypeError, ValueError):
+        rgba = None
+    if rgba is None and not (isinstance(v, str) and v.strip().lower() in ("none", "transparent")):
+        raise ValueError(f"invalid color {v!r}")
+    return v
+
+
+def pair(check: Callable[[Any], Any]) -> Callable[[Any], tuple[Any, Any]]:
+    def c(v):
+        if not isinstance(v, (tuple, list)) or len(v) != 2:
+            raise ValueError(f"expected a pair, got {v!r}")
+        return (check(v[0]), check(v[1]))
+    return c
+
+
+def dpi_or_bool(v: Any) -> Any:
+    if isinstance(v, bool):
+        return v
+    return number(positive=True)(v)
+
+
+def simplify_value(v: Any) -> Any:
+    if v == "auto":
+        return "auto"
+    return dpi_or_bool(v)

plot_io/shapes.py

@@ -0,0 +1,57 @@
+"""Many rectangles or polygons in one call (pdf_io's ``draw_rects`` and ``fill_polygons``)."""
+
+from array import array
+from typing import Any
+
+__all__ = ["draw_rects", "fill_polygons"]
+
+
+def draw_rects(canvas: Any, x: Any, y: Any, w: Any, h: Any, fill: Any = None,
+               stroke: Any = None, line_width: Any = None, simplify: Any = None) -> None:
+    """Rectangles with top-left corners ``(x, y)`` and sizes ``(w, h)`` (page units);
+    ``fill``, ``stroke`` and ``line_width``: one value or one per rectangle."""
+    if not len(x):
+        return
+    canvas.draw_rects(x, y, w, h, fill=fill, stroke=stroke, line_width=line_width,
+                      simplify=simplify)
+
+
+def fill_polygons(canvas: Any, polygons: list[list[tuple[Any, Any]]], fill: Any = None,
+                  stroke: Any = None, line_width: Any = None, fill_rule: str = "nonzero",
+                  simplify: Any = None) -> None:
+    """Polygons, each a list of rings ``(xs, ys)`` filled together (holes work);
+    ``fill``, ``stroke`` and ``line_width``: one value or one per polygon."""
+    if not polygons:
+        return
+    xs, ys = array("d"), array("d")
+    ring_starts, path_starts = array("q"), array("q")
+    for poly in polygons:
+        path_starts.append(len(ring_starts))
+        for rx, ry in poly:
+            ring_starts.append(len(xs))
+            xs.extend(rx)
+            ys.extend(ry)
+    ring_starts.append(len(xs))
+    path_starts.append(len(ring_starts) - 1)
+    canvas.fill_polygons((xs, ys, ring_starts, path_starts), fill=fill, stroke=stroke,
+                         line_width=line_width, fill_rule=fill_rule, simplify=simplify)
+
+
+def fill_ring_sets(canvas: Any, ring_sets: list[tuple[Any, Any, Any]], fill: Any,
+                   simplify: Any = None) -> None:
+    """Paths given as pdf_io ring arrays ``(xs, ys, ring_starts)`` (one path each), one fill
+    per path."""
+    xs, ys = array("d"), array("d")
+    ring_starts, path_starts = array("q"), array("q")
+    for rx, ry, starts in ring_sets:
+        path_starts.append(len(ring_starts))
+        base = len(xs)
+        ring_starts.extend(base + s for s in starts[:-1])
+        xs.extend(rx)
+        ys.extend(ry)
+    if not len(ring_starts):
+        return
+    ring_starts.append(len(xs))
+    path_starts.append(len(ring_starts) - 1)
+    canvas.fill_polygons((xs, ys, ring_starts, path_starts), fill=fill, fill_rule="nonzero",
+                         simplify=simplify)

plot_io/sharing.py

@@ -0,0 +1,160 @@
+"""Shared axes: plots whose x (or y) axes form a group have one scale, one set of limits,
+the same ticks and category order, and (``label_outer``) tick labels and titles only on
+the outer plots of each column (x) or row (y).
+
+Groups come from the figure's ``share_x``/``share_y``/``share`` (all plots, plots of a
+column span, plots of a row span) and from plots' own ``share_x=other`` (chained).
+"""
+
+from typing import Any
+
+__all__ = ["check_figure_share", "check_share", "groups", "apply"]
+
+_MODES = ("all", "col", "row")
+
+
+def check_figure_share(v: Any) -> Any:
+    """``False``, ``True``/``"all"``, ``"col"`` or ``"row"``."""
+    if v is False or v is True:
+        return "all" if v else False
+    if isinstance(v, str) and v.strip().lower() in _MODES:
+        return v.strip().lower()
+    raise ValueError(f"expected False, True, 'all', 'col' or 'row', got {v!r}")
+
+
+def check_share(v: Any) -> Any:
+    """The figure's ``share``: as ``share_x`` or ``"grid"`` (x per column, y per row)."""
+    if isinstance(v, str) and v.strip().lower() == "grid":
+        return "grid"
+    return check_figure_share(v)
+
+
+def figure_modes(fig: Any) -> dict[str, Any]:
+    """The figure's sharing mode per axis role."""
+    share = fig.get("share")
+    out: dict[str, Any] = {"x": False, "y": False}
+    if share == "grid":
+        out = {"x": "col", "y": "row"}
+    elif share:
+        out = {"x": share, "y": share}
+    for role in ("x", "y"):
+        if fig.is_set(f"share_{role}"):
+            out[role] = fig.get(f"share_{role}")
+    return out
+
+
+class _Union:
+    def __init__(self, items: list[Any]) -> None:
+        self.parent = {id(p): id(p) for p in items}
+
+    def find(self, k: int) -> int:
+        while self.parent[k] != k:
+            self.parent[k] = self.parent[self.parent[k]]
+            k = self.parent[k]
+        return k
+
+    def join(self, a: Any, b: Any) -> None:
+        ra, rb = self.find(id(a)), self.find(id(b))
+        if ra != rb:
+            self.parent[rb] = ra
+
+
+def groups(fig: Any, areas: list[Any], role: str) -> list[tuple[list[Any], bool]]:
+    """Groups of areas sharing axis ``role`` (two or more), each with whether it comes from
+    the figure's setting (outer labels by default)."""
+    from .plot import Plot
+
+    plots = [a for a in areas if isinstance(a.obj, Plot) and a.obj.get("axes")]
+    if not plots:
+        return []
+    mode = figure_modes(fig)[role]
+    u = _Union(plots)
+    own = {id(a): a.obj.own_share(role) for a in plots}
+    figure_made: set[int] = set()
+    if mode:
+        free = [a for a in plots if own[id(a)] is None]
+        keys: dict[int, Any]
+        if mode == "all":
+            keys = {id(a): 0 for a in free}
+        elif mode == "col":
+            keys = {id(a): (a.c0, a.c1) for a in free}
+        else:
+            keys = {id(a): (a.r0, a.r1) for a in free}
+        first: dict[Any, Any] = {}
+        for a in free:
+            k = keys[id(a)]
+            if k in first:
+                u.join(first[k], a)
+            else:
+                first[k] = a
+        figure_made = {id(a) for a in free}
+    by_plot = {id(a.obj): a for a in plots}
+    for a in plots:
+        other = own[id(a)]
+        if other is not None:
+            b = by_plot.get(id(other))
+            if b is None:
+                raise ValueError(f"{a.obj!r} shares its {role} axis with {other!r}, which is "
+                                 f"not a plot of the same figure")
+            u.join(b, a)
+    out: dict[int, list[Any]] = {}
+    for a in plots:
+        out.setdefault(u.find(id(a)), []).append(a)
+    result = []
+    for members in out.values():
+        if len(members) > 1:
+            result.append((members, all(id(m) in figure_made for m in members)))
+    return result
+
+
+def _leader(members: list[Any], role: str) -> Any:
+    axes = [getattr(m.obj, f"{role}_axis") for m in members]
+    limited = [a for a in axes if a.get("limits") != "auto"]
+    specs = {repr(a.get("limits")) for a in limited}
+    if len(specs) > 1:
+        raise ValueError(f"plots sharing their {role} axis have different limits: "
+                         f"{', '.join(sorted(specs))}")
+    scales = {a.get("scale") for a in axes if a.is_set("scale")}
+    if len(scales) > 1:
+        raise ValueError(f"plots sharing their {role} axis have different scales: "
+                         f"{', '.join(sorted(map(str, scales)))}")
+    for pick in (limited, [a for a in axes if a.is_set("scale")], axes):
+        if pick:
+            return members[axes.index(pick[0])]
+    return members[0]
+
+
+def apply(fig: Any, areas: list[Any]) -> None:
+    """Resolve every group: one scale and set of limits from all members' series (category
+    order in plot order), ticks shared, and outer labels."""
+    label_outer = fig.get("label_outer")
+    for role in ("x", "y"):
+        for members, from_figure in groups(fig, areas, role):
+            lead = _leader(members, role)
+            items = []
+            for m in members:
+                items.extend(m.state.role_items[role])
+            lstate = getattr(lead.state, role)
+            lstate.resolve(items, lead.state.padded)
+            for m in members:
+                st = getattr(m.state, role)
+                st.shared = lstate if m is not lead else None
+                if m is not lead:
+                    st.copy_limits(lstate)
+            outer = label_outer if label_outer is not None else from_figure
+            if not outer:
+                continue
+            for m in members:
+                getattr(m.state, role).hide_labels = not _is_outer(m, members, role)
+
+
+def _is_outer(a: Any, members: list[Any], role: str) -> bool:
+    if role == "x":
+        same = [m for m in members if (m.c0, m.c1) == (a.c0, a.c1)]
+        if getattr(a.state, "x").on_far_side():
+            return a.r0 == min(m.r0 for m in same)
+        return a.r1 == max(m.r1 for m in same)
+    same = [m for m in members if (m.r0, m.r1) == (a.r0, a.r1)]
+    if getattr(a.state, "y").on_far_side():
+        return a.c1 == max(m.c1 for m in same)
+    return a.c0 == min(m.c0 for m in same)

plot_io/slots.py

@@ -0,0 +1,52 @@
+"""Category slots: categorical series of one dodge group share each category's slot.
+
+Box, violin, bar, strip and swarm series place one item per category.  The series of a
+dodge group (``Series.DODGE_GROUP``) with the same orientation that have a category split
+its slot (``width``) evenly, in call order (stacked series count as one); ``dodge=False``
+overlays a series on the whole slot.  ``gap`` is the fraction of each part left empty when several series share a slot.
+"""
+
+from typing import Any
+
+__all__ = ["slots"]
+
+
+def _token(s: Any) -> Any:
+    """Stacked series share one part of a slot, and so do split violins."""
+    if "stack" in s.SETTINGS and s.get("stack"):
+        return "stack"
+    if "split" in s.SETTINGS and s.get("split"):
+        return "split"
+    return s
+
+
+def slots(series: Any, ctx: Any) -> list[tuple[float, float]]:
+    """``(center, width)`` of each of ``series.cats``, in category units."""
+    width = series.get("width")
+    positions = getattr(series, "positions", None)
+    if positions is not None:
+        return [(p, width) for p in positions]
+    horizontal = series._horizontal()
+    state = ctx.y if horizontal else ctx.x
+    group = series.DODGE_GROUP
+    peers = [s for s in ctx.plot.series if s.DODGE_GROUP == group
+             and getattr(s, "positions", None) is None and s._horizontal() == horizontal]
+    gap = series.get("gap") if "gap" in series.SETTINGS else 0.0
+    out = []
+    for k in series.cats:
+        i = state.categories.index(k)
+        if not series.get("dodge"):
+            out.append((float(i), width))
+            continue
+        members: list[Any] = []
+        for s in peers:
+            if not s.get("dodge") or k not in s.cats:
+                continue
+            token = _token(s)
+            if token not in members:
+                members.append(token)
+        m = len(members)
+        j = members.index(_token(series))
+        share = width / m
+        out.append((i - width / 2 + (j + 0.5) * share, share * (1.0 - gap) if m > 1 else share))
+    return out

plot_io/stacking.py

@@ -0,0 +1,63 @@
+"""Stacking: series with ``stack=True`` sit on the previous stacked series of their group.
+
+A stackable series (``Series.STACK_GROUP``) gives its layers as ``(keys, values)``
+(``stack_layers()``): a key per value (a category or an x value).  Layers stack in call
+order within the plot, per key; positive and negative values stack separately.  With
+``stack="normalize"`` on any series of the group, each key's values are divided by the
+key's total (of absolute values).
+"""
+
+import math
+from typing import Any
+
+__all__ = ["stacked", "check_stack"]
+
+
+def check_stack(v: Any) -> Any:
+    if v == "normalize":
+        return "normalize"
+    if isinstance(v, bool):
+        return v
+    raise ValueError(f"expected True, False or 'normalize', got {v!r}")
+
+
+def _group(s: Any) -> tuple[Any, bool]:
+    return s.STACK_GROUP, s._horizontal()
+
+
+def stacked(series: Any) -> list[tuple[list[float], list[float]]]:
+    """``(bottoms, tops)`` of each layer of ``series`` (which has ``stack`` set)."""
+    group = _group(series)
+    members = [s for s in series.plot.series if s.STACK_GROUP is not None
+               and s.get("stack") and _group(s) == group]
+    normalize = any(s.get("stack") == "normalize" for s in members)
+    totals: dict[Any, float] = {}
+    if normalize:
+        for s in members:
+            for keys, vals in s.stack_layers():
+                for k, v in zip(keys, vals):
+                    if math.isfinite(v):
+                        totals[k] = totals.get(k, 0.0) + abs(v)
+    pos: dict[Any, float] = {}
+    neg: dict[Any, float] = {}
+    for s in members:
+        out = []
+        for keys, vals in s.stack_layers():
+            bottoms, tops = [], []
+            for k, v in zip(keys, vals):
+                if not math.isfinite(v):
+                    bottoms.append(math.nan)
+                    tops.append(math.nan)
+                    continue
+                if normalize:
+                    t = totals.get(k, 0.0)
+                    v = v / t if t else 0.0
+                acc = pos if v >= 0 else neg
+                b = acc.get(k, 0.0)
+                acc[k] = b + v
+                bottoms.append(b)
+                tops.append(b + v)
+            out.append((bottoms, tops))
+        if s is series:
+            return out
+    return []