plot-io 0.1.0__py3-none-any.whl

plot_io/labels.py

@@ -0,0 +1,63 @@
+"""Value labels on bars, histogram bins and pie wedges."""
+
+from typing import Any
+
+from .settings import one_of
+from .text import Font, draw_text, measure
+
+__all__ = ["check_labels", "ink_for", "bar_labels"]
+
+
+def check_labels(v: Any) -> Any:
+    if v is True:
+        return "outside"
+    if v is False or v is None:
+        return False
+    return one_of("inside", "outside", "center")(v)
+
+
+def luminance(c: Any) -> float:
+    if c is None:
+        return 1.0
+    from pdf_io.colors import to_rgba
+    rgba = to_rgba(c)
+    if rgba is None:
+        return 1.0
+    r, g, b = (float(x) for x in rgba[:3])
+    a = float(rgba[3]) if len(rgba) > 3 else 1.0
+    lum = 0.2126 * r + 0.7152 * g + 0.0722 * b
+    return a * lum + (1.0 - a)            # over a white background
+
+
+def ink_for(fill: Any) -> str:
+    """Black or white, whichever contrasts more with ``fill``."""
+    return "black" if luminance(fill) > 0.45 else "white"
+
+
+def bar_labels(canvas: Any, rects: list[tuple[float, float, float, float, bool]],
+               texts: list[Any], fills: list[Any], where: str, horizontal: bool,
+               font: Font, pad: float = 2.0) -> None:
+    """Labels of bars ``(x0, y0, x1, y1, negative)`` (page units): ``outside`` beyond the
+    bar's end, ``inside`` just within it, ``center`` in its middle."""
+    for (x0, y0, x1, y1, negative), text, fill in zip(rects, texts, fills):
+        if text is None or text == "":
+            continue
+        inner = where in ("inside", "center")
+        f = Font(font.size, font.family, font.weight, font.style,
+                 ink_for(fill) if inner else font.color)
+        if where == "center":
+            draw_text(canvas, text, (x0 + x1) / 2, (y0 + y1) / 2, f, "center", "center")
+            continue
+        if horizontal:
+            end = x0 if negative else x1
+            out = (where == "outside") != negative
+            ha = "left" if out else "right"
+            draw_text(canvas, text, end + (pad if out else -pad), (y0 + y1) / 2, f, ha, "center")
+        else:
+            end = y1 if negative else y0
+            up = (where == "outside") != negative
+            if up:
+                draw_text(canvas, text, (x0 + x1) / 2, end - pad, f, "center", "bottom")
+            else:
+                w, a, d = measure(canvas, text, f)
+                draw_text(canvas, text, (x0 + x1) / 2, end + pad, f, "center", "top")

plot_io/legend.py

@@ -0,0 +1,498 @@
+"""Legend layout and drawing: one entry per named series."""
+
+import math
+from typing import Any
+
+from .style import resolve_color, with_alpha
+from .text import Font, draw_text, measure
+
+__all__ = ["LegendState", "SizeKey", "size_key_values"]
+
+#: Inside candidates of ``position="auto"``, in order of preference (ties go to the first).
+CANDIDATES = ("top right", "top left", "bottom left", "bottom right", "top", "bottom",
+              "center right", "center left")
+#: ``"auto"`` puts the legend outside right when every inside position covers more than
+#: this fraction of drawn cells.
+OUTSIDE_THRESHOLD = 0.02
+
+
+def size_key_values(smap: Any, flo: float, fhi: float, given: Any = None) -> list[float]:
+    """Values shown in a size key: ``given``, else 3–5 nice numbers inside the map's
+    limits (``flo``/``fhi`` after its scale function)."""
+    from .scales import get_scale
+    from .ticks import numeric_ticks
+    if isinstance(given, (list, tuple)):
+        return [float(v) for v in given]
+    scale = get_scale(smap.scale)
+    lo, hi = sorted((scale.inverse(flo), scale.inverse(fhi)))
+    eps = (hi - lo) * 1e-9
+    vals: list[float] = []
+    for most in (4, 5, 6, 8):
+        ticks, _ = numeric_ticks(scale, lo, hi, most, minor=False, length=100.0)
+        vals = [t.value for t in ticks if t.major and lo - eps <= t.value <= hi + eps
+                and (t.value > 0 or scale.name != "linear" or lo <= 0)]
+        if len(vals) >= 3:
+            break
+    return vals if len(vals) >= 2 else [lo, hi]
+
+
+class SizeKey:
+    """Entries of a size key: a header (the map's label) and sample markers."""
+
+    header = False
+
+    def __init__(self, smap: Any, series: list[Any], values: list[float], labels: list[Any],
+                 title: Any) -> None:
+        self.smap = smap
+        self.series = series
+        self.values = values
+        self.labels = labels
+        self.title = title
+
+    def sizes(self, ctx: Any) -> list[float]:
+        from . import _backend
+        from .markers import area_factor
+        from .scales import get_scale
+        flo, fhi = ctx.maps[id(self.smap)][:2]
+        d = self.smap.map(_backend.doubles(self.values), flo, fhi,
+                          get_scale(self.smap.scale).function)
+        s = self.series[0]
+        marker = s.get("marker") if "marker" in s.SETTINGS else "circle"
+        marker = marker[0] if isinstance(marker, list) else marker
+        factor = area_factor(marker) if s.get("size_basis") == "area" else 1.0
+        return [v * factor if v == v else 0.0 for v in d]
+
+    def glyph(self, ctx: Any, i: int, x: float, y: float, w: float, h: float) -> None:
+        from .markers import resolve
+        s = self.series[0]
+        size = self.sizes(ctx)[i]
+        if not size:
+            return
+        marker = s.get("marker") if "marker" in s.SETTINGS else "circle"
+        marker = marker[0] if isinstance(marker, list) else marker
+        from .values import Values, is_computed
+        mapped = any(isinstance(s.get(n), Values) or is_computed(s.get(n))
+                     for n in ("color", "line_color") if n in s.SETTINGS)
+        if len(self.series) == 1 and not mapped:
+            from .series.points import MarkerStyle
+            st = MarkerStyle(s, ctx, "", s.base_color(ctx), 1, True)
+            fill, stroke, lw = st.first_color("fill"), st.first_color("stroke"), st.line_width
+            if fill is None and stroke is None:
+                fill = s.base_color(ctx)
+        else:
+            fill, stroke, lw = "#888888", None, None
+        ctx.canvas.draw_markers([x + w / 2], [y + h / 2], marker=resolve(marker)[0],
+                                size=size, fill=fill, stroke=stroke, line_width=lw)
+
+
+class _Header:
+    header = True
+
+
+class LegendState:
+    """A plot's legend while drawing."""
+
+    def __init__(self, plot_state: Any) -> None:
+        self.ps = plot_state
+        self.legend = plot_state.plot.legend
+        plot = plot_state.plot
+        own = list(plot.series)
+        if getattr(plot, "twin_of", None) and not plot.legend.is_set("position"):
+            own = []                             # listed in the main plot's legend
+        for t in getattr(plot, "twins", []):
+            if not t.legend.is_set("position"):
+                own += list(t.series)
+        self.entries = [(s, label, i) for s in own + list(plot.decorations)
+                        for i, label in enumerate(s.legend_labels())]
+        self.keys = self._size_keys(plot_state)
+        for key in self.keys:
+            if key.title is not None:
+                self.entries.append((_Header(), key.title, 0))
+            self.entries.extend((key, lab, i) for i, lab in enumerate(key.labels))
+        self.size = (0.0, 0.0)
+        self._cols: list[float] = []
+        self._rows = 0
+        self._heights: list[float] = []
+        self._title_h = 0.0
+        #: The position chosen for ``"auto"`` once the axes are known (see :meth:`choose`).
+        self.choice: str | None = None
+        self.free: tuple[float, float] = (0.0, 0.0)
+
+    def _size_keys(self, ps: Any) -> list[SizeKey]:
+        """Size keys of the plot's series with a ``size_map`` (one per map)."""
+        from .numbers import format_numbers
+        by_map: dict[int, list[Any]] = {}
+        maps: dict[int, Any] = {}
+        for s in ps.plot.series:
+            m = s.size_map_obj() if hasattr(s, "size_map_obj") else None
+            if m is None or ("size_legend" in s.SETTINGS and s.get("size_legend") is False):
+                continue
+            by_map.setdefault(id(m), []).append(s)
+            maps[id(m)] = m
+        keys = []
+        for k, members in by_map.items():
+            m = maps[k]
+            if k not in ps.maps:
+                continue
+            flo, fhi = ps.maps[k][:2]
+            given = members[0].get("size_legend") if "size_legend" in members[0].SETTINGS \
+                else None
+            values = size_key_values(m, flo, fhi, given)
+            labels = format_numbers(values, "auto", ps.plot)
+            title = m.label
+            if title is None:
+                title = next((s.columns["size"] for s in members
+                              if "size" in getattr(s, "columns", {})), None)
+            keys.append(SizeKey(m, members, values, labels, title))
+        return keys
+
+    def font(self) -> Font:
+        g = self.legend
+        return Font(g.get("font_size"), g.get("font_family"), color=g.get("color"))
+
+    def active(self) -> bool:
+        return bool(self.entries) and self.legend.get("position") != "none"
+
+    def position(self) -> str:
+        """The position setting, with ``"auto"`` replaced by its choice once made."""
+        pos = self.legend.get("position")
+        return self.choice if pos == "auto" and self.choice else pos
+
+    def horizontal(self) -> bool:
+        o = self.legend.get("orientation")
+        if o == "auto":
+            # The setting, not an ``"auto"`` choice: the box was measured before choosing.
+            return self.legend.get("position") in ("top", "bottom", "outside top",
+                                                   "outside bottom")
+        return o == "horizontal"
+
+    def outside(self) -> str | None:
+        pos = self.position()
+        return pos if self.active() and pos.startswith("outside") else None
+
+    def _metrics(self) -> tuple[float, float, float, float]:
+        fs = self.font().size
+        g = self.legend
+        return (g.get("glyph_width") * fs, 0.5 * fs, g.get("row_height") * fs,
+                (0.5 * fs if g.get("frame") else 0.15 * fs))
+
+    def _ctx(self) -> Any:
+        """A context for size computations (the maps)."""
+        class _C:
+            maps = self.ps.maps
+        return _C()
+
+    def measure(self, canvas: Any) -> tuple[float, float]:
+        if not self.active():
+            self.size = (0.0, 0.0)
+            return self.size
+        font = self.font()
+        glyph, gap, row, inner = self._metrics()
+        n = len(self.entries)
+        cols = min(self.legend.get("columns"), n)
+        if self.horizontal() and not self.legend.is_set("columns"):
+            cols = n
+        rows = math.ceil(n / cols)
+        widths = [0.0] * cols
+        self._heights = [row] * rows
+        for i, (s, label, k) in enumerate(self.entries):
+            c, r = divmod(i, rows)
+            lw = measure(canvas, label, font)[0]
+            if getattr(s, "header", False):
+                lw -= glyph + gap
+            widths[c] = max(widths[c], lw)
+            if isinstance(s, SizeKey):
+                self._heights[r] = max(self._heights[r], 1.15 * s.sizes(self._ctx())[k])
+        self._cols = [glyph + gap + w for w in widths]
+        self._rows = rows
+        w = sum(self._cols) + font.size * (cols - 1)
+        title = self.legend.get("title")
+        self._title_h = 0.0
+        if title is not None:
+            tw, a, d = measure(canvas, title, font)
+            w = max(w, tw)
+            self._title_h = a + d + 0.3 * font.size
+        h = self._title_h + sum(self._heights)
+        self.size = (w + 2 * inner, h + 2 * inner)
+        return self.size
+
+    def _place(self, ctx: Any) -> tuple[float, float]:
+        """Top-left corner of the legend box."""
+        x0, y0, x1, y1 = ctx.rect
+        w, h = self.size
+        pad = self.legend.get("pad")
+        pos = self.position()
+        if pos == "outside right":
+            return x1 + self.ps._right_used + pad, y0
+        if pos == "outside top":
+            return (x0 + x1 - w) / 2 if self.horizontal() else x0, y0 - pad - h
+        if pos == "outside bottom":
+            return ((x0 + x1 - w) / 2 if self.horizontal() else x0,
+                    y1 + self.ps._bottom_used + pad)
+        if pos == "auto":
+            pos = self.choose(ctx, outside=False)
+        return self._box(ctx, pos)
+
+    def _box(self, ctx: Any, pos: str) -> tuple[float, float]:
+        """Top-left corner of the legend box at an inside position."""
+        x0, y0, x1, y1 = ctx.rect
+        w, h = self.size
+        pad = self.legend.get("pad")
+        if pos == "inside":
+            fx, fy = self.free
+            return (x0 + pad + fx * max(0.0, x1 - x0 - 2 * pad - w),
+                    y0 + pad + fy * max(0.0, y1 - y0 - 2 * pad - h))
+        vertical, _, horizontal = pos.partition(" ")
+        if pos in ("top", "bottom"):
+            vertical, horizontal = pos, "center"
+        x = {"left": x0 + pad, "right": x1 - pad - w, "center": (x0 + x1 - w) / 2}[horizontal]
+        y = {"top": y0 + pad, "bottom": y1 - pad - h, "center": (y0 + y1 - h) / 2}[vertical]
+        return x, y
+
+    def choose(self, ctx: Any, outside: bool = True) -> str:
+        """The position for ``"auto"``, from the occupancy grid (every series marks what it
+        draws: points, lines, bars, areas, …):
+
+        1. the first candidate (``CANDIDATES``) whose box covers no drawn cell;
+        2. else the free box (one grid cell apart, anywhere inside) nearest to a corner of
+           the axes (``"inside"``, its place kept as fractions of the free room);
+        3. else ``"outside right"`` (when ``outside``) if every candidate covers more than
+           ``OUTSIDE_THRESHOLD``; else the candidate covering the fewest cells."""
+        from .occupancy import Occupancy
+
+        occ = Occupancy(ctx.rect)
+        for s in self.ps.series:
+            s.occupy(ctx, occ)
+        from .series import DrawContext
+        for t in getattr(self.ps, "twins", []):
+            tctx = DrawContext(ctx.canvas, t.plot, ctx.rect, t.x, t.y, t.maps, t.palette)
+            for s in t.series:
+                s.occupy(tctx, occ)
+        w, h = self.size
+        best, best_f = CANDIDATES[0], math.inf
+        for pos in CANDIDATES:
+            x, y = self._box(ctx, pos)
+            f = occ.covered(x, y, w, h)
+            if f == 0.0:
+                return pos
+            if f < best_f - 1e-12:
+                best, best_f = pos, f
+        x0, y0, x1, y1 = ctx.rect
+        pad = self.legend.get("pad")
+        free = occ.free_boxes(w, h, pad)
+        if free:
+            def corner(p: tuple[float, float]) -> float:
+                x, y = p
+                return min(x - x0, x1 - x - w) + min(y - y0, y1 - y - h)
+            x, y = min(free, key=corner)
+            room_x, room_y = x1 - x0 - 2 * pad - w, y1 - y0 - 2 * pad - h
+            self.free = ((x - x0 - pad) / room_x if room_x > 0 else 0.0,
+                         (y - y0 - pad) / room_y if room_y > 0 else 0.0)
+            return "inside"
+        if outside and best_f > OUTSIDE_THRESHOLD:
+            return "outside right"
+        return best
+
+    def draw(self, canvas: Any, ctx: Any) -> None:
+        if not self.active() or not self.size[0]:
+            return
+        x, y = self._place(ctx)
+        w, h = self.size
+        font = self.font()
+        glyph, gap, row, inner = self._metrics()
+        g = self.legend
+        if g.get("frame"):
+            alpha = g.get("frame_alpha")
+            bg = with_alpha(resolve_color(g.get("background"), ctx.palette), alpha)
+            fc = with_alpha(resolve_color(g.get("frame_color"), ctx.palette), alpha)
+            canvas.save()
+            canvas.begin_path()
+            r = min(g.get("frame_radius"), w / 2, h / 2)
+            if r:
+                canvas.rounded_rect(x, y, w, h, r)
+            else:
+                canvas.rect(x, y, w, h)
+            if bg is not None:
+                canvas.fill(bg)
+            if fc is not None and g.get("frame_width"):
+                canvas.line_width = g.get("frame_width")
+                canvas.stroke(fc)
+            canvas.restore()
+        cx, cy = x + inner, y + inner
+        title = self.legend.get("title")
+        if title is not None:
+            draw_text(canvas, title, cx, cy, font, "left", "top")
+            cy += self._title_h
+        for i, (s, label, k) in enumerate(self.entries):
+            c, r = divmod(i, self._rows)
+            ex = cx + sum(self._cols[:c]) + font.size * c
+            ey = cy + sum(self._heights[:r])
+            rh = self._heights[r]
+            if getattr(s, "header", False):
+                draw_text(canvas, label, ex, ey + rh / 2, font, "left", "center")
+                continue
+            if isinstance(s, SizeKey):
+                canvas.save()
+                try:
+                    s.glyph(ctx, k, ex, ey, glyph, rh)
+                finally:
+                    canvas.restore()
+                draw_text(canvas, label, ex + glyph + gap, ey + rh / 2, font, "left", "center")
+                continue
+            ey += (rh - row) / 2
+            canvas.save()
+            try:
+                kind = g.get("glyph")
+                if kind == "series":
+                    s.legend_glyph_at(ctx, k, ex, ey + 0.1 * row, glyph, 0.8 * row)
+                else:
+                    _simple_glyph(ctx, s, k, kind, ex, ey + 0.1 * row, glyph, 0.8 * row)
+            finally:
+                canvas.restore()
+            draw_text(canvas, label, ex + glyph + gap, ey + row / 2, font, "left", "center")
+
+
+def _opaque(c: Any) -> Any:
+    if c is None:
+        return None
+    from pdf_io.colors import to_rgba
+    rgba = to_rgba(c)
+    return None if rgba is None else (rgba[0], rgba[1], rgba[2], 1.0)
+
+
+def _simple_glyph(ctx: Any, series: Any, k: int, kind: str, x: float, y: float, w: float,
+                  h: float) -> None:
+    """A legend symbol in the series' colors: a filled box, a circle or a line."""
+    canvas = ctx.canvas
+    fill, stroke = series.legend_colors_at(ctx, k)
+    alpha = ctx.plot.legend.get("glyph_alpha")
+    if alpha is not None and kind != "line":
+        base = _opaque(fill if fill is not None else stroke)
+        if base is not None:
+            fill, stroke = with_alpha(base, alpha), (stroke if stroke is not None else base)
+    if kind == "line":
+        c = stroke if stroke is not None else fill
+        if c is not None:
+            canvas.draw_lines([x, x + w], [y + h / 2, y + h / 2], color=c,
+                              width=min(1.5, h / 3))
+        return
+    if kind == "circle":
+        d = 0.75 * h
+        canvas.draw_markers([x + w / 2], [y + h / 2], size=d, fill=fill, stroke=stroke,
+                            line_width=1.0 if stroke is not None else None)
+        return
+    canvas.begin_path()
+    canvas.rect(x, y + 0.1 * h, w, 0.8 * h)
+    if fill is not None:
+        canvas.fill(fill)
+    if stroke is not None:
+        canvas.line_width = 1.0
+        canvas.stroke(stroke)
+
+
+class SizeLegend:
+    """A size key in its own grid area (``figure.size_legend(size_map, id=…)``)."""
+
+    def __init__(self, size_map: Any, figure: Any, values: Any = None, font_size: Any = None,
+                 title: Any = None) -> None:
+        from .maps import SizeMap
+        if not isinstance(size_map, SizeMap):
+            raise ValueError("a size legend needs a SizeMap")
+        self.size_map = size_map
+        self.figure = figure
+        self.values = None if values is None else [float(v) for v in values]
+        self.font_size = font_size
+        self.title = title
+        self.id: Any = None
+
+    def __repr__(self) -> str:
+        return f"SizeLegend({self.size_map!r})"
+
+
+class SizeLegendState:
+    """A size legend area while drawing (the colorbar-area interface of the layout)."""
+
+    vertical = True
+
+    def __init__(self, sl: SizeLegend, maps: dict[int, tuple]) -> None:
+        from .numbers import format_numbers
+        from .plot import Plot
+        self.sl = sl
+        fig = sl.figure
+        self.maps = maps
+        m = sl.size_map
+        users = [s for p in fig.plots for s in p.series
+                 if hasattr(s, "size_map_obj") and s.size_map_obj() is m]
+        self.key = None
+        self.thickness = 1.0
+        if id(m) in maps and users:
+            flo, fhi = maps[id(m)][:2]
+            values = size_key_values(m, flo, fhi, sl.values)
+            labels = format_numbers(values, "auto", users[0].plot if isinstance(
+                users[0].plot, Plot) else None)
+            title = sl.title if sl.title is not None else m.label
+            self.key = SizeKey(m, users, values, labels, title)
+        size = sl.font_size or fig.get("font_size")
+        self.font = Font(size, fig.get("font_family"), color=fig.get("text_color"))
+        self._layout: list[tuple[str, Any, float]] = []
+
+    def _ctx(self) -> Any:
+        class _C:
+            maps = self.maps
+        return _C()
+
+    def measure(self, canvas: Any, w: float, h: float) -> tuple[float, float, float, float]:
+        if self.key is None:
+            return (0.0, 0.0, 0.0, 0.0)
+        fs = self.font.size
+        glyph, gap, row = 2.0 * fs, 0.5 * fs, 1.35 * fs
+        sizes = self.key.sizes(self._ctx())
+        width = 0.0
+        rows: list[tuple[str, Any, float]] = []
+        if self.key.title is not None:
+            width = measure(canvas, self.key.title, self.font)[0]
+            rows.append(("title", self.key.title, row))
+        g = max([glyph] + [1.1 * s for s in sizes])
+        for lab, s in zip(self.key.labels, sizes):
+            width = max(width, g + gap + measure(canvas, lab, self.font)[0])
+            rows.append(("entry", lab, max(row, 1.15 * s)))
+        self._layout = rows
+        self._glyph = g
+        self.thickness = width
+        return (0.0, 0.0, 0.0, 0.0)
+
+    def bar_rect(self, rect: tuple[float, float, float, float]) -> tuple:
+        x0, y0, x1, y1 = rect
+        return (x0, y0, min(x1, x0 + self.thickness), y1)
+
+    def draw_area(self, canvas: Any, rect: tuple[float, float, float, float]) -> None:
+        if self.key is None:
+            return
+        from .palettes import palette_colors
+        from .style import resolve_color
+        x0, y = rect[0], rect[1]
+        fs = self.font.size
+        plot = self.key.series[0].plot
+        palette = palette_colors(plot.get("palette"), 10)
+
+        class _Ctx:
+            maps = self.maps
+
+            def color(self, value: Any) -> Any:
+                return resolve_color(value, palette)
+        ctx: Any = _Ctx()
+        ctx.canvas, ctx.palette, ctx.plot = canvas, palette, plot
+        i = 0
+        for kind, lab, h in self._layout:
+            if kind == "title":
+                draw_text(canvas, lab, x0, y + h / 2, self.font, "left", "center")
+            else:
+                canvas.save()
+                try:
+                    self.key.glyph(ctx, i, x0, y, self._glyph, h)
+                finally:
+                    canvas.restore()
+                draw_text(canvas, lab, x0 + self._glyph + 0.5 * fs, y + h / 2, self.font,
+                          "left", "center")
+                i += 1
+            y += h

plot_io/limits.py

@@ -0,0 +1,92 @@
+"""Limits: ``"auto"``, ``"lo/hi"`` strings (``min``, ``max``, numbers, ``q:F``) or pairs."""
+
+import math
+from collections.abc import Callable, Sequence
+from typing import Any
+
+__all__ = ["check_limits", "resolve_limits"]
+
+
+def _side(token: str) -> Any:
+    t = token.strip().lower()
+    if t in ("min", "max", "auto", ""):
+        return "auto" if t in ("auto", "") else t
+    if t.startswith("q:"):
+        q = float(t[2:])
+        if not 0 <= q <= 1:
+            raise ValueError(f"quantile {q} outside [0, 1]")
+        return ("q", q)
+    try:
+        v = float(t)
+    except ValueError:
+        import datetime as dt
+        from .times import seconds
+        try:
+            v = seconds(dt.datetime.fromisoformat(token.strip()))
+        except ValueError:
+            raise ValueError(f"invalid limit {token!r}") from None
+    if not math.isfinite(v):
+        raise ValueError(f"invalid limit {token!r}")
+    return v
+
+
+def check_limits(v: Any) -> Any:
+    """Normalize a limits value to ``"auto"`` or a pair of sides (``None``/``"auto"``, a
+    number, ``"min"``, ``"max"``, ``("q", F)``)."""
+    if isinstance(v, str):
+        s = v.strip().lower()
+        if s == "auto":
+            return "auto"
+        parts = s.split("/")
+        if len(parts) != 2:
+            raise ValueError(f"expected 'lo/hi', got {v!r}")
+        return (_side(parts[0]), _side(parts[1]))
+    if isinstance(v, (tuple, list)) and len(v) == 2:
+        out: list[Any] = []
+        for side in v:
+            if side is None:
+                out.append("auto")
+            elif isinstance(side, str):
+                out.append(_side(side))
+            elif isinstance(side, (int, float)) and not isinstance(side, bool) \
+                    and math.isfinite(side):
+                out.append(float(side))
+            elif hasattr(side, "year"):                  # a date or datetime
+                from .times import seconds
+                out.append(seconds(side))
+            else:
+                raise ValueError(f"invalid limit {side!r}")
+        return tuple(out)
+    raise ValueError(f"expected 'auto', 'lo/hi' or (lo, hi), got {v!r}")
+
+
+def resolve_limits(spec: Any, lo: float, hi: float,
+                   quantile: Callable[[float], float] | None = None) -> tuple[Any, Any, bool, bool]:
+    """``(lo, hi, lo_auto, hi_auto)`` from a limits spec and the data range; ``*_auto``
+    tells whether that side follows the data (and takes padding)."""
+    sides = ("auto", "auto") if spec == "auto" else spec
+    out: list[Any] = []
+    autos: list[bool] = []
+    for side, data in zip(sides, (lo, hi)):
+        if side == "auto":
+            out.append(data)
+            autos.append(True)
+        elif side == "min":
+            out.append(lo)
+            autos.append(False)
+        elif side == "max":
+            out.append(hi)
+            autos.append(False)
+        elif isinstance(side, tuple):
+            out.append(quantile(side[1]) if quantile is not None else data)
+            autos.append(False)
+        else:
+            out.append(float(side))
+            autos.append(False)
+    return out[0], out[1], autos[0], autos[1]
+
+
+def needs_quantiles(spec: Any) -> Sequence[float]:
+    if spec == "auto":
+        return ()
+    return [s[1] for s in spec if isinstance(s, tuple)]