plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/shapes.py

@@ -0,0 +1,66 @@
+"""Many rectangles or polygons in one call (vec_io's ``draw_rects`` and ``draw_polygons``)."""
+
+from array import array
+from typing import Any
+from .canvas import Canvas
+
+__all__ = ["draw_rects", "draw_polygons"]
+
+
+def draw_rects(canvas: Canvas, x: Any, y: Any, w: Any, h: Any, fill: Any = None,
+               stroke: Any = None, stroke_width: Any = None, simplify: Any = None) -> None:
+    """Rectangles with top-left corners ``(x, y)`` and sizes ``(w, h)`` (page units);
+    ``fill``, ``stroke`` and ``stroke_width``: one value or one per rectangle."""
+    if not len(x):
+        return
+    canvas.draw_rects(x, y, w, h, fill=fill, stroke=stroke, stroke_width=stroke_width,
+                      simplify=simplify)
+
+
+def draw_polygons(canvas: Canvas, polygons: list[list[tuple[Any, Any]]], fill: Any = None,
+                  stroke: Any = None, stroke_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 ``stroke_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.draw_polygons((xs, ys, ring_starts, path_starts), fill=fill, stroke=stroke,
+                         stroke_width=stroke_width, fill_rule=fill_rule, simplify=simplify)
+
+
+def fill_ring_sets(canvas: Canvas, ring_sets: list[tuple[Any, Any, Any]], fill: Any,
+                   simplify: Any = None) -> None:
+    """Paths given as vec_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.draw_polygons((xs, ys, ring_starts, path_starts), fill=fill, fill_rule="nonzero",
+                         simplify=simplify)
+
+
+def swatch(x: float, y: float, w: float, h: float) -> tuple[float, float, float, float]:
+    """The rectangle legend symbols of filled series use in a symbol box ``(x, y, w, h)``:
+    0.6em high with the default row height (the box is 0.8 of the row, 1.35em), as wide
+    as the box, like line symbols."""
+    sh = 0.6 / 1.08 * h
+    return x, y + (h - sh) / 2, w, sh

plot_io/sharing.py

@@ -0,0 +1,232 @@
+"""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, or the plots holding a plot type: ``share_y="bigwig"``)
+and from plots' own ``share_x=other`` (chained).  The figure's ``share_color`` and
+``share_size`` group plots the same way for their series' color and size axes
+(:func:`plot_io.mapped.train`).  The last plot of
+a figure group (``figure.group``) shows the x tick labels too, under ``label_outer``.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+__all__ = ["check_figure_share", "check_legend_share", "check_share", "groups", "leader", "apply"]
+
+_MODES = ("all", "col", "row")
+
+
+def _check(v: Any, types: bool, grid: bool = False) -> Any:
+    """A sharing mode: ``False``, ``True``/``"all"``, ``"col"``, ``"row"``; with ``types``
+    a plot type's name, with ``grid`` ``"grid"``."""
+    if v is False or v is True:
+        return "all" if v else False
+    s = v.strip() if isinstance(v, str) else None
+    if s is not None and (s.lower() in _MODES or (grid and s.lower() == "grid")):
+        return s.lower()
+    if s is not None and types:
+        from .layers import layer_types
+        if s in layer_types():
+            return s
+    kinds = "False, True, 'all', 'col', 'row'" + (", 'grid'" if grid else "")
+    tail = " or a plot type's name" if types else ""
+    raise ValueError(f"expected {kinds}{tail}, got {v!r}")
+
+
+def check_figure_share(v: Any) -> Any:
+    """``False``, ``True``/``"all"``, ``"col"``, ``"row"`` or a plot type's name (the
+    plots holding one: ``"bigwig"``)."""
+    return _check(v, True)
+
+
+def check_legend_share(v: Any) -> Any:
+    """The figure's ``share_legend``: ``False``, ``True``/``"all"``, ``"row"`` or ``"col"``."""
+    return _check(v, False)
+
+
+def check_share(v: Any) -> Any:
+    """The figure's ``share``: as ``share_x`` or ``"grid"`` (x per column, y per row)."""
+    return _check(v, True, grid=True)
+
+
+def figure_modes(fig: Any) -> dict[str, Any]:
+    """The figure's sharing mode per axis role."""
+    share = fig.resolve("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"):
+        v = fig.resolve(f"share_{role}")
+        if v is not None:
+            out[role] = v
+    return out
+
+
+def _holds(plot: Any, kind: str) -> bool:
+    """Whether a plot holds a series of the plot type named ``kind``."""
+    from .layers import layer_types
+    cls = layer_types().get(kind)
+    return isinstance(cls, type) and any(isinstance(s, cls) for s in plot.series)
+
+
+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`` (``"x"``, ``"y"``, or ``"color"``/``"size"``:
+    their series' color or size axes; ``"legend"``: one figure legend), two or more each,
+    with whether the group comes from the figure's setting (outer labels by default)."""
+    from .plot import Plot
+
+    mapped = role in ("color", "size", "legend")
+    plots = [a for a in areas if isinstance(a.obj, Plot) and (mapped or a.obj.resolve("axes"))]
+    if not plots:
+        return []
+    mode = fig.resolve(f"share_{role}") if mapped else figure_modes(fig)[role]
+    u = _Union(plots)
+    own = {id(a): None if mapped else 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}
+        elif mode == "row":
+            keys = {id(a): (a.r0, a.r1) for a in free}
+        else:                                # the plots holding a plot type
+            free = [a for a in free if _holds(a.obj, mode)]
+            keys = {id(a): 0 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(axes: list[Any], role: str,
+           given: Callable[[Any, str], bool] | None = None) -> int:
+    """Index of the axis whose scale and limits a shared group takes: one with limits, else
+    one with a scale, else the first.  Different limits or scales are an error.  ``given(axis,
+    name)``: whether a setting is given (default: set on the axis)."""
+    is_given = given or (lambda a, name: a.is_set(name))
+    what = f"{role} axes" if role in ("color", "size") else f"{role} axis"
+    limited = [a for a in axes if a.resolve("limits") != "auto"]
+    specs = {repr(a.resolve("limits")) for a in limited}
+    if len(specs) > 1:
+        raise ValueError(f"plots sharing their {what} have different limits: "
+                         f"{', '.join(sorted(specs))}")
+    scaled = [a for a in axes if is_given(a, "scale")]
+    scales = {a.resolve("scale") for a in scaled}
+    if len(scales) > 1:
+        raise ValueError(f"plots sharing their {what} have different scales: "
+                         f"{', '.join(sorted(map(str, scales)))}")
+    for pick in (limited, scaled):
+        if pick:
+            return axes.index(pick[0])
+    return 0
+
+
+def _leader(members: list[Any], role: str) -> Any:
+    return members[leader([getattr(m.obj, f"{role}_axis") for m in members], role)]
+
+
+def _check_times(members: list[Any], role: str) -> None:
+    """Refuse a group of plots some of which draw dates on the axis and some numbers."""
+    kinds = set()
+    for m in members:
+        on = [s for s in m.state.role_items[role] if s.has_axis(role)]
+        if on and all(s.categories(role) is None for s in on):
+            kinds.add(any(getattr(s, "time_role", lambda r: None)(role) for s in on))
+    if len(kinds) > 1:
+        raise ValueError(f"plots sharing their {role} axis draw dates and numbers on it: a "
+                         f"time axis would read the numbers as seconds")
+
+
+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.resolve("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)
+            if lstate.axis.resolve("scale") is None:
+                _check_times(members, role)
+            try:
+                lstate.resolve(items, lead.state.padded)
+            except ValueError as e:
+                if len(members) < 2 or "mixes categorical and numeric" not in str(e):
+                    raise
+                raise ValueError(f"plots sharing their {role} axis (share, share_{role}) draw "
+                                 f"categories on one and numbers on another: share only plots "
+                                 f"of one kind") from None
+            leaves = any(getattr(m.state, role).call_leaves for m in members)
+            for m in members:
+                st = getattr(m.state, role)
+                st.call_leaves = leaves               # a dendrogram's leaves name them all
+                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
+            ends = {id(g.end()) for g in fig.groups} if role == "x" else set()
+            for m in members:
+                st = getattr(m.state, role)
+                bottom = _is_outer(m, members, role)
+                st.hide_labels = not bottom and id(m.obj) not in ends
+                st.hide_title = not bottom
+
+
+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/sizemaps.py

@@ -0,0 +1,97 @@
+"""Size maps: the range of marker diameters mapped values are drawn with (their limits and
+scale are a size axis', :mod:`plot_io.mapped`)."""
+
+import math
+from collections.abc import Sequence
+from typing import Any
+
+from . import kernels
+from .settings import one_of
+
+__all__ = ["SizeMap", "DEFAULT"]
+
+
+def _size(v: Any) -> Any:
+    """A marker diameter: px or any length (``"1.2em"``), resolved by the series using
+    the map."""
+    from .validators import length
+    return length(lo=0)(v)
+
+
+def _size_px(v: Any, owner: Any) -> float:
+    if isinstance(v, (int, float)) and (owner is None or v != v):
+        return float(v)
+    if owner is None:
+        raise ValueError(f"SizeMap size {v!r}: a relative length needs the series it is "
+                         f"drawn for (owner=)")
+    from .units import resolve_raw
+    from .validators import length
+    return resolve_raw(owner, "size", length(lo=0), v)
+
+
+class SizeMap:
+    """Marker diameters (px) over [0, 1]: the positions of values between their size axis'
+    limits.
+
+    ``sizes``: the diameters at the two limits.  ``by="area"`` moves the marker area
+    linearly between the end areas; ``by="diameter"`` moves the diameter.  ``under`` and
+    ``over``: sizes below and above the limits (default: the end sizes; ``"none"`` leaves
+    those points out); ``bad``: size of points with a missing value (default: left out).
+
+    With ``sizes=(0, d)``, ``by="area"`` and ``size_limits="0/max"``, a marker's area is
+    proportional to its value.  ``size_map`` also takes a pair of diameters.
+    """
+
+    def __init__(self, sizes: Sequence[float] = (3.0, 13.0), by: str = "area",
+                 under: Any = None, over: Any = None, bad: Any = None) -> None:
+        if len(sizes) != 2:
+            raise ValueError("sizes must be a pair (smallest, largest)")
+        self.sizes = (_size(sizes[0]), _size(sizes[1]))
+        self.by = one_of("area", "diameter")(by)
+        self.under = self._extreme(under)
+        self.over = self._extreme(over)
+        self.bad = self._extreme(bad)
+
+    @staticmethod
+    def _extreme(v: Any) -> Any:
+        if v is None:
+            return None
+        if isinstance(v, str) and v.lower() == "none":
+            return math.nan
+        return _size(v)
+
+    def __repr__(self) -> str:
+        from .units import given
+        return f"SizeMap({given(self.sizes[0])!r}–{given(self.sizes[1])!r}, by {self.by})"
+
+    def diameters(self, owner: Any = None) -> tuple[float, float]:
+        """The end sizes in px, resolved for series ``owner`` (its `em`, scaling)."""
+        return _size_px(self.sizes[0], owner), _size_px(self.sizes[1], owner)
+
+    def map(self, values: Any, flo: float, fhi: float, function: str | None,
+            owner: Any = None) -> Any:
+        """Diameters (px) for ``values``, with ``flo``/``fhi`` the limits after the scale
+        function; lengths resolved for series ``owner``."""
+        d0, d1 = self.diameters(owner)
+        span = fhi - flo
+        nan = math.nan
+        under = d0 if self.under is None else _size_px(self.under, owner)
+        over = d1 if self.over is None else _size_px(self.over, owner)
+        bad = nan if self.bad is None else _size_px(self.bad, owner)
+        if self.by == "diameter":
+            k = (d1 - d0) / span if span else 0.0
+            lo, hi = (d0, d1) if d1 >= d0 else (d1, d0)
+            u, o = (under, over) if d1 >= d0 else (over, under)
+            return kernels.scaled(values, k, d0 - k * flo, function, low=lo, high=hi,
+                                   under=u, over=o, nan=bad)
+        a0, a1 = d0 * d0, d1 * d1
+        k = (a1 - a0) / span if span else 0.0
+        lo, hi = (a0, a1) if a1 >= a0 else (a1, a0)
+        u, o = (under * under, over * over) if a1 >= a0 else (over * over, under * under)
+        areas = kernels.scaled(values, k, a0 - k * flo, function, low=lo, high=hi,
+                                under=u, over=o, nan=bad * bad)
+        return kernels.scaled(areas, 1.0, 0.0, "sqrt")
+
+
+#: The sizes of size axes without a ``size_map``.
+DEFAULT = SizeMap()

plot_io/spec.py

@@ -0,0 +1,240 @@
+"""Renders: the model's settings resolved during one render.
+
+A render (:func:`rendering`) resolves a setting of an object on its first plain read
+(``obj.resolve(name)``) and keeps the value for the rest of the render: a dict per object
+(:meth:`Render.lookup`).  A setting never read is never resolved.  The render also holds
+what the renderer computes about the model: the layout boxes that ``%`` of the axes refers
+to, the plot's colors given to series without one, and the trained color and size axes.
+
+A setting whose value needs what only its use provides (``%`` of a layout box, of a slot,
+an axis scale) is :data:`LAZY` in the render, and resolved where it is used, against the
+render's boxes.
+"""
+
+import contextlib
+import contextvars
+import warnings
+from collections.abc import Generator
+from typing import Any
+
+from .units import NeedsContext
+
+__all__ = ["LAZY", "NeedsBox", "Render", "rendering", "current", "set_boxes", "auto_colors",
+           "warn", "warnings_once"]
+
+
+class _Lazy:
+    __slots__ = ()
+
+    def __repr__(self) -> str:
+        return "LAZY"
+
+
+#: The value of a setting resolved where it is used (it needs a layout box, a slot, a
+#: scale).
+LAZY: Any = _Lazy()
+_MISS = object()
+#: The values of an object outside the render's figure: none kept.
+_OUTSIDE: dict[str, Any] = {}
+
+
+class NeedsBox(NeedsContext):
+    """``%`` of a layout box, resolved before the box is known."""
+
+
+class Render:
+    """One render of a figure: the resolved settings of its objects, and what the renderer
+    computes about them (layout boxes, the plot's colors)."""
+
+    __slots__ = ("root", "theme", "values", "held", "tree", "boxes", "colors", "plots", "calls",
+                 "placed", "widths", "scales", "size_keys", "runs", "levels",
+                 "levels_group")
+
+    def __init__(self, root: Any) -> None:
+        self.root = root
+        self.theme = root._theme()
+        #: ``id(obj)`` → ``{name: value}``: the settings of ``obj`` read in this render.
+        self.values: dict[int, dict[str, Any]] = {}
+        #: the objects of ``values`` (kept alive, so that their ids stay theirs).
+        self.held: list[Any] = []
+        #: the ids of the objects of the figure (made on demand, see :meth:`changed`).
+        self.tree: set[int] | None = None
+        #: ``id(obj)`` → ``{"axes_width": px, …}``: the boxes `%` refers to.
+        self.boxes: dict[int, dict[str, float]] = {}
+        #: ``id(series)`` → the plot's colors it takes (``None``: it has its own).
+        self.colors: dict[int, list[Any] | None] = {}
+        #: level axes' colors (``(color group, axis key)`` → ``(plot id, {level: color})``)
+        #: and each plot's color group (``share_color``), see :mod:`plot_io.levels`
+        self.levels: dict[Any, Any] = {}
+        self.levels_group: dict[int, int] = {}
+        #: ``id(plot)`` → its calls (layers built, positions applied), ``id(series)`` → its
+        #: call (see :mod:`plot_io.layers.pipeline`).
+        self.plots: dict[int, list[Any]] = {}
+        self.calls: dict[int, Any] = {}
+        #: ``id(plot)`` → a drawing context (no canvas) of its axes as the last layout round
+        #: placed them: what stats binned at the axes' resolution read (hexagon lattices).
+        self.placed: dict[int, Any] = {}
+        #: ``id(plot)`` → the axes width (px) genome data were binned for.
+        self.widths: dict[int, float] = {}
+        #: ``id(axis)`` → the trained state of a color or size axis (see
+        #: :func:`plot_io.mapped.train`).
+        self.scales: dict[int, Any] = {}
+        #: the size keys of the trained size axes (see :func:`plot_io.mapped.size_keys`).
+        self.size_keys: dict[Any, Any] = {}
+        #: shaped lines of rich content by font database, font and content (see
+        #: :func:`plot_io.text.shape`; plain strings are memoized in the font database)
+        self.runs: dict[Any, Any] = {}
+
+    def lookup(self, obj: Any, name: str) -> Any:
+        """The resolved value of ``obj``'s setting ``name`` (resolved on its first read in
+        the render), or :data:`LAZY` (resolved where used, or ``obj`` is not of the
+        render's figure).  Markup in a text setting is checked when it is resolved."""
+        d = self.values.get(id(obj))
+        if d is None:
+            d = self.values[id(obj)] = {} if self._holds(obj) else _OUTSIDE
+            self.held.append(obj)
+        v = d.get(name, _MISS)
+        if v is _MISS:
+            if d is _OUTSIDE:
+                return LAZY
+            v = d[name] = self._compute(obj, name)
+        return v
+
+    def _holds(self, obj: Any) -> bool:
+        """Whether ``obj`` is of the render's figure (not an object being made)."""
+        try:
+            return obj._root() is self.root
+        except AttributeError:
+            return False
+
+    def changed(self, obj: Any) -> None:
+        """``obj`` was set during the render: when it is of the figure (not an object being
+        made by the render), drop what the render resolved and computed from the model."""
+        if id(obj) not in self.values:
+            if not self._holds(obj):
+                return
+            if self.tree is None:
+                self.tree = set()
+                todo = [self.root]
+                while todo:
+                    o = todo.pop()
+                    if id(o) not in self.tree:
+                        self.tree.add(id(o))
+                        todo.extend(o._children())
+            if id(obj) not in self.tree:
+                return
+        self.values.clear()
+        self.plots.clear()
+        self.calls.clear()
+
+    def _compute(self, obj: Any, name: str) -> Any:
+        # Kept values do not depend on the layout: the boxes are hidden while one is
+        # resolved, so that `%` of a box stays LAZY.
+        boxes, widths = self.boxes, self.widths
+        try:
+            if boxes or widths:
+                self.boxes, self.widths = {}, {}
+                try:
+                    v = obj._resolve(name, theme=self.theme)
+                finally:
+                    self.boxes, self.widths = boxes, widths
+            else:
+                v = obj._resolve(name, theme=self.theme)
+        except NeedsContext:
+            return LAZY
+        texts = _TEXTS.get(type(obj))
+        if texts is None:
+            texts = _texts(type(obj))
+        if name in texts and v is not None and self.lookup(obj, "markup"):
+            from .markup import check
+            try:
+                check(v)
+            except ValueError as e:
+                raise ValueError(f"{obj.kind} setting {name!r}: {e}") from None
+        return v
+
+
+_TEXTS: dict[type, frozenset[str]] = {}
+
+
+def _texts(cls: type) -> frozenset[str]:
+    """The text settings of settings class ``cls`` whose markup is checked (none without
+    a ``markup`` setting)."""
+    t = _TEXTS.get(cls)
+    if t is None:
+        from .validators import text
+        names = cls.SETTINGS                                       # type: ignore[attr-defined]
+        t = _TEXTS[cls] = frozenset(n for n, s in names.items() if s.check is text) \
+            if "markup" in names else frozenset()
+    return t
+
+
+_CURRENT: contextvars.ContextVar[Render | None] = contextvars.ContextVar("plot_io_render",
+                                                                          default=None)
+
+
+def current() -> Render | None:
+    """The render in progress, if any."""
+    return _CURRENT.get()
+
+
+@contextlib.contextmanager
+def rendering(root: Any) -> Generator[Render]:
+    """A render of ``root`` (a figure).  Inside a render of the same figure, that
+    render."""
+    r = _CURRENT.get()
+    if r is not None and r.root is root:
+        yield r
+        return
+    r = Render(root)
+    token = _CURRENT.set(r)
+    try:
+        yield r
+    finally:
+        _CURRENT.reset(token)
+
+
+_PENDING: contextvars.ContextVar[dict[Any, tuple[str, type[Warning]]] | None] = \
+    contextvars.ContextVar("plot_io_warnings", default=None)
+
+
+def warn(message: str, key: Any = None, category: type[Warning] = UserWarning,
+         stacklevel: int = 2) -> None:
+    """Warn once per layout (:func:`warnings_once`): a warning given again with the same
+    ``key`` (default: the message) replaces the earlier one, so a layout round's later
+    numbers are the ones shown.  Outside a layout, warn at once."""
+    pending = _PENDING.get()
+    if pending is None:
+        warnings.warn(message, category, stacklevel=stacklevel + 1)
+        return
+    pending[message if key is None else key] = (message, category)
+
+
+@contextlib.contextmanager
+def warnings_once() -> Generator[None]:
+    """Collect :func:`warn` calls and give each once at the end (nested: the outermost
+    gives them)."""
+    if _PENDING.get() is not None:
+        yield
+        return
+    pending: dict[Any, tuple[str, type[Warning]]] = {}
+    token = _PENDING.set(pending)
+    try:
+        yield
+    finally:
+        _PENDING.reset(token)
+    for message, category in pending.values():
+        warnings.warn(message, category, stacklevel=4)
+
+
+def set_boxes(obj: Any, **boxes: float) -> None:
+    """The layout boxes `%` of ``obj``'s settings (and its children's) refers to."""
+    r = _CURRENT.get()
+    if r is not None:
+        r.boxes[id(obj)] = boxes
+
+
+def auto_colors(series: Any) -> list[Any] | None:
+    """The plot's colors ``series`` takes in the render in progress (``None``: none)."""
+    r = _CURRENT.get()
+    return None if r is None else r.colors.get(id(series))