plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/settings.py

@@ -0,0 +1,807 @@
+"""Settings: declared, validated, inherited and resolved through one cascade.
+
+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.
+:func:`cascade` finds where a value comes from, in this order:
+
+1. the value set on the object, then (plots' x and y axes) the value set on the figure's
+   axis of that role (``figure.x_axis``), then a rule of values given elsewhere
+   (:func:`given_rule`: a series' own color axis settings);
+2. each style of the figure's chain (:class:`Theme`), nearest first: the key of the
+   object's class, then of its base classes (a base class's key is skipped once a more
+   specific class has a default for the setting), then the key of the setting's group
+   (``"Marker.size"``); a class rule (``RULES``: a default the class computes from the
+   model) comes after the keys of its class and of more specific ones, before the
+   others.  For an inherited setting, the first style with its bare name is the last
+   one read here (the nearer style wins);
+3. for inherited settings, the parent's value (series → plot → figure);
+4. the default (:data:`plot_io.defaults.DEFAULTS`): the class's, along the classes as
+   style keys, then the group's; first when it refers to the parent's value
+   (``"calc(1.4 * inherit)"``);
+5. for inherited settings, the bare name: the nearest style's, else ``DEFAULTS``'.
+
+:meth:`Settings.get` returns the value as given, :meth:`Settings.resolve` the final value
+(units, ``var()``, ``calc()`` and ``"auto"`` rules resolved; see :mod:`plot_io.units`),
+:meth:`Settings.explain` where it comes from.  While a figure is rendered, plain
+resolutions read the render's :mod:`~plot_io.spec`.
+"""
+
+import contextlib
+import contextvars
+import difflib
+from collections.abc import Callable, Generator, Iterable
+from typing import Any, Self
+
+from .defaults import DEFAULTS, default_of, inherited
+from .units import (SettingError, Value, Var, guard, has_fixed, may_refer, needs_resolving, parse, refers_inherit, resolve_raw,
+                    given)
+from .validators import Validator, anything, as_validator, family, text
+# The validators, imported from here by the modules that declare settings.
+from .validators import (  # noqa: F401
+    boolean, custom_vars, dpi, dpi_or_bool, either, font_stretch, font_style, font_variations,
+    font_weight, line_height, literal, number, one_of, pair, simplify_value, time_zone)
+from . import hints
+from . import spec as _spec
+
+_MISS = object()
+
+#: Values in force for the output in progress in this thread or task (``write(simplify=…)``,
+#: ``region=``): ``id(obj)`` → ``(obj, {name: value})``, read as if set on ``obj``.
+_OVERRIDES: contextvars.ContextVar[dict[int, tuple[Any, dict[str, Any]]]] = \
+    contextvars.ContextVar("plot_io_overrides", default={})
+
+
+def _own(obj: "Settings", name: str) -> Any:
+    """``obj``'s value of ``name``: an override in force, else its own (``_MISS``: none)."""
+    o = _OVERRIDES.get()
+    if o:
+        hit = o.get(id(obj))
+        if hit is not None and name in hit[1]:
+            return hit[1][name]
+    return obj._values.get(name, _MISS)
+
+
+@contextlib.contextmanager
+def overriding(obj: "Settings", **settings: Any) -> Generator[None]:
+    """Settings of ``obj`` in force inside the block, in this thread or task only, as if
+    set on ``obj``; the object is not changed.  ``None`` values are left out."""
+    settings = {k: v for k, v in canonical_kwargs(settings, obj.SETTINGS, obj.kind).items()
+                if v is not None}
+    if not settings:
+        yield
+        return
+    checked = {}
+    for name, value in settings.items():
+        s = obj.SETTINGS.get(name)
+        if s is None:
+            raise SettingError(unknown_message(name, obj.SETTINGS, obj.kind), obj, name, value)
+        checked[name] = obj._checked(s, name, value)
+    current = _OVERRIDES.get()
+    mine = dict(current[id(obj)][1]) if id(obj) in current else {}
+    mine.update(checked)
+    token = _OVERRIDES.set({**current, id(obj): (obj, mine)})
+    try:
+        yield
+    finally:
+        _OVERRIDES.reset(token)
+#: Returned by a class rule that does not apply: the cascade goes on.
+DECLINE = object()
+
+__all__ = ["Setting", "Settings", "Theme", "BASE_THEME", "ALIASES", "MARKER_ALIASES", "DECLINE",
+           "route", "unknown_message", "canonical", "cascade", "overriding"]
+
+#: The shorthands: of setting names (on every class that has the full setting; a setting
+#: has at most one) and of marker names.  docs/api.md's table of shorthands is made from them.
+ALIASES = {"c": "color", "s": "size", "cmap": "color_map", "smap": "size_map"}
+MARKER_ALIASES = {"o": "circle", "s": "square", "d": "diamond", "^": "triangle_up",
+                  "v": "triangle_down", "<": "triangle_left", ">": "triangle_right",
+                  "+": "plus", "x": "cross", "triangle": "triangle_up"}
+
+
+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] = {}
+    given_as: dict[str, str] = {}
+    for name, value in kwargs.items():
+        key = canonical(name, table)
+        if key in out:
+            raise ValueError(f"{what}: {given_as[key]!r} and {name!r} are the same setting; "
+                             f"give one")
+        out[key] = value
+        given_as[key] = name
+    return out
+
+
+class Theme:
+    """A figure's style chain: ``layers``, the styles other than ``"default"`` as
+    ``(label, keys)``, nearest first; ``DEFAULTS`` comes after them.  As a mapping, the
+    bare names (inherited settings) and custom variables (``--name``): the nearest
+    style's, else ``DEFAULTS``'."""
+
+    __slots__ = ("layers", "_flat")
+
+    def __init__(self, layers: Iterable[tuple[str, dict[str, Any]]] = ()) -> None:
+        self.layers = tuple(layers)
+        flat = inherited()
+        for _, keys in reversed(self.layers):
+            flat.update((k, v) for k, v in keys.items() if "." not in k)
+        self._flat = flat
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._flat.get(key, default)
+
+    def __getitem__(self, key: str) -> Any:
+        return self._flat[key]
+
+    def __contains__(self, key: object) -> bool:
+        return key in self._flat
+
+    def label(self, key: str) -> str:
+        """``style "name" key`` for the nearest style that has ``key``, else
+        ``default key``."""
+        for label, keys in self.layers:
+            if key in keys:
+                return f"style {label} {key}"
+        return f"default {key}"
+
+
+#: The theme of objects outside a figure, and of figures without a style.
+BASE_THEME = Theme()
+
+
+class Setting:
+    """One declared setting: ``check``, its :class:`~plot_io.validators.Validator` (a
+    function is wrapped in a :class:`~plot_io.validators.Custom`), validates and normalizes
+    a value (raising ``ValueError``).  ``expr``: ``var()`` is accepted (default: unless the
+    setting is text).  ``auto(obj)``: the final value of ``"auto"``, computed from the model
+    when the setting is resolved.  ``group``, ``field``: the setting group it belongs to and
+    its member name there.  Defaults are in :data:`plot_io.defaults.DEFAULTS`; ``default``
+    is the default of a class that has no ``DEFAULTS`` key for the setting (a plot type
+    added by a user)."""
+
+    __slots__ = ("name", "check", "inherited", "doc", "expr", "auto", "default", "group",
+                 "field", "prefix")
+
+    def __init__(self, check: Validator | Callable[[Any], Any] | None = None, *,
+                 inherited: bool = False, doc: str = "", expr: bool | None = None,
+                 auto: Callable[[Any], Any] | None = None, default: Any = _MISS) -> None:
+        self.name = ""
+        self.check: Validator = as_validator(check)
+        self.inherited = inherited
+        self.doc = doc
+        self.expr = expr if expr is not None else check not in (text, str, family, anything,
+                                                                 None)
+        self.auto = auto
+        #: the default of a class outside ``DEFAULTS`` (a plot type a user adds), used when
+        #: no ``DEFAULTS`` key applies
+        self.default = default
+        self.group: Any = None
+        self.field: str | None = None
+        self.prefix = ""
+
+    @property
+    def kind(self) -> str | None:
+        """``"length"``, ``"angle"``, ``"number"`` or ``None``."""
+        return self.check.kind
+
+    @property
+    def group_key(self) -> str | None:
+        """The ``"Group.member"`` key of this setting's group member."""
+        g = self.group
+        return None if g is None else f"{g.__name__}.{self.field}"
+
+
+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
+
+
+#: Setting names suggested for a name of the same idea that a class lacks (Hist's
+#: ``shape`` for ``kind``, Bar's ``y_error`` for ``error``, Area's ``y`` for ``ys``).
+SAME_IDEA = {"kind": "shape", "error": "y_error", "ys": "y"}
+
+
+def unknown_message(name: str, candidates: Iterable[str], what: str,
+                    own: Iterable[str] = ()) -> str:
+    """The error of an unknown setting ``name`` of ``what`` among ``candidates``; ``own``:
+    the candidates of the class itself, preferred for a matplotlib name's hint."""
+    if name == "theme":
+        return ("unknown setting 'theme': use style= (a style name, or a dict of settings "
+                "with an optional \"base\")")
+    candidates = list(candidates)
+    if name == "label" and "name" in candidates:
+        return f"unknown {what} setting 'label': use name= (the legend entry)"
+    if name.endswith("alpha"):
+        want = name[:-5] + "opacity"
+        if want in candidates or name == "alpha":
+            return (f"unknown {what} setting {name!r}: use {want}= (an opacity; alpha is "
+                    "the alpha channel of a color)")
+    if name in ("color_map", "cmap") and "color_map" not in candidates \
+            and "sequential_map" in candidates:
+        from .color.maps import COLOR_MAP_HINT
+        return f"unknown {what} setting {name!r}: {COLOR_MAP_HINT}"
+    use = hints.setting(name, own) or hints.setting(name, candidates)
+    if use is not None:
+        return f"unknown {what} setting {name!r}: use {use}"
+    axis = hints.axis_setting(name)
+    if axis is not None:
+        return f"unknown {what} setting {name!r}: use {axis}"
+    near = [SAME_IDEA[name]] if SAME_IDEA.get(name) in candidates else \
+        difflib.get_close_matches(name, 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 Plan:
+    """Where a setting of one class is looked up (see :func:`cascade`), computed once per
+    class: its owner style keys, its default and the key holding it, its group style key,
+    whether it is inherited and whether its default refers to the inherited value, and the
+    class rule."""
+
+    __slots__ = ("setting", "style_keys", "default", "default_key", "group_key",
+                 "inherited", "inherit_default", "rule", "rule_key", "rule_first", "rule_at",
+                 "shared")
+
+    def __init__(self, obj: "Settings", name: str) -> None:
+        s = obj.SETTINGS[name]
+        self.setting = s
+        self.inherited = s.inherited
+        keys: list[str] = []
+        self.default: Any = _MISS
+        self.default_key: str | None = None
+        for level in obj._levels(name):
+            keys.extend(f"{c}.{name}" for c in level)
+            hit = next((f"{c}.{name}" for c in level if f"{c}.{name}" in DEFAULTS), None)
+            if hit is not None:
+                self.default_key = hit
+                break
+        self.style_keys = tuple(keys)
+        self.group_key = s.group_key
+        if self.default_key is None and self.group_key is not None \
+                and self.group_key in DEFAULTS:
+            self.default_key = self.group_key
+        if self.default_key is None and s.default is not _MISS:
+            self.default_key = f"{type(obj).__name__}.{name}"   # declared: not in DEFAULTS
+        if self.default_key is not None:
+            self.default = default_of(s, self.default_key)
+        self.inherit_default = self.inherited and self.default is not _MISS \
+            and refers_inherit(self.default)
+        #: whether values set on another object (``obj._shared()``) come before the rest
+        self.shared = type(obj)._shared is not Settings._shared
+        self.rule = None
+        self.rule_key: str | None = None
+        #: a rule of given values runs before the styles; another after the style keys of
+        #: its class and of more specific ones (``style_keys[:rule_at]``)
+        self.rule_first = False
+        self.rule_at = 0
+        for c in type(obj).__mro__:
+            r = c.__dict__.get("RULES", {}).get(name)
+            if r is not None:
+                self.rule, self.rule_key = r, f"{c.__name__}.{name}"
+                self.rule_first = isinstance(r, _GivenRule)
+                keys_ = self.style_keys
+                self.rule_at = keys_.index(self.rule_key) + 1 if self.rule_key in keys_ \
+                    else len(keys_)
+                break
+
+
+_PLANS: dict[Any, dict[str, Plan]] = {}
+
+
+def class_default(cls: Any, name: str, keys: tuple[str, ...] = (), role: Any = None) -> Any:
+    """The ``DEFAULTS`` entry (as written) of setting ``name`` of objects of ``cls``, where
+    the cascade's :class:`Plan` finds it: the first of ``keys`` present, else along the
+    class's levels (``role``: an axis' ``"x"``, ``"y"`` or ``"c"``), else its group's.
+    Raises ``KeyError``."""
+    for k in keys:
+        if k in DEFAULTS:
+            return DEFAULTS[k]
+    obj: Any = object.__new__(cls)             # the class's levels, without a model
+    if role is not None:
+        obj.role = role
+    obj.__dict__["_plans"] = {}
+    try:
+        plan = Plan(obj, name)
+    except AttributeError:                     # levels that need an instance's state
+        obj.__dict__["_levels"] = lambda _: _mro_levels(cls)
+        plan = Plan(obj, name)
+    if plan.default_key is None:
+        raise KeyError(f"no default for {cls.__name__}.{name}")
+    if plan.default_key not in DEFAULTS:
+        return plan.setting.default
+    return DEFAULTS[plan.default_key]
+
+
+def cascade(obj: "Settings", name: str,
+            theme: "Theme | None" = None) -> tuple[Any, "Settings", str, str | None]:
+    """Where the value of setting ``name`` of ``obj`` comes from: ``(raw, holder, how,
+    key)``.  ``how`` is ``"own"``, ``"figure"`` (set on ``holder``, the figure's axis of the
+    role), ``"rule"``, ``"style"`` (``key``: the style key),
+    ``"default"`` (``key``: the ``DEFAULTS`` key), ``"parent"`` (``holder``: the ancestor
+    whose value it is; ``raw`` unused), ``"theme"`` (the bare inherited name) or
+    ``"unset"``.  ``raw`` is the stored value, as checked.  ``theme``: ``obj._theme()``,
+    when the caller has it."""
+    v = _own(obj, name)
+    if v is not _MISS:
+        return v, obj, "own", None
+    plan = obj._plan(name)
+    if plan.shared:
+        src = obj._shared()
+        if src is not None:
+            v = _own(src, name)
+            if v is not _MISS:
+                return v, src, "figure", None
+    rule = plan.rule
+    if rule is not None and plan.rule_first:
+        v = _rule_value(obj, plan)
+        if v is not DECLINE:
+            return v, obj, "rule", plan.rule_key
+        rule = None
+    if theme is None:
+        theme = obj._theme()
+    group = None if plan.inherited else plan.group_key
+    keys_ = plan.style_keys
+    layers = theme.layers
+    if plan.inherited:                     # a style's bare name ends the farther styles
+        for i, (_, keys) in enumerate(layers):
+            if name in keys:
+                layers = layers[:i + 1]
+                break
+    if rule is not None:
+        near = keys_[:plan.rule_at]
+        for _, keys in layers:
+            for k in near:
+                v = keys.get(k, _MISS)
+                if v is not _MISS:
+                    return v, obj, "style", k
+        v = _rule_value(obj, plan)
+        if v is not DECLINE:
+            return v, obj, "rule", plan.rule_key
+        keys_ = keys_[plan.rule_at:]
+    for _, keys in layers:
+        for k in keys_:
+            v = keys.get(k, _MISS)
+            if v is not _MISS:
+                return v, obj, "style", k
+        if group is not None:
+            v = keys.get(group, _MISS)
+            if v is not _MISS:
+                return v, obj, "style", group
+    if plan.inherited:
+        if plan.inherit_default:
+            return plan.default, obj, "default", plan.default_key
+        p = obj._parent()
+        while p is not None:
+            if name in p.SETTINGS:
+                return None, p, "parent", None
+            p = p._parent()
+    if plan.default is not _MISS:
+        return plan.default, obj, "default", plan.default_key
+    if plan.inherited:
+        return theme.get(name), obj, "theme", name
+    return None, obj, "unset", None
+
+
+#: ``DEFAULTS``' bare values as checked, by (setting, value).
+_CHECKED_DEFAULTS: dict[tuple[int, str], Any] = {}
+
+
+def _checked_default(s: Setting, raw: str) -> Any:
+    key = (id(s), raw)
+    checked = _CHECKED_DEFAULTS.get(key, _MISS)
+    if checked is _MISS:
+        try:
+            checked = check_value(s, raw)
+        except (TypeError, ValueError):
+            checked = raw
+        _CHECKED_DEFAULTS[key] = checked
+    return checked
+
+
+def _variable_default(s: Setting, raw: str) -> bool:
+    """Whether a bare default of ``DEFAULTS`` given as text (a named color, a color map
+    name) depends on the color variant."""
+    return has_fixed(_checked_default(s, raw))
+
+
+def _varied_default(obj: "Settings", s: Setting, raw: str) -> Any:
+    """A bare default of ``DEFAULTS`` given as text in ``obj``'s color variant; ``None``
+    in the base variant (the text as given)."""
+    from .color.values import variant_of
+    if variant_of(obj) == "base":
+        return None
+    return _checked_default(s, raw).in_context(obj)
+
+
+def _rule_value(obj: "Settings", plan: Plan) -> Any:
+    assert plan.rule is not None
+    v = plan.rule(obj)
+    if v is not DECLINE and v is not None and not isinstance(v, Value):
+        v = check_value(plan.setting, v)
+    return v
+
+
+def given_rule(rule: Callable[[Any], Any]) -> Callable[[Any], Any]:
+    """Marks a class rule whose value the user gave elsewhere (a series' own setting): it
+    comes before the styles."""
+    return _GivenRule(rule)
+
+
+class _GivenRule:
+    """A class rule of values given elsewhere (see :func:`given_rule`)."""
+
+    __slots__ = ("rule",)
+
+    def __init__(self, rule: Callable[[Any], Any]) -> None:
+        self.rule = rule
+
+    def __call__(self, obj: Any) -> Any:
+        return self.rule(obj)
+
+
+class Settings:
+    """Base of every object with settings."""
+
+    SETTINGS: dict[str, Setting] = {}
+    #: Class rules: ``{name: rule(obj)}`` giving the value of a setting (as given) from
+    #: the model, a default after the style keys of the class (and of more specific ones);
+    #: ``DECLINE`` when the rule does not apply.  A :func:`given_rule` comes before them.
+    RULES: dict[str, Callable[[Any], Any]] = {}
+
+    def __init__(self, **settings: Any) -> None:
+        self._values: dict[str, Any] = {}
+        self.set(**settings)
+
+    def _parent(self) -> "Settings | None":
+        return None
+
+    def _shared(self) -> "Settings | None":
+        """An object whose own values come right after this object's (see
+        :func:`cascade`); classes that have one override this."""
+        return None
+
+    def _theme(self) -> Theme:
+        p = self._parent()
+        return p._theme() if p is not None else BASE_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 SettingError(unknown_message(name, self.SETTINGS, self.kind), self, name,
+                                   value)
+            checked[name] = None if value is None else self._checked(s, name, value)
+        for name, value in checked.items():
+            if value is None:
+                self._values.pop(name, None)
+            else:
+                self._values[name] = value
+        r = _spec.current()
+        if r is not None:
+            r.changed(self)
+        return self
+
+    def _checked(self, s: Setting, name: str, value: Any) -> Any:
+        """``value`` checked for setting ``s`` (``name``) of this object; a ``var()`` of
+        another of its settings is checked against it."""
+        try:
+            out = check_value(s, value)
+        except (TypeError, ValueError) as e:
+            raise SettingError(f"{self.kind} setting {name!r}: {e}", self, name,
+                               value) from None
+        if isinstance(out, Var) and out.name in (name, "inherit") and out.fallback is None \
+                and not self._inherits(name):
+            raise SettingError(f"{self.kind} setting {name!r}: {out.source}: no parent of "
+                               f"{self.kind} and no style has {name!r}", self, name, value)
+        if isinstance(out, Var) and out.name in self.SETTINGS \
+                and out.name not in (name, "inherit"):
+            target = self.SETTINGS[out.name].check
+            if s.check.accepts(target) is False:
+                raise SettingError(f"{self.kind} setting {name!r}: {out.source} is "
+                                   f"{target.noun}, expected {s.check.noun}", self, name, value)
+        return out
+
+    def _levels(self, name: str) -> tuple[tuple[str, ...], ...]:
+        """The classes whose style keys and defaults apply to setting ``name``, most
+        specific first, in levels: a level with a default ends the search."""
+        return _mro_levels(type(self))
+
+    def _level_key(self) -> Any:
+        """What the levels depend on besides the class (an axis: its role)."""
+        return None
+
+    def _plan(self, name: str) -> Plan:
+        table_ = self.__dict__.get("_plans")
+        if table_ is None:
+            key = (type(self), self._level_key())
+            table_ = _PLANS.get(key)
+            if table_ is None:
+                table_ = _PLANS[key] = {}
+            self.__dict__["_plans"] = table_
+        plan = table_.get(name)
+        if plan is None:
+            plan = table_[name] = Plan(self, name)
+        return plan
+
+    def _name(self, name: str) -> str:
+        """The setting ``name`` refers to (a shorthand's full name); ``ValueError`` for an
+        unknown name."""
+        if name in self.SETTINGS:
+            return name
+        key = canonical(name, self.SETTINGS)
+        if key not in self.SETTINGS:
+            raise SettingError(unknown_message(name, self.SETTINGS, self.kind), self, name)
+        return key
+
+    def is_set(self, name: str) -> bool:
+        """Whether setting ``name`` is set on this object."""
+        return _own(self, self._name(name)) is not _MISS
+
+    def _raw(self, name: str) -> Any:
+        """The stored value of setting ``name`` (as checked, before resolving), wherever
+        the cascade finds it."""
+        raw, holder, how, _ = cascade(self, name)
+        return holder._raw(name) if how == "parent" else raw
+
+    def get(self, name: str) -> Any:
+        """The value of a setting as given (``"4.5pt"``, ``"var(color)"``, ``6``): its own,
+        the style's, inherited or the default; see :meth:`resolve` for the final value."""
+        return given(self._raw(self._name(name)))
+
+    def resolve(self, name: str, *, of: Any = None, scale: Any = None, time: bool = False,
+                unit: str = "px") -> Any:
+        """The final value of a setting: lengths in px (``unit="data"``: in data units),
+        angles in degrees, ``var()`` and ``calc()`` evaluated, ``"auto"`` resolved by the
+        setting's rule, scaling applied.
+
+        ``of``: what ``%`` is of, for settings whose reference the caller knows; ``scale``:
+        px per data unit, for ``data`` units; ``time``: durations are accepted."""
+        if name not in self.SETTINGS:
+            name = self._name(name)
+        if of is None and scale is None and not time and unit == "px":
+            r = _spec._CURRENT.get()
+            if r is not None:                 # the value kept by the render, else resolved
+                d = r.values.get(id(self))
+                v = _MISS if d is None else d.get(name, _MISS)
+                if v is _MISS:
+                    v = r.lookup(self, name)
+                if v is not _spec.LAZY:
+                    return v
+        return self._resolve(name, of, scale, time, unit)
+
+    def _resolve(self, name: str, of: Any = None, scale: Any = None, time: bool = False,
+                 unit: str = "px", theme: "Theme | None" = None) -> Any:
+        """:meth:`resolve` through the cascade, without the render's values."""
+        raw, holder, how, _ = cascade(self, name, theme)
+        s = self.SETTINGS[name]
+        if how == "parent":
+            # named colors and color maps: in this object's color variant
+            raw = holder._raw(name)
+            if has_fixed(raw):
+                return resolve_raw(self, name, s.check, raw, of, scale, time, unit)
+            if not (isinstance(raw, str) and _variable_default(s, raw)):
+                return holder.resolve(name)
+            how = "theme"
+        if how == "theme" and isinstance(raw, str) and _variable_default(s, raw):
+            varied = _varied_default(self, s, raw)
+            return raw if varied is None else varied
+        if raw is None or not needs_resolving(raw, s.check):
+            out = raw
+        elif may_refer(raw):
+            with guard(self, name):
+                out = resolve_raw(self, name, s.check, raw, of, scale, time, unit)
+        else:
+            out = resolve_raw(self, name, s.check, raw, of, scale, time, unit)
+        if s.auto is not None and isinstance(out, str) and out == "auto":
+            out = s.auto(self)
+        return out
+
+    def resolve_linear(self, name: str, **options: Any) -> tuple[float, float]:
+        """``(a, b)`` such that the setting resolves to ``a + b × of`` (``%`` of ``of``):
+        for settings whose reference varies item by item."""
+        a = self.resolve(name, of=0.0, **options)
+        return a, self.resolve(name, of=1.0, **options) - a
+
+    def explain(self, name: str, as_dict: bool = False) -> Any:
+        """Where the value of setting ``name`` comes from: its source (set here, a style
+        key, inherited, the default), the value as given, what it refers to (``var()``,
+        ``%``, ``em``) and the final value.  Text, or a dict with ``as_dict``."""
+        from .units import explain_tree
+        return explain_tree(self, self._name(name), as_dict)
+
+    def _source(self, name: str) -> tuple[str, "Settings"]:
+        """Where ``name``'s stored value comes from, and the object holding it."""
+        raw, holder, how, key = cascade(self, name)
+        if how == "own":
+            return f"set on {self.kind}", self
+        if how == "figure":
+            return f"set on the figure's {getattr(self, 'role', '')} axis", holder
+        if how == "rule":
+            return f"rule {key}", self
+        if how == "style":
+            return self._theme().label(key or name), self
+        if how == "default":
+            return f"default {key}", self
+        if how == "parent":
+            src, owner = holder._source(name)
+            if src.startswith("inherited from "):
+                return src, owner
+            return f"inherited from {holder.kind}: {src}", owner
+        if how == "theme":
+            return self._theme().label(name) if name in self._theme() else "unset", self
+        return "unset", self
+
+    def settings(self) -> dict[str, Any]:
+        """The settings set explicitly on this object, as given."""
+        return {k: given(v) for k, v in self._values.items()}
+
+    def _children(self) -> "list[Settings]":
+        """The model objects below this one."""
+        return []
+
+    # -- what resolution needs ------------------------------------------------------
+
+    def _ancestors(self) -> "list[Settings]":
+        out = []
+        p = self._parent()
+        while p is not None:
+            out.append(p)
+            p = p._parent()
+        return out
+
+    def _root(self) -> "Settings":
+        r: Settings = self
+        p = r._parent()
+        while p is not None:
+            r, p = p, p._parent()
+        return r
+
+    def _scaling(self) -> float:
+        root = self._root()
+        if "scaling" in root.SETTINGS:
+            return root.resolve("scaling")
+        return 1.0
+
+    def _font_size(self) -> float:
+        """The font size ``em`` is of: this object's ``font_size``, else its parent's."""
+        if "font_size" in self.SETTINGS:
+            return self.resolve("font_size")
+        return self._parent_font_size()
+
+    def _parent_font_size(self) -> float:
+        for p in self._ancestors():
+            if "font_size" in p.SETTINGS:
+                return p.resolve("font_size")
+        return self._root_font_size()
+
+    def _root_font_size(self) -> float:
+        root = self._root()
+        if root is not self and "font_size" in root.SETTINGS:
+            return root.resolve("font_size")
+        v = self._theme().get("font_size", 11.0)
+        return float(v) * self._scaling() if isinstance(v, (int, float)) else 11.0
+
+    def _box(self, kind: str, name: str) -> float:
+        """The size (px) of a layout box, while the figure is laid out."""
+        r = _spec.current()
+        if r is not None:
+            for o in [self] + self._ancestors():
+                boxes = r.boxes.get(id(o))
+                if boxes and kind in boxes:
+                    return boxes[kind]
+        raise _spec.NeedsBox(f"{self.kind} setting {name!r}: % of the "
+                             f"{kind.replace('_', ' ')} is known only while the figure is "
+                             f"drawn")
+
+    def _custom_var(self, key: str) -> Any:
+        """Custom variable ``--name``: from the nearest ``vars`` that has it, else the
+        style's."""
+        for o in [self] + self._ancestors():
+            if "vars" in o.SETTINGS and o.is_set("vars"):
+                d = o._values["vars"]
+                if key[2:] in d:
+                    return d[key[2:]]
+        return self._theme().get(key)
+
+    def _inherits(self, name: str) -> bool:
+        """Whether an ancestor or the style has ``name`` (what ``inherit`` reads)."""
+        return any(name in p.SETTINGS for p in self._ancestors()) or name in self._theme()
+
+    def _parent_value(self, name: str) -> Any:
+        """``name`` as inherited, skipping this object (``inherit``, or ``var()`` of a
+        setting's own name)."""
+        for p in self._ancestors():
+            if name in p.SETTINGS:
+                return p.resolve(name)
+        theme = self._theme()
+        if name in theme:
+            s = self.SETTINGS.get(name)
+            raw = theme[name]
+            if s is not None and needs_resolving(raw, s.check):
+                return resolve_raw(self, name, s.check, raw)
+            return raw
+        return None
+
+    def _resolve_any(self, name: str) -> Any:
+        """``name`` of this object, or of the nearest ancestor that has it."""
+        for o in [self] + self._ancestors():
+            if name in o.SETTINGS:
+                return o.resolve(name)
+        if name in self._theme():
+            return self._theme()[name]
+        raise ValueError(f"var({name}): no setting {name!r} on {self.kind} or its parents")
+
+    def _check_of(self, name: str, own: bool = True) -> Validator | None:
+        """The validator of setting ``name`` of this object (``own``) or of the nearest
+        ancestor that has it; without ``own``, this object's when no ancestor has it (the
+        style's bare value is resolved by it); ``None``: no such setting."""
+        for o in ([self] if own else []) + self._ancestors():
+            if name in o.SETTINGS:
+                return o.SETTINGS[name].check
+        if not own and name in self.SETTINGS:
+            return self.SETTINGS[name].check
+        return None
+
+
+_MRO_LEVELS: dict[type, tuple[tuple[str, ...], ...]] = {}
+
+
+def _mro_levels(cls: type) -> tuple[tuple[str, ...], ...]:
+    out = _MRO_LEVELS.get(cls)
+    if out is None:
+        out = _MRO_LEVELS[cls] = tuple((c.__name__,) for c in cls.__mro__
+                                       if issubclass(c, Settings) and c is not Settings)
+    return out
+
+
+def check_value(s: Setting, value: Any) -> Any:
+    """``value`` checked for setting ``s``: ``var()`` text as a :class:`Var`, else through
+    the setting's validator."""
+    if isinstance(value, Value):          # already checked (a style built on another)
+        return value
+    if s.expr and isinstance(value, str):
+        v = parse(value, calc=False)
+        if v is not None:
+            return v
+    return s.check(value)
+
+
+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]
+    given_as: dict[tuple[int, str], str] = {}
+    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__}: {given_as[i, key]!r} and {name!r} are "
+                                     f"the same setting; give one")
+                out[i][key] = value
+                given_as[i, key] = name
+                break
+        else:
+            names = set().union(*(cls.SETTINGS for cls in levels))
+            raise ValueError(unknown_message(name, names, levels[0].__name__,
+                                             levels[0].SETTINGS))
+    return out