plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/units.py

@@ -0,0 +1,768 @@
+"""Setting values: dimensions with units, ``var()`` and CSS math functions (``calc()``,
+``min()``, …: vec_io's grammar, :func:`vec_io.units.parse_math`).
+
+A validator parses a value once, when it is set, into a plain Python value or a
+:class:`Value` (:class:`Dim`, :class:`Var`, :class:`Calc`); :meth:`Settings.get` returns it
+as given and :meth:`Settings.resolve` turns it into px (lengths), degrees (angles) or a
+plain value.
+
+Units: absolute ``px pt pc in cm mm Q``; ``em`` (the object's ``font_size``; in a
+``font_size`` setting, the parent's); ``rem`` (the figure's ``font_size``); ``%`` (of the
+reference each setting declares, :data:`REFERENTS`); ``d`` or ``data`` (data units along an
+axis; on a time axis ``d`` is a day) and durations; ``fr`` (figure widths and heights);
+angles ``deg grad rad turn``.  Bare numbers are px (degrees for angles); positions along
+an axis (a decoration's ``min``/``max``) take bare numbers as data values.
+"""
+
+import re
+import threading
+from typing import TYPE_CHECKING, Any
+
+from vec_io.units import ANGLE_UNITS, PX_PER_UNIT, parse_math
+
+if TYPE_CHECKING:
+    from .validators import Validator
+
+__all__ = ["Value", "Dim", "Fixed", "Var", "Calc", "parse", "given", "resolve_raw",
+           "SettingError", "NeedsContext", "NeedsScale", "explain_tree", "refers_inherit", "FONT_KEYWORDS",
+           "DURATIONS", "REFERENTS", "Expr", "var", "calc"]
+
+ABSOLUTE = frozenset(PX_PER_UNIT)
+DURATIONS = {"ms": 0.001, "s": 1.0, "min": 60.0, "h": 3600.0, "d": 86400.0, "w": 604800.0}
+#: Font-size keywords, relative to the figure's font size (matplotlib's scale).
+FONT_KEYWORDS = {"xx-small": 0.579, "x-small": 0.694, "small": 0.833, "medium": 1.0,
+                 "large": 1.2, "x-large": 1.44, "xx-large": 1.728}
+_RELATIVE_FONT = {"smaller": 1 / 1.2, "larger": 1.2}
+
+
+# ---------------------------------------------------------------------------
+# Values
+# ---------------------------------------------------------------------------
+
+class Value:
+    """A setting value that needs resolving; ``source`` is the text as given."""
+
+    __slots__ = ("source",)
+    source: str
+
+    def __repr__(self) -> str:
+        return repr(self.source)
+
+
+class Dim(Value):
+    """A number with a unit (``""``: bare), or a keyword (``number`` is ``None``)."""
+
+    __slots__ = ("number", "unit")
+
+    def __init__(self, source: str, number: float | None, unit: str) -> None:
+        self.source = source
+        self.number = number
+        self.unit = unit
+
+
+class Fixed(Value):
+    """A value whose final form is known when given (a named color's hex): ``source`` is
+    the text as given, ``value`` the final value."""
+
+    __slots__ = ("value",)
+
+    def __init__(self, source: str, value: Any) -> None:
+        self.source = source
+        self.value = value
+
+    def in_context(self, obj: Any) -> Any:
+        """The final value for a setting of ``obj`` (a named color: in ``obj``'s color
+        variant)."""
+        return self.value
+
+    @property
+    def varies(self) -> bool:
+        """Whether the final value depends on the color variant."""
+        return False
+
+
+def has_fixed(v: Any) -> bool:
+    """Whether ``v`` is or holds (one level) a :class:`Fixed` value, whose final value may
+    depend on the object resolving it."""
+    return isinstance(v, Fixed) or _has_fixed(v)
+
+
+def _has_fixed(v: Any) -> bool:
+    if isinstance(v, dict):
+        v = v.values()
+    elif not isinstance(v, (list, tuple)):
+        return False
+    return any(isinstance(x, Fixed) for x in v)
+
+
+def _fixed_final(v: Any, obj: Any) -> Any:
+    """``v`` with its :class:`Fixed` items replaced by their values for ``obj`` (one
+    level)."""
+    if isinstance(v, dict):
+        return {k: x.in_context(obj) if isinstance(x, Fixed) else x for k, x in v.items()}
+    out = [x.in_context(obj) if isinstance(x, Fixed) else x for x in v]
+    return tuple(out) if isinstance(v, tuple) else out
+
+
+class Var(Value):
+    """``var(name[, fallback])``."""
+
+    __slots__ = ("name", "fallback")
+
+    def __init__(self, source: str, name: str, fallback: str | None) -> None:
+        self.source = source
+        self.name = name
+        self.fallback = fallback
+
+
+class Calc(Value):
+    """A CSS math function (``calc()``, ``min()``, ``clamp()``, …) parsed by vec_io's
+    :func:`~vec_io.units.parse_math`: ``math`` evaluates it; ``refs``: the dimensions and
+    ``var()`` it holds, in order."""
+
+    __slots__ = ("math", "refs")
+
+    def __init__(self, source: str, math: Any, refs: tuple[Value, ...]) -> None:
+        self.source = source
+        self.math = math
+        self.refs = refs
+
+
+
+def given(v: Any) -> Any:
+    """``v`` as it was given: the text of values, containers mapped (copies)."""
+    if isinstance(v, Value):
+        return v.source
+    if isinstance(v, tuple):
+        return tuple(given(x) for x in v)
+    if isinstance(v, list):
+        return [given(x) for x in v]
+    if isinstance(v, dict):
+        return {k: given(x) for k, x in v.items()}
+    return v
+
+
+# ---------------------------------------------------------------------------
+# Parsing
+# ---------------------------------------------------------------------------
+
+#: Units plot_io resolves inside math functions besides the CSS ones.
+_MATH_UNITS = ("data", "fr", *DURATIONS)
+_FUNCTION = re.compile(r"([A-Za-z][\w-]*)\s*\(")
+_NAME = re.compile(r"\s*(--[\w-]+|[A-Za-z_][\w-]*)\s*")
+_SCAN = re.compile(r"""
+    (?P<var>\bvar\s*\(\s*(?P<vname>--[\w-]+|[A-Za-z_][\w-]*))
+  | (?P<name>-*[A-Za-z_][\w-]*)
+  | (?P<num>(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?)(?P<unit>[A-Za-z]+|%)?
+    """, re.X)
+
+
+def _parse_var(s: str, start: int) -> Var:
+    """``var(name[, fallback])``, ``s[start:]`` following its ``(``."""
+    m = _NAME.match(s, start)
+    if m is None:
+        raise ValueError(f"{s}: expected a setting name at {start}")
+    name, pos, fallback = m.group(1), m.end(), None
+    if s.startswith(",", pos):
+        depth, i = 0, pos + 1
+        while i < len(s):
+            if s[i] == "(":
+                depth += 1
+            elif s[i] == ")":
+                if depth == 0:
+                    break
+                depth -= 1
+            i += 1
+        fallback = s[pos + 1:i].strip()
+        if not fallback:
+            raise ValueError(f"{s}: expected a fallback at {i}")
+        pos = i
+    if not s.startswith(")", pos):
+        raise ValueError(f"{s}: expected ')' at {pos}")
+    if s[pos + 1:].strip():
+        raise ValueError(f"{s}: unexpected text after var() at {pos + 1}")
+    return Var(s, name, fallback)
+
+
+#: The longest math function text, and its deepest nesting of parentheses.
+MAX_MATH_LENGTH, MAX_MATH_DEPTH = 1000, 32
+
+
+def _parse_math(s: str, units: frozenset[str] | None) -> Calc:
+    """A math function; ``units``: the units allowed in it (``None``: all)."""
+    if len(s) > MAX_MATH_LENGTH:
+        raise ValueError(f"a math function of at most {MAX_MATH_LENGTH} characters, "
+                         f"got {len(s)}")
+    depth = 0
+    for i, c in enumerate(s):
+        depth += (c == "(") - (c == ")")
+        if depth > MAX_MATH_DEPTH:
+            raise ValueError(f"{s[:20]}…: parentheses nested deeper than {MAX_MATH_DEPTH} "
+                             f"at {i + 1}")
+    math = parse_math(s, units=_MATH_UNITS)
+    refs: list[Value] = []
+    for m in _SCAN.finditer(s):
+        if m["var"]:
+            refs.append(Var(f"var({m['vname']})", m["vname"], None))
+        elif m["name"]:
+            if m["name"].lower() == "inherit":
+                refs.append(Var("inherit", "inherit", None))
+        elif m["unit"]:
+            unit = m["unit"].lower()
+            if units is not None and unit not in units:
+                raise ValueError(f"{s}: unit {unit!r} not allowed here at {m.start()}")
+            refs.append(Dim(m.group(), float(m["num"]), unit))
+    return Calc(s, math, tuple(refs))
+
+
+def parse(text: str, units: frozenset[str] | None = None, calc: bool = True) -> Value | None:
+    """``var(…)`` or ``inherit`` (the parent's value of the same setting), or, when
+    ``calc``, a CSS math function (``calc()``, ``min()``, …; vec_io's grammar), as a
+    :class:`Value`; ``None`` for other text.  ``units``: the units allowed in a math
+    function.  Raises ``ValueError`` naming the position of an error."""
+    s = text.strip()
+    if s.lower() == "inherit":
+        return Var(s, "inherit", None)
+    m = _FUNCTION.match(s)
+    if m is None:
+        return None
+    if m.group(1).lower() == "var":
+        return _parse_var(s, m.end())
+    return _parse_math(s, units) if calc else None
+
+
+
+def refers_inherit(v: Any) -> bool:
+    """Whether a stored value refers to ``inherit``."""
+    if isinstance(v, Var):
+        return v.name == "inherit"
+    if isinstance(v, Calc):
+        return "inherit" in v.math.variables
+    return False
+
+
+# ---------------------------------------------------------------------------
+# ---------------------------------------------------------------------------
+# What % is of
+# ---------------------------------------------------------------------------
+
+#: What ``%`` of a length is of (``length(percent=…)``), besides another setting of the
+#: object: ``{key: (meaning, how)}``.  ``how``: ``"em"`` (the font size ``em`` is of),
+#: ``"box"`` (a layout box, known while the figure is laid out) or ``"given"`` (known
+#: where the setting is used, which passes it as ``of=``).
+REFERENTS: dict[str, tuple[str, str]] = {
+    "em": ("the font size", "em"),
+    "axes_width": ("the axes width", "box"),
+    "axes_height": ("the axes height", "box"),
+    "across": ("the axes side across the axis", "box"),
+    "along": ("the axes side along the axis", "box"),
+    "axes": ("the axes width (across) or height (down)", "given"),
+    "axes_length": ("the axes length along the axis", "given"),
+    "data_range": ("the axis range", "given"),
+    "bar_across": ("the axes side across the colorbar", "given"),
+    "bar_thickness": ("the span along a key, the axes side across a bar", "given"),
+    "bar_along": ("the span along the colorbar (the axes side of an attached one)", "given"),
+    "figure": ("the figure width (across) or height (down)", "given"),
+    "room": ("the plots' room: the figure less its margins, spacing and lanes (and the "
+             "plots' margins with `align=\"axes\"`)", "given"),
+    "slot": ("the slot: one category, or the smallest gap between positions", "given"),
+    "slot_part": ("each series' part of a shared slot", "given"),
+    "box_width": ("the box width", "given"),
+    "radius": ("the radius", "given"),
+}
+
+
+def percent_meaning(ref: Any) -> str | None:
+    """What ``%`` of a length with ``percent=ref`` is of, in words."""
+    if ref is None:
+        return None
+    if ref in REFERENTS:
+        return REFERENTS[ref][0]
+    return f"`{ref}`"
+
+
+# ---------------------------------------------------------------------------
+# Resolution
+# ---------------------------------------------------------------------------
+
+_local = threading.local()
+
+
+def _stack() -> list[tuple[int, str, str]]:
+    s = getattr(_local, "stack", None)
+    if s is None:
+        s = _local.stack = []
+    return s
+
+
+class guard:
+    """Detects reference loops while ``obj.name`` resolves."""
+
+    __slots__ = ("key",)
+
+    def __init__(self, obj: Any, name: str) -> None:
+        self.key = (id(obj), name, f"{obj.kind}.{name}")
+
+    def __enter__(self) -> None:
+        st = _stack()
+        if any(k[:2] == self.key[:2] for k in st):
+            chain = [k[2] for k in st[next(i for i, k in enumerate(st)
+                                         if k[:2] == self.key[:2]):]]
+            st.clear()
+            raise ValueError("reference loop: " + " → ".join(chain + [self.key[2]]))
+        st.append(self.key)
+
+    def __exit__(self, *exc: Any) -> None:
+        st = _stack()
+        if st and st[-1] == self.key:
+            st.pop()
+
+
+class Expr(str):
+    """A setting value written with ``var()`` or ``calc()`` (made by :func:`var` and
+    :func:`calc`): the type of such values in the typed API, where a plain string is
+    flagged for a number, a boolean or a choice."""
+
+    __slots__ = ()
+
+
+def var(name: str, fallback: Any = None) -> Expr:
+    """``var(name)``, or ``var(name, fallback)``: the value of setting ``name`` (or custom
+    variable ``--name``) of the object or its parents."""
+    return Expr(f"var({name})" if fallback is None else f"var({name}, {fallback})")
+
+
+def calc(expression: Any) -> Expr:
+    """``calc(expression)``: CSS math of numbers, lengths, angles, ``var()`` and
+    ``inherit``."""
+    return Expr(f"calc({expression})")
+
+
+class SettingError(ValueError):
+    """A value a setting does not take, found when it is set or resolved: ``owner``, the
+    object whose setting it is; ``name``, the setting; ``value``, the value as given."""
+
+    def __init__(self, message: str, owner: Any = None, name: str | None = None,
+                 value: Any = None) -> None:
+        super().__init__(message)
+        self.owner = owner
+        self.name = name
+        self.value = value
+
+
+class NeedsContext(SettingError):
+    """A value that needs what only its use provides: the reference of ``%``, a layout
+    box, an axis scale (it stays unresolved in a render's spec)."""
+
+
+class NeedsScale(NeedsContext):
+    """A length in px resolved in data units before the axis scale is known."""
+
+
+class Context:
+    """What one resolution needs besides the object: ``of`` (the reference of ``%``),
+    ``scale`` (px per data unit), ``time`` (durations accepted), ``unit`` (``"px"`` or
+    ``"data"``: the unit of the result)."""
+
+    __slots__ = ("obj", "name", "check", "of", "scale", "time", "unit", "raw")
+
+    def __init__(self, obj: Any, name: str, check: "Validator", of: Any, scale: Any,
+                 time: bool, unit: str, raw: Any = None) -> None:
+        self.obj, self.name, self.check = obj, name, check
+        self.of, self.scale, self.time, self.unit = of, scale, time, unit
+        self.raw = raw
+
+    def error(self, msg: str, context: bool = False) -> SettingError:
+        cls = NeedsContext if context else SettingError
+        return cls(f"{self.obj.kind} setting {self.name!r}: {msg}", self.obj, self.name,
+                   given(self.raw))
+
+
+def _scaling(ctx: Context) -> float:
+    if not ctx.check.scaled:
+        return 1.0
+    return ctx.obj._scaling()
+
+
+def _px_to_unit(px: float, ctx: Context) -> float:
+    if ctx.unit == "data":
+        if not ctx.scale:
+            raise NeedsScale(f"{ctx.obj.kind} setting {ctx.name!r}: a length in px needs "
+                             f"the axis scale here")
+        return px / ctx.scale
+    return px
+
+
+def _data_to_unit(d: float, ctx: Context) -> float:
+    if ctx.unit == "data":
+        return d
+    if ctx.scale is None:
+        raise ctx.error("data units are only valid along a linear or category axis", True)
+    return d * ctx.scale
+
+
+def _percent_ref(ctx: Context) -> float:
+    if ctx.of is not None:
+        return float(ctx.of)
+    ref = ctx.check.percent
+    if ref is None:
+        raise ctx.error("% is not accepted")
+    if ref in REFERENTS and REFERENTS[ref][1] == "given":
+        raise ctx.error("% needs a reference here", True)
+    if ref == "em":
+        return _px_to_unit(_em(ctx), ctx)
+    if ref in REFERENTS and REFERENTS[ref][1] == "box":
+        return _px_to_unit(ctx.obj._box(ref, ctx.name), ctx)
+    return ctx.obj.resolve(ref)
+
+
+def _em(ctx: Context) -> float:
+    obj = ctx.obj
+    basis = ctx.check.em
+    if basis is not None:
+        return obj.resolve(basis)
+    if ctx.name == "font_size":
+        return obj._parent_font_size()
+    return obj._font_size()
+
+
+def _dim(d: Dim, ctx: Context) -> float:
+    n, u = d.number, d.unit
+    if n is None:                                 # font keyword
+        if u in _RELATIVE_FONT:
+            return _px_to_unit(_em(ctx) * _RELATIVE_FONT[u], ctx)
+        return _px_to_unit(ctx.obj._root_font_size() * FONT_KEYWORDS[u], ctx)
+    if u in ABSOLUTE:
+        return _px_to_unit(n * PX_PER_UNIT[u] * _scaling(ctx), ctx)
+    if u == "em":
+        return _px_to_unit(n * _em(ctx), ctx)
+    if u == "rem":
+        return _px_to_unit(n * ctx.obj._root_font_size(), ctx)
+    if u == "%":
+        return n / 100.0 * _percent_ref(ctx)
+    if u == "data":
+        return _data_to_unit(n, ctx)
+    if u == "d" and not ctx.time:                 # data units (a day on a time axis)
+        return _data_to_unit(n, ctx)
+    if u in DURATIONS:
+        if not ctx.time:
+            raise ctx.error(f"a duration ({d.source!r}) needs a time axis", True)
+        return _data_to_unit(n * DURATIONS[u], ctx)
+    if u in ANGLE_UNITS:
+        return n * ANGLE_UNITS[u]
+    if u == "fr":
+        raise ctx.error("fr units are only valid in figure widths and heights")
+    raise ctx.error(f"unknown unit {u!r}")
+
+
+def _bare(n: float, ctx: Context) -> float:
+    if ctx.check.kind != "length":
+        return n
+    if ctx.check.bare == "data":
+        return _data_to_unit(n, ctx)
+    return _px_to_unit(n * _scaling(ctx), ctx)
+
+
+def _var(v: Var, ctx: Context, checked: bool = True) -> Any:
+    """The value ``v`` refers to: as a value of this setting (``checked``), else as the
+    referred setting has it (a ``calc()`` operand)."""
+    obj = ctx.obj
+    if v.name.startswith("--"):
+        raw = obj._custom_var(v.name)
+        if raw is None:
+            if v.fallback is None:
+                raise ctx.error(f"unknown variable {v.name!r}")
+            raw = v.fallback
+        with guard(obj, v.name):
+            return _from_text(raw, ctx)
+    if v.name == ctx.name or v.name == "inherit":
+        if not obj._inherits(ctx.name):
+            if v.fallback is None:
+                raise ctx.error(f"{v.source}: no parent of {obj.kind} and no style has "
+                                f"{ctx.name!r}")
+            return _from_text(v.fallback, ctx)
+        out = obj._parent_value(ctx.name)
+        target = obj._check_of(ctx.name, own=False)
+    else:
+        out = obj._resolve_any(v.name)
+        target = obj._check_of(v.name)
+    if out is None:
+        return None if v.fallback is None else _from_text(v.fallback, ctx)
+    return _take(v, out, target, ctx) if checked else out
+
+
+def _take(v: Var, out: Any, target: "Validator | None", ctx: Context) -> Any:
+    """``out``, the final value of the setting ``v`` refers to (checked by ``target``;
+    ``None``: a style's bare value), as a value of this setting."""
+    check = ctx.check
+    ok = None if target is None else check.accepts(target)
+    if ok:
+        return out if target is check else check.finish(out, ctx)
+    if ok is False:
+        assert target is not None
+        raise ctx.error(f"{v.source} is {target.noun}, expected {check.noun}")
+    try:
+        raw = check(out)
+    except (TypeError, ValueError) as e:
+        raise ctx.error(f"{v.source} is {out!r}: {e}") from None
+    return resolve_value(raw, ctx)
+
+
+def _from_text(raw: Any, ctx: Context) -> Any:
+    """A custom variable or fallback, checked and resolved as a value of this setting."""
+    try:
+        raw = ctx.check(raw)
+    except (TypeError, ValueError) as e:
+        raise ctx.error(str(e)) from None
+    return resolve_value(raw, ctx)
+
+
+def _finite(x: float, ctx: Context) -> float:
+    if x - x != 0:                                # inf or NaN
+        raise ctx.error(f"{given(ctx.raw)} gives {x} (not finite)")
+    return x
+
+
+#: The unit of a ``var()`` value inside a math function: the setting's own unit.
+_FINAL = "="
+
+
+def _calc(c: "Calc", ctx: Context) -> tuple[float, bool]:
+    """Value of a math function and whether it is a dimension (length or angle)."""
+    per: dict[str, float] = {}
+
+    def final(unit: str) -> float:
+        """One ``unit`` in the setting's unit."""
+        if unit not in per:
+            per[unit] = 1.0 if unit == _FINAL else _dim(Dim(f"1{unit}", 1.0, unit), ctx)
+        return per[unit]
+
+    def px(unit: str) -> float:
+        return final(unit) / final("px")
+
+    def var(name: str, fallback: str | None) -> Any:
+        v = Var(name if name == "inherit" and fallback is None else
+                f"var({name})" if fallback is None else f"var({name}, {fallback})",
+                name, fallback)
+        out = _var(v, ctx, checked=False)
+        if isinstance(out, bool) or not isinstance(out, (int, float)):
+            raise ctx.error(f"{v.source} is not a number ({out!r})")
+        if name.startswith("--") or name in (ctx.name, "inherit"):
+            kind = ctx.check.kind
+        else:
+            target = ctx.obj._check_of(name)
+            kind = None if target is None else target.kind
+        x = _finite(float(out), ctx)
+        return {"deg": x} if kind == "angle" else {_FINAL: x} if kind == "length" else x
+
+    try:
+        value = c.math.evaluate(px, var)
+    except SettingError:
+        raise
+    except (ValueError, ZeroDivisionError) as e:
+        raise ctx.error(str(e)) from None
+    for x in value.values():
+        _finite(x, ctx)
+    if "" in value:
+        if len(value) > 1:
+            raise ctx.error(f"{c.source} adds a dimension and a plain number")
+        return value[""], False
+    return _finite(sum(x * final(u) for u, x in value.items()), ctx), True
+
+
+def resolve_value(raw: Any, ctx: Context) -> Any:
+    """The final value of ``raw`` (a stored value of ``ctx.name``)."""
+    check = ctx.check
+    kind = check.kind
+    if isinstance(raw, Fixed):
+        return raw.in_context(ctx.obj)
+    if isinstance(raw, Var):
+        return _var(raw, ctx)
+    if isinstance(raw, Calc):
+        x, is_dim = _calc(raw, ctx)
+        if kind == "length" and not is_dim:
+            x = _bare(x, ctx)
+        return check.finish(x, ctx)
+    if isinstance(raw, Dim):
+        return check.finish(_dim(raw, ctx), ctx)
+    if kind is not None and isinstance(raw, (int, float)) and not isinstance(raw, bool):
+        return _bare(float(raw), ctx)
+    inner = check.inner
+    if inner is not None and isinstance(raw, (tuple, list)):
+        sub = Context(ctx.obj, ctx.name, inner, ctx.of, ctx.scale, ctx.time, ctx.unit,
+                      ctx.raw)
+        out = [resolve_value(x, sub) for x in raw]
+        return tuple(out) if isinstance(raw, tuple) else out
+    if _has_fixed(raw):
+        return _fixed_final(raw, ctx.obj)
+    return raw
+
+
+def resolve_raw(obj: Any, name: str, check: "Validator", raw: Any, of: Any = None,
+                scale: Any = None, time: bool = False, unit: str = "px") -> Any:
+    """The final value of ``raw``, a stored value of setting ``name`` of ``obj``."""
+    return resolve_value(raw, Context(obj, name, check, of, scale, time, unit, raw))
+
+
+def may_refer(raw: Any) -> bool:
+    """Whether resolving ``raw`` may read other settings (and so loop back): a ``var()``, a
+    ``calc()``, ``%`` or a relative unit."""
+    if isinstance(raw, Dim):
+        return raw.number is None or raw.unit in ("%", "em", "rem")
+    return isinstance(raw, (Var, Calc)) or isinstance(raw, (tuple, list))
+
+
+def needs_resolving(raw: Any, check: "Validator") -> bool:
+    """Whether ``raw`` differs from its final value (fast path for plain values)."""
+    if isinstance(raw, Value):
+        return True
+    if check.kind == "length" and isinstance(raw, (int, float)):
+        return True
+    if check.inner is not None and isinstance(raw, (tuple, list)):
+        return True
+    return _has_fixed(raw)
+
+
+# ---------------------------------------------------------------------------
+# Explaining a value
+# ---------------------------------------------------------------------------
+
+def _refs(raw: Any, out: list[Any]) -> list[Any]:
+    """The ``var()`` names and dimensions a stored value refers to."""
+    if isinstance(raw, (Var, Dim)):
+        out.append(raw)
+    elif isinstance(raw, Calc):
+        out.extend(raw.refs)
+    elif isinstance(raw, (tuple, list)):
+        for x in raw:
+            _refs(x, out)
+    return out
+
+
+def explain_tree(obj: Any, name: str, as_dict: bool) -> Any:
+    """See :meth:`Settings.explain`."""
+    tree = _explain(obj, name, 0, set())
+    return tree if as_dict else "\n".join(_lines(tree, 0))
+
+
+def _final(obj: Any, name: str) -> Any:
+    try:
+        return obj.resolve(name)
+    except ValueError as e:
+        return f"<{e}>"
+
+
+def _explain(obj: Any, name: str, depth: int, seen: set[Any]) -> dict[str, Any]:
+    source, owner = obj._source(name)
+    raw = owner._raw(name)
+    c = owner.SETTINGS[name].check if name in owner.SETTINGS else None
+    kind = None if c is None else c.kind or (c.inner.kind if c.inner is not None else None)
+    node: dict[str, Any] = {"name": f"{obj.kind}.{name}", "value": _final(obj, name),
+                            "given": given(raw), "source": source, "refers": [],
+                            "unit": {"length": "px", "angle": "°"}.get(kind or "", "")}
+    variant = _variant_used(obj, name, raw)
+    if variant is not None:
+        node["variant"] = variant
+    key = (id(owner), name)
+    if key in seen or depth > 8:
+        return node
+    seen = seen | {key}
+    check = None if c is None else c.inner or c          # pairs, dash lists: their items
+    refs, keys = [], set()
+    for r in _refs(raw, []):                   # each reference once
+        k = (type(r).__name__, r.name if isinstance(r, Var) else None,
+             r.unit if isinstance(r, Dim) else None)
+        if k not in keys:
+            keys.add(k)
+            refs.append(r)
+    for r in refs:
+        if isinstance(r, Var):
+            if r.name.startswith("--"):
+                node["refers"].append({"name": r.name, "value": owner._custom_var(r.name),
+                                       "given": owner._custom_var(r.name),
+                                       "source": "custom variable", "refers": []})
+                continue
+            target = owner if r.name not in (name, "inherit") else None
+            if target is None:
+                parent = next((p for p in owner._ancestors() if name in p.SETTINGS), None)
+                if parent is not None:
+                    node["refers"].append(_explain(parent, name, depth + 1, seen))
+                continue
+            holder = next((o for o in [owner] + owner._ancestors() if r.name in o.SETTINGS),
+                          None)
+            if holder is not None:
+                node["refers"].append(_explain(holder, r.name, depth + 1, seen))
+        elif isinstance(r, Dim):
+            u = r.unit
+            if u == "%":
+                ref = None if check is None else check.percent
+                if isinstance(ref, str) and ref in owner.SETTINGS:
+                    node["refers"].append(_explain(owner, ref, depth + 1, seen))
+                elif ref == "em" or (ref is None and name == "font_size"):
+                    node["refers"].append(_font_node(owner, name, depth, seen, check))
+                else:
+                    node["refers"].append({"name": f"% of {ref}", "value": None,
+                                           "given": None, "source": "layout", "refers": []})
+            elif u in ("em", "smaller", "larger") or (r.number is None and u in _RELATIVE_FONT):
+                node["refers"].append(_font_node(owner, name, depth, seen, check))
+            elif u == "rem" or (r.number is None):
+                root = owner._root()
+                if "font_size" in root.SETTINGS:
+                    node["refers"].append(_explain(root, "font_size", depth + 1, seen))
+            elif u in ABSOLUTE and (check is None or check.scaled):
+                k = owner._scaling()
+                if k != 1.0:
+                    node["refers"].append({"name": "scaling", "value": k, "given": k,
+                                           "source": "Figure.scaling", "refers": []})
+    return node
+
+
+def _font_node(obj: Any, name: str, depth: int, seen: set[Any],
+               check: "Validator | None" = None) -> dict[str, Any]:
+    basis = None if check is None else check.em
+    if basis is not None:
+        return _explain(obj, basis, depth + 1, seen)
+    holders = obj._ancestors() if name == "font_size" else [obj] + obj._ancestors()
+    holder = next((o for o in holders if "font_size" in o.SETTINGS), None)
+    if holder is None:
+        return {"name": "font_size", "value": obj._root_font_size(), "given": None,
+                "source": "theme", "refers": []}
+    return _explain(holder, "font_size", depth + 1, seen)
+
+
+def _show(v: Any, unit: str = "") -> str:
+    if isinstance(v, float):
+        return f"{v:.6g}{unit}"
+    if isinstance(v, tuple) and all(isinstance(x, float) for x in v):
+        return "(" + ", ".join(f"{x:.6g}{unit}" for x in v) + ")"
+    return repr(v)
+
+
+def _variant_used(obj: Any, name: str, raw: Any) -> str | None:
+    """The color variant a setting's named colors or color maps are resolved in, when not
+    base."""
+    from .settings import _variable_default
+    s = obj.SETTINGS.get(name)
+    items = raw.values() if isinstance(raw, dict) else raw if isinstance(raw, (list, tuple)) \
+        else (raw,)
+    if s is None or not (any(isinstance(x, Fixed) and x.varies for x in items)
+                         or isinstance(raw, str) and _variable_default(s, raw)):
+        return None
+    from .color.values import variant_of
+    v = variant_of(obj)
+    return None if v == "base" else v
+
+
+def _lines(node: dict[str, Any], depth: int) -> list[str]:
+    pad = "  " * depth
+    given_ = node["given"]
+    head = f"{pad}{node['name']} = {_show(node['value'], node.get('unit', ''))}"
+    if given_ is not None and given_ != node["value"]:
+        head += f" ← {_show(given_)}"
+    variant = node.get("variant")
+    head += f"  ({node['source']}; color_variant {variant})" if variant \
+        else f"  ({node['source']})"
+    out = [head]
+    for r in node["refers"]:
+        out.extend(_lines(r, depth + 1))
+    return out