plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/validators.py

@@ -0,0 +1,1029 @@
+"""Validators: what a setting accepts, as objects.
+
+A validator parses a value given to a setting (``parse(v)``, also ``validator(v)``) into a
+plain Python value or a :class:`~plot_io.units.Value` (``Dim``, ``Var``, ``Calc``), raising
+``ValueError``.  Its fields tell resolution (:mod:`plot_io.units`) how to finish the value:
+``kind`` (``"length"``, ``"angle"``, ``"number"`` or ``None``), bounds (``lo``, ``hi``,
+``positive``), for lengths what ``%`` is of (``percent``), the unit of bare numbers
+(``bare``), whether absolute units follow the figure's ``scaling`` (``scaled``), the units
+accepted (``units``), the font size ``em`` is of (``em``); ``inner``: the validator of each
+item of a list or pair; ``choices``: the words of a choice; ``alternatives``: those of an
+:class:`Either`.
+
+After ``var()`` and ``calc()`` are evaluated, ``finish(x, ctx)`` checks the result (bounds,
+finiteness, at most :data:`MAX_PX` px for lengths); ``accepts(other)`` tells whether the
+values of a setting checked by ``other`` are values of this one (``var()``).
+
+For the generated typed API and the docs: ``annotation`` is the type of the values given,
+as source text (``tools/gen_api.py``); ``describe(name)`` the value type in words
+(``tools/settings_doc.py``, the docs' settings tables).
+
+The constructors (:func:`number`, :func:`length`, :func:`angle`, :func:`one_of`,
+:func:`either`, :func:`pair`, :func:`literal`) and the instances (:data:`boolean`,
+:data:`text`, :data:`family`, …) are what settings are declared with; a plain function
+given to a :class:`~plot_io.settings.Setting` is wrapped in a :class:`Custom`.  Real
+numbers are read here, once (:func:`real`, :func:`integer`, :func:`as_bool`).
+"""
+
+import datetime
+import enum
+import math
+import numbers
+import re
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from vec_io import Simplify, Span
+from vec_io.units import ANGLE_UNITS, PX_PER_UNIT, split_length
+
+from .units import ABSOLUTE, DURATIONS, FONT_KEYWORDS, _RELATIVE_FONT, Dim, Value, parse, percent_meaning
+
+__all__ = ["MAX_PX", "Validator", "Number", "Length", "Angle", "Choice", "Exact", "Bool", "Text", "Family",
+           "Pair", "Either", "Dpi", "Color", "Custom", "as_validator", "typed", "union", "real",
+           "integer", "as_bool",
+           "number", "length", "angle", "one_of", "literal", "either", "pair", "boolean", "text",
+           "family", "anything", "custom_vars", "dpi", "dpi_or_bool", "simplify_value",
+           "font_weight", "font_style", "font_stretch", "line_height", "font_variations",
+           "time_zone"]
+
+
+# ---------------------------------------------------------------------------
+# Real numbers
+# ---------------------------------------------------------------------------
+
+def real(v: Any) -> float | None:
+    """``v`` as a float when it is a real number (Python's, numpy's, any ``numbers.Real``, a
+    0-d numeric array), not a boolean; else ``None``."""
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, (int, float)):
+        try:
+            return float(v)
+        except OverflowError:
+            return math.inf if v > 0 else -math.inf
+    dt = getattr(v, "dtype", None)
+    if dt is not None:
+        if getattr(dt, "kind", "") not in ("i", "u", "f") or getattr(v, "shape", ()) != ():
+            return None
+        return float(v)
+    if isinstance(v, numbers.Real):
+        try:
+            return float(v)
+        except (TypeError, ValueError, OverflowError):
+            return None
+    return None
+
+
+def integer(v: Any) -> int | None:
+    """``v`` as an int when it is an integer (``numbers.Integral``, or a real of integral
+    value), not a boolean; else ``None``."""
+    if isinstance(v, bool):
+        return None
+    if isinstance(v, int):
+        return v
+    dt = getattr(v, "dtype", None)
+    if dt is not None and getattr(dt, "kind", "") in ("i", "u") and getattr(v, "shape", ()) == ():
+        return int(v)
+    if isinstance(v, numbers.Integral):
+        return int(v)
+    x = real(v)
+    if x is not None and math.isfinite(x) and x.is_integer():
+        return int(x)
+    return None
+
+
+def as_bool(v: Any) -> bool | None:
+    """``v`` as a bool when it is one (Python's or numpy's); else ``None``."""
+    if isinstance(v, bool):
+        return v
+    dt = getattr(v, "dtype", None)
+    if dt is not None and getattr(dt, "kind", "") == "b" and getattr(v, "shape", ()) == ():
+        return bool(v)
+    return None
+
+
+#: The largest length in px (and resolution in dpi) a setting takes, either sign.
+MAX_PX = 1e6
+#: The largest integer an integer setting takes, either sign (exact as a float).
+MAX_INT = 2 ** 53
+
+
+def _bound(v: float, lo: float | None, hi: float | None, positive: bool, what: str) -> None:
+    if isinstance(v, int) and abs(v) > MAX_INT:
+        raise ValueError(f"expected an integer within ±2**53, got one of {len(str(abs(v)))} digits")
+    if not math.isfinite(v):
+        raise ValueError(f"expected a finite {what}")
+    if positive and not v > 0:
+        raise ValueError(f"expected a positive {what}, got {v!r}")
+    if lo is not None and v < lo:
+        raise ValueError(f"expected at least {lo}, got {v!r}")
+    if hi is not None and v > hi:
+        raise ValueError(f"expected at most {hi}, got {v!r}")
+
+
+# ---------------------------------------------------------------------------
+# Validator objects
+# ---------------------------------------------------------------------------
+
+#: The fields resolution reads, copied by :class:`Either` from its typed alternative and
+#: by :class:`Custom` from the validator it resolves like.
+_FIELDS = ("kind", "lo", "hi", "positive", "integer", "percent", "bare", "font", "scaled",
+           "units", "em", "inner", "choices", "alternatives")
+
+
+_UNSET: dict[str, Any] = {
+    "kind": None, "lo": None, "hi": None, "positive": False, "integer": False, "percent": None,
+    "bare": "px", "font": False, "scaled": True, "units": frozenset(), "em": None,
+    "inner": None, "choices": None, "alternatives": None}
+
+
+class Validator:
+    """What a setting accepts.  Immutable: fields are given when it is made."""
+
+    __slots__ = _FIELDS
+    kind: str | None
+    lo: float | None
+    hi: float | None
+    positive: bool
+    integer: bool
+    percent: str | None
+    bare: str
+    font: bool
+    scaled: bool
+    units: frozenset[str]
+    em: str | None
+    inner: "Validator | None"
+    choices: tuple[str, ...] | None
+    alternatives: "tuple[Validator, ...] | None"
+
+    def __init__(self, **fields: Any) -> None:
+        for k, v in {**_UNSET, **fields}.items():
+            object.__setattr__(self, k, v)
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        raise AttributeError(f"{type(self).__name__} is immutable")
+
+    #: What the values are, for ``var()``: ``"length"``, ``"angle"``, ``"number"``,
+    #: ``"bool"``, ``"choice"``, ``"text"``, or ``None`` (not known).
+    sort: str | None = None
+
+    @property
+    def noun(self) -> str:
+        """The values, in words (``"a length"``)."""
+        return _NOUNS.get(self.sort or "", "a value")
+
+    def accepts(self, other: "Validator") -> bool | None:
+        """Whether the final values of a setting checked by ``other`` are values of this
+        one as they are (``True``), never are (``False``), or must be parsed again
+        (``None``)."""
+        if other is self:
+            return True
+        if isinstance(other, Either):
+            return _all(self.accepts(o) for o in other.alternatives or ())
+        a, b = self.sort, other.sort
+        if a is None or b is None:
+            return None
+        return a == b
+
+    def finish(self, x: Any, ctx: Any) -> Any:
+        """``x``, the final value of a ``var()``, ``calc()`` or unit of this setting,
+        checked: finite, within the bounds; ``ctx.error`` otherwise."""
+        if self.kind is None:
+            return x
+        v = real(x)
+        if v is None:
+            if self.strict:
+                raise ctx.error(f"expected {self.noun}, got {x!r}")
+            return x
+        if not math.isfinite(v):
+            raise ctx.error(f"resolves to {v}, expected a finite value")
+        if self.kind == "angle":
+            lo, hi = self.lo, self.hi
+            if (lo is not None and v < lo) or (hi is not None and v > hi):
+                raise ctx.error(f"{v:g}° is outside {lo:g}…{hi:g}")
+            return x
+        if self.integer and not v.is_integer():
+            raise ctx.error(f"resolves to {v:g}, expected an integer")
+        if self.positive and not v > 0:
+            raise ctx.error(f"resolves to {v:g}, expected a positive {self.kind}")
+        if self.lo is not None and v < self.lo - 1e-9:
+            raise ctx.error(f"resolves to {v:g}, expected at least {self.lo:g}")
+        if self.hi is not None and v > self.hi + 1e-9:
+            raise ctx.error(f"resolves to {v:g}, expected at most {self.hi:g}")
+        if self.kind == "length" and self.bare == "px" and ctx.unit == "px" \
+                and abs(v) > MAX_PX:
+            raise ctx.error(f"resolves to {v:g} px, expected at most {MAX_PX:g} px")
+        return x
+
+    #: whether :meth:`finish` refuses values that are not real numbers (a validator of
+    #: its own; a :class:`Custom` passes them)
+    strict = True
+
+    #: The type of the values given, as source text of ``plot_io/types.py``.
+    annotation = "Any"
+
+    def describe(self, name: str = "") -> str:
+        """The value type, in words, appended to the meaning of setting ``name`` in docs/api.md:
+        lengths (what their ``%`` is of, the unit of bare numbers) and angles."""
+        check: Validator | None = self.inner if self.kind is None else self
+        kind = None if check is None else check.kind
+        if check is None or kind == "angle":
+            return "Angle (bare: degrees)." if kind == "angle" else ""
+        if kind != "length":
+            return ""
+        parts = ["Length"]
+        if check.em is not None:
+            parts.append(f"`em` and `%`: of `{check.em}`")
+        elif check.percent == "em" and name == "font_size":
+            parts.append("`%`: of the parent's font size")
+        elif check.percent is not None:
+            parts.append(f"`%`: of {percent_meaning(check.percent)}")
+        if check.bare == "data":
+            parts.append("bare numbers: data units")
+        elif "d" in check.units:
+            parts.append("`d`: data units")
+        return "; ".join(parts) + "."
+
+    def _like(self, other: "Validator") -> dict[str, Any]:
+        """The fields of ``other``, to resolve as it does."""
+        return {k: getattr(other, k) for k in _FIELDS}
+
+    @property
+    def typed(self) -> bool:
+        """Whether resolution treats values as this validator's kind or items."""
+        return self.kind is not None or self.inner is not None
+
+    def parse(self, v: Any) -> Any:
+        """``v`` checked and normalized; ``ValueError`` when it is not accepted."""
+        raise NotImplementedError
+
+    def __call__(self, v: Any) -> Any:
+        return self.parse(v)
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}()"
+
+
+class Number(Validator):
+    """A number between ``lo`` and ``hi`` (``positive``: above 0; ``integer``: an integer);
+    ``calc()`` and ``var()`` kept."""
+
+    __slots__ = ()
+
+    def __init__(self, lo: float | None = None, hi: float | None = None,
+                 positive: bool = False, integer: bool = False) -> None:
+        super().__init__(kind="number", lo=lo, hi=hi, positive=positive, integer=integer)
+
+    sort = "number"
+    annotation = "SupportsFloat"
+
+    def parse(self, v: Any) -> Any:
+        if isinstance(v, str) and not self.integer:
+            e = parse(v, frozenset())
+            if e is not None:
+                return e
+        x = real(v)
+        if x is None:
+            raise ValueError(f"expected a number, got {v!r}")
+        if not self.integer:
+            _bound(x, self.lo, self.hi, self.positive, "number")
+            return x
+        n = integer(v)
+        if n is None:
+            raise ValueError(f"expected an integer, got {v!r}")
+        _bound(n, self.lo, self.hi, self.positive, "number")
+        return n
+
+    def __repr__(self) -> str:
+        return f"Number(lo={self.lo!r}, hi={self.hi!r})"
+
+
+class Length(Validator):
+    """A length.
+
+    ``percent``: what ``%`` is of: a key of :data:`~plot_io.units.REFERENTS` or the name
+    of another setting of the object; ``None``: ``%`` is not accepted.  ``bare``: unit of
+    bare numbers (``"px"`` or ``"data"``).  ``data``: ``data`` units and durations are
+    accepted.  ``font``: font-size keywords are accepted.  ``scaled``: absolute values
+    follow the figure's ``scaling``.  ``fr``: ``fr`` units are accepted.  ``em``: the
+    font-size setting ``em`` is of, instead of the object's ``font_size``
+    (``"tick_label_font_size"`` for tick spacing).
+    """
+
+    __slots__ = ()
+
+    def __init__(self, lo: float | None = None, positive: bool = False, *, percent: Any = None,
+                 bare: str = "px", data: bool = False, font: bool = False, scaled: bool = True,
+                 fr: bool = False, em: str | None = None) -> None:
+        units = set(ABSOLUTE) | {"em", "rem"}
+        if percent is not None:
+            units.add("%")
+        if data:
+            units |= {"data"} | set(DURATIONS)
+        if fr:
+            units.add("fr")
+        super().__init__(kind="length", lo=lo, positive=positive, percent=percent, bare=bare,
+                         font=font, scaled=scaled, units=frozenset(units), em=em)
+
+    sort = "length"
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        return "SupportsFloat | str | timedelta" if "data" in self.units \
+            else "SupportsFloat | str"
+
+    def _sane(self, px: float, v: Any) -> None:
+        if self.bare == "px" and abs(px) > MAX_PX:
+            raise ValueError(f"expected a length of at most {MAX_PX:g} px, got {v!r}")
+
+    def parse(self, v: Any) -> Any:
+        lo, positive, allowed = self.lo, self.positive, self.units
+        x = real(v)
+        if x is not None:
+            _bound(x, lo, None, positive, "length")
+            self._sane(x, v)
+            return x
+        if isinstance(v, datetime.timedelta) and "data" in allowed:
+            return Dim(str(v), v.total_seconds(), "s")
+        if isinstance(v, Value):
+            return v
+        if not isinstance(v, str):
+            raise ValueError(f"expected a length, got {v!r}")
+        s = v.strip()
+        if self.font and (s.lower() in FONT_KEYWORDS or s.lower() in _RELATIVE_FONT):
+            return Dim(v, None, s.lower())
+        e = parse(s, allowed)
+        if e is not None:
+            return e
+        try:
+            number, unit = split_length(s, allowed | {""})
+        except ValueError:
+            hint = ", ".join(sorted(u for u in allowed if u not in DURATIONS))
+            raise ValueError(f"invalid length {v!r} (units: {hint})") from None
+        if not unit:
+            _bound(number, lo, None, positive, "length")
+            self._sane(number, v)
+            return number
+        if unit in ABSOLUTE:
+            _bound(number * PX_PER_UNIT[unit], lo, None, positive, "length")
+            self._sane(number * PX_PER_UNIT[unit], v)
+        else:
+            _bound(number, 0.0 if lo is not None and lo >= 0 else None, None, positive,
+                   "length")
+        return Dim(v, number, unit)
+
+    def __repr__(self) -> str:
+        return f"Length(lo={self.lo!r}, percent={self.percent!r})"
+
+
+_ANGLES = frozenset(ANGLE_UNITS)
+
+
+class Angle(Validator):
+    """An angle between ``lo`` and ``hi`` degrees: degrees, or ``deg``, ``grad``, ``rad``,
+    ``turn``."""
+
+    __slots__ = ()
+
+    def __init__(self, lo: float | None = None, hi: float | None = None) -> None:
+        super().__init__(kind="angle", lo=lo, hi=hi)
+
+    sort = "angle"
+    annotation = "SupportsFloat | str"
+
+    def parse(self, v: Any) -> Any:
+        x = real(v)
+        if x is not None:
+            _bound(x, self.lo, self.hi, False, "angle")
+            return x
+        if isinstance(v, Value):
+            return v
+        if not isinstance(v, str):
+            raise ValueError(f"expected an angle, got {v!r}")
+        e = parse(v, _ANGLES)
+        if e is not None:
+            return e
+        try:
+            number, unit = split_length(v, _ANGLES | {""})
+        except ValueError:
+            raise ValueError(f"invalid angle {v!r} (units: deg, grad, rad, turn)") from None
+        deg = number * ANGLE_UNITS[unit] if unit else number
+        _bound(deg, self.lo, self.hi, False, "angle")
+        return Dim(v, number, unit) if unit else number
+
+    def __repr__(self) -> str:
+        return f"Angle(lo={self.lo!r}, hi={self.hi!r})"
+
+
+class Choice(Validator):
+    """One of ``choices`` (case, ``-`` and ``_`` aside; an ``enum`` member by its value);
+    ``aliases`` maps other words to them."""
+
+    __slots__ = ("aliases",)
+    aliases: dict[str, str]
+
+    def __init__(self, *choices: str, aliases: dict[str, str] | None = None) -> None:
+        super().__init__(choices=choices)
+        object.__setattr__(self, "aliases", dict(aliases or {}))
+
+    sort = "choice"
+
+    @property
+    def noun(self) -> str:
+        return "one of " + ", ".join(map(repr, self.choices or ()))
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        words = (*(self.choices or ()), *self.aliases)
+        return "Literal[" + ", ".join(map(repr, words)) + "]"
+
+    def accepts(self, other: Validator) -> bool | None:
+        if isinstance(other, Choice):
+            return True if set(other.choices or ()) <= set(self.choices or ()) else None
+        return super().accepts(other)
+
+    def parse(self, v: Any) -> Any:
+        if isinstance(v, enum.Enum):
+            v = v.value
+        choices = self.choices or ()
+        if isinstance(v, str):
+            key = v.strip().lower().replace("-", "_")
+            key = self.aliases.get(key, key)
+            if key in choices:
+                return key
+        raise ValueError(f"expected one of {', '.join(map(repr, choices))}, got {v!r}")
+
+    def __repr__(self) -> str:
+        return f"Choice{self.choices!r}"
+
+
+class Exact(Validator):
+    """One of ``values``, equal and of the same type."""
+
+    __slots__ = ("values",)
+    values: tuple[Any, ...]
+
+    def __init__(self, *values: Any) -> None:
+        super().__init__()
+        object.__setattr__(self, "values", values)
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        if all(w is None or isinstance(w, (str, int, bool)) for w in self.values):
+            return "Literal[" + ", ".join(map(repr, self.values)) + "]"
+        return "Any"
+
+    def parse(self, v: Any) -> Any:
+        for w in self.values:
+            if v == w and type(v) is type(w):
+                return v
+        raise ValueError(f"expected one of {', '.join(map(repr, self.values))}, got {v!r}")
+
+    def __repr__(self) -> str:
+        return f"Exact{self.values!r}"
+
+
+class Bool(Validator):
+    """``True`` or ``False`` (numpy's too)."""
+
+    __slots__ = ()
+    sort = "bool"
+    annotation = "bool"
+
+    def parse(self, v: Any) -> bool:
+        b = as_bool(v)
+        if b is None:
+            raise ValueError(f"expected True or False, got {v!r}")
+        return b
+
+
+class Text(Validator):
+    """A string or rich content (a list of strings and spans); other values as text."""
+
+    __slots__ = ()
+    sort = "text"
+    annotation = "str | Span | Sequence[str | Span] | SupportsFloat"
+
+    def parse(self, v: Any) -> Any:
+        if isinstance(v, str):
+            return v
+        if isinstance(v, (list, tuple)):
+            for x in v:
+                if not isinstance(x, (str, Span)):
+                    raise ValueError(f"expected a string or a list of strings and spans, "
+                                     f"got {v!r}")
+            return list(v)
+        if isinstance(v, Span):
+            return [v]
+        return str(v)
+
+
+class Family(Validator):
+    """A font family: a name, or names separated by commas (the first installed is used)."""
+
+    __slots__ = ()
+    sort = "text"
+    annotation = "str"
+
+    @property
+    def noun(self) -> str:
+        return "a font family"
+
+    def parse(self, v: Any) -> str:
+        if not isinstance(v, str) or not v.strip(" ,"):
+            raise ValueError(f"expected a font family name, got {v!r}")
+        return v
+
+
+class Pair(Validator):
+    """Two values, each checked by ``item``."""
+
+    __slots__ = ()
+
+    def __init__(self, item: Validator) -> None:
+        super().__init__(inner=item)
+
+    def parse(self, v: Any) -> tuple[Any, Any]:
+        if not isinstance(v, (tuple, list)) or len(v) != 2:
+            raise ValueError(f"expected a pair, got {v!r}")
+        item = self.inner
+        assert item is not None
+        return (item(v[0]), item(v[1]))
+
+    @property
+    def noun(self) -> str:
+        return "a pair"
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        assert self.inner is not None
+        a = self.inner.annotation
+        return f"tuple[{a}, {a}] | list[{a}]"
+
+    def accepts(self, other: Validator) -> bool | None:
+        if other is self:
+            return True
+        if isinstance(other, Pair):
+            assert self.inner is not None and other.inner is not None
+            return self.inner.accepts(other.inner)
+        return None
+
+    def finish(self, x: Any, ctx: Any) -> Any:
+        item = self.inner
+        if item is None or not isinstance(x, (tuple, list)):
+            return x
+        return type(x)(item.finish(i, ctx) for i in x)
+
+    def __repr__(self) -> str:
+        return f"Pair({self.inner!r})"
+
+
+class Either(Validator):
+    """The first of ``alternatives`` that accepts the value.  Resolved as its first typed
+    alternative (a length, an angle, a number, or one with items)."""
+
+    __slots__ = ()
+
+    def __init__(self, *alternatives: Validator) -> None:
+        typed = next((c for c in alternatives if c.typed), None)
+        fields = self._like(typed) if typed is not None else {}
+        fields["alternatives"] = alternatives
+        super().__init__(**fields)
+
+    def parse(self, v: Any) -> Any:
+        errors = []
+        for c in self.alternatives or ():
+            try:
+                return c(v)
+            except (TypeError, ValueError) as e:
+                errors.append(str(e))
+        raise ValueError("; ".join(errors))
+
+    @property
+    def sort(self) -> str | None:  # type: ignore[override]
+        sorts = {a.sort for a in self.alternatives or ()}
+        return sorts.pop() if len(sorts) == 1 else None
+
+    @property
+    def noun(self) -> str:
+        return " or ".join(a.noun for a in self.alternatives or ())
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        return union(*(a.annotation for a in self.alternatives or ()))
+
+    def accepts(self, other: Validator) -> bool | None:
+        if other is self:
+            return True
+        return _any(a.accepts(other) for a in self.alternatives or ())
+
+    def finish(self, x: Any, ctx: Any) -> Any:
+        """``x`` finished by the alternative it is a value of: the typed one for a number."""
+        if real(x) is not None:
+            typed = next((a for a in self.alternatives or () if a.typed), None)
+            return x if typed is None else typed.finish(x, ctx)
+        return x
+
+    def __repr__(self) -> str:
+        return f"Either{self.alternatives!r}"
+
+
+_MULTIPLE = re.compile(r"\s*([0-9]*\.?[0-9]+)\s*x\s*", re.I)
+_POSITIVE = Number(positive=True, hi=MAX_PX)
+
+
+class Dpi(Validator):
+    """A resolution in dots per inch: a number, or a multiple of 96 written ``"2x"``
+    (192 dpi); ``calc()`` and ``var()`` kept.  ``flag``: ``True`` and ``False`` too;
+    ``auto``: ``"auto"`` too."""
+
+    __slots__ = ("flag", "auto")
+    flag: bool
+    auto: bool
+
+    def __init__(self, flag: bool = False, auto: bool = False) -> None:
+        super().__init__()
+        object.__setattr__(self, "flag", flag)
+        object.__setattr__(self, "auto", auto)
+
+    sort = "number"
+
+    @property
+    def noun(self) -> str:
+        return "a resolution"
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        return "SupportsFloat | str | bool" if self.flag else "SupportsFloat | str"
+
+    def finish(self, x: Any, ctx: Any) -> Any:
+        if isinstance(x, bool) or x == "auto":
+            return x
+        return _POSITIVE.finish(x, ctx)
+
+    def parse(self, v: Any) -> Any:
+        if self.auto and v == "auto":
+            return "auto"
+        if self.flag and isinstance(v, bool):
+            return v
+        if isinstance(v, str):
+            m = _MULTIPLE.fullmatch(v)
+            if m is not None:
+                return _POSITIVE(96.0 * float(m.group(1)))
+        d = _POSITIVE(v)
+        return d if isinstance(d, Value) else float(d)
+
+    def __repr__(self) -> str:
+        return f"Dpi(flag={self.flag!r}, auto={self.auto!r})"
+
+
+class Color(Validator):
+    """A color, checked by ``fn(v)`` (:func:`plot_io.color.values.color`)."""
+
+    __slots__ = ("fn",)
+    fn: Callable[[Any], Any]
+
+    def __init__(self, fn: Callable[[Any], Any]) -> None:
+        super().__init__()
+        object.__setattr__(self, "fn", fn)
+
+    sort = "color"
+    annotation = "ColorLike"
+
+    @property
+    def noun(self) -> str:
+        return "a color"
+
+    def parse(self, v: Any) -> Any:
+        return self.fn(v)
+
+    def __repr__(self) -> str:
+        return "Color()"
+
+
+class Custom(Validator):
+    """A validator made of a function ``fn(v)``.  ``like``: the validator whose fields it
+    takes (it resolves as that one); ``inner``: the validator of its items;
+    ``annotation``: the type of the values given (default: the one :func:`typed` gave
+    ``fn``, else ``Any``)."""
+
+    __slots__ = ("fn", "_annotation")
+    fn: Callable[[Any], Any]
+    _annotation: str | None
+
+    def __init__(self, fn: Callable[[Any], Any], *, like: Validator | None = None,
+                 inner: Validator | None = None, annotation: str | None = None) -> None:
+        fields = self._like(like) if like is not None else {}
+        if inner is not None:
+            fields["inner"] = inner
+        super().__init__(**fields)
+        object.__setattr__(self, "fn", fn)
+        object.__setattr__(self, "_annotation", annotation)
+
+    strict = False
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        if self._annotation is not None:
+            return self._annotation
+        return getattr(self.fn, "value_type", "Any")
+
+    @property
+    def sort(self) -> str | None:  # type: ignore[override]
+        return self.kind
+
+    def accepts(self, other: Validator) -> bool | None:
+        if isinstance(other, Custom) and other.fn is self.fn:
+            return True
+        return super().accepts(other)
+
+    def parse(self, v: Any) -> Any:
+        return self.fn(v)
+
+    def __repr__(self) -> str:
+        return f"Custom({getattr(self.fn, '__name__', self.fn)!r})"
+
+
+_NOUNS = {"length": "a length", "angle": "an angle", "number": "a number",
+          "bool": "True or False", "choice": "a choice", "text": "text"}
+
+
+_F = TypeVar("_F", bound=Callable[..., Any])
+
+
+def typed(annotation: str) -> Callable[[_F], _F]:
+    """Decorator of a function validator: ``annotation`` is the type of the values it
+    accepts, as source text of ``plot_io/types.py`` (read by :class:`Custom`)."""
+    def mark(fn: _F) -> _F:
+        setattr(fn, "value_type", annotation)
+        return fn
+    return mark
+
+
+def union(*annotations: str) -> str:
+    """The union of type annotations (source text), each member once; ``Any`` absorbs the
+    others."""
+    out: list[str] = []
+    for a in annotations:
+        depth, start = 0, 0
+        for i, ch in enumerate(a + "|"):
+            if ch == "[":
+                depth += 1
+            elif ch == "]":
+                depth -= 1
+            elif ch == "|" and depth == 0:
+                part = a[start:i].strip()
+                start = i + 1
+                if part and part not in out:
+                    out.append(part)
+    return "Any" if "Any" in out else " | ".join(out)
+
+
+def _all(results: Any) -> bool | None:
+    """``True`` when every result is, ``False`` when every result is, else ``None``."""
+    rs = set(results)
+    return rs.pop() if len(rs) == 1 else None
+
+
+def _any(results: Any) -> bool | None:
+    """``True`` when a result is, ``False`` when every result is, else ``None``."""
+    rs = set(results)
+    if True in rs:
+        return True
+    return False if rs == {False} else None
+
+
+def as_validator(check: Any) -> Validator:
+    """``check`` as a validator: itself, a function wrapped in :class:`Custom`, or (``None``)
+    :data:`anything`."""
+    if check is None:
+        return anything
+    if isinstance(check, Validator):
+        return check
+    return Custom(check)
+
+
+# ---------------------------------------------------------------------------
+# Constructors and instances
+# ---------------------------------------------------------------------------
+
+def number(lo: float | None = None, hi: float | None = None, positive: bool = False,
+           integer: bool = False) -> Number:
+    return Number(lo, hi, positive, integer)
+
+
+def length(lo: float | None = None, positive: bool = False, *, percent: Any = None,
+           bare: str = "px", data: bool = False, font: bool = False, scaled: bool = True,
+           fr: bool = False, em: str | None = None) -> Length:
+    """Validator of a length (see :class:`Length`)."""
+    return Length(lo, positive, percent=percent, bare=bare, data=data, font=font,
+                  scaled=scaled, fr=fr, em=em)
+
+
+def angle(lo: float | None = None, hi: float | None = None) -> Angle:
+    """Validator of an angle: degrees, or ``deg``, ``grad``, ``rad``, ``turn``."""
+    return Angle(lo, hi)
+
+
+def one_of(*choices: str, aliases: dict[str, str] | None = None) -> Choice:
+    return Choice(*choices, aliases=aliases)
+
+
+def literal(*values: Any) -> Exact:
+    return Exact(*values)
+
+
+def either(*checks: Any) -> Either:
+    return Either(*(as_validator(c) for c in checks))
+
+
+def pair(check: Any) -> Pair:
+    return Pair(as_validator(check))
+
+
+boolean = Bool()
+text = Text()
+family = Family()
+anything = Custom(lambda v: v)
+dpi = Dpi()
+dpi_or_bool = Dpi(flag=True)
+
+
+class SimplifyValue(Dpi):
+    """``simplify``: what :class:`Dpi` takes (flag and ``"auto"``), or a
+    :class:`vec_io.Simplify` or a dict of its fields (checked, given unchanged)."""
+
+    __slots__ = ()
+
+    @property
+    def annotation(self) -> str:  # type: ignore[override]
+        return "SupportsFloat | str | bool | Simplify | Mapping[str, Any]"
+
+    def finish(self, x: Any, ctx: Any) -> Any:
+        if isinstance(x, (Simplify, dict)):
+            return x
+        return super().finish(x, ctx)
+
+    def parse(self, v: Any) -> Any:
+        if isinstance(v, Simplify):
+            return v
+        if isinstance(v, dict):
+            try:
+                Simplify(**v)
+            except ValueError as e:                # a field's value (OptionError)
+                raise ValueError(str(e)) from e
+            except TypeError as e:                 # an unknown field
+                raise ValueError(f"expected Simplify fields (dpi, tolerance), got "
+                                 f"{sorted(v)!r}") from e
+            return dict(v)
+        return super().parse(v)
+
+    def __repr__(self) -> str:
+        return "SimplifyValue()"
+
+
+simplify_value = SimplifyValue(flag=True, auto=True)
+
+
+@typed("Mapping[str, Any]")
+def _custom_vars(v: Any) -> dict[str, Any]:
+    if not isinstance(v, dict):
+        raise ValueError(f"expected a dict of variables, got {v!r}")
+    out = {}
+    for k, x in v.items():
+        if not isinstance(k, str) or not k.strip("-"):
+            raise ValueError(f"invalid variable name {k!r}")
+        if x is None:
+            raise ValueError(f"variable {k!r}: None is not a value")
+        out[k.lstrip("-")] = x
+    return out
+
+
+#: Custom variables: ``{"accent": "#c00", "gap": "4pt"}`` (names with or without the
+#: leading ``--``), read by ``var(--name)``.
+custom_vars = Custom(_custom_vars)
+
+
+# ---------------------------------------------------------------------------
+# Fonts and time zones
+# ---------------------------------------------------------------------------
+
+@typed("Literal['normal', 'bold'] | SupportsFloat | str")
+def font_weight(v: Any) -> Any:
+    """``normal``, ``bold`` or a weight 1–1000 (a number or a numeric string)."""
+    if isinstance(v, str) and v.strip().lower() in ("normal", "bold"):
+        return v.strip().lower()
+    if not isinstance(v, bool):
+        try:
+            w = float(v)
+        except (TypeError, ValueError, OverflowError):
+            w = math.nan
+        if 1 <= w <= 1000:
+            return v.strip() if isinstance(v, str) else v
+    raise ValueError(f"expected 'normal', 'bold' or a weight 1-1000, got {v!r}")
+
+
+_OBLIQUE = Angle(-90, 90)
+
+
+@typed("Literal['normal', 'italic', 'oblique'] | str")
+def font_style(v: Any) -> str:
+    """``normal``, ``italic``, ``oblique`` or ``"oblique <angle>"`` (−90°–90°)."""
+    if isinstance(v, str):
+        words = v.strip().lower().split(None, 1)
+        if len(words) == 1 and words[0] in ("normal", "italic", "oblique"):
+            return words[0]
+        if len(words) == 2 and words[0] == "oblique":
+            try:
+                _OBLIQUE(words[1])
+            except ValueError:
+                pass
+            else:
+                return f"oblique {words[1]}"
+    raise ValueError(f"expected 'normal', 'italic', 'oblique' or 'oblique <angle>', got {v!r}")
+
+
+_STRETCHES = ("ultra-condensed", "extra-condensed", "condensed", "semi-condensed", "normal",
+              "semi-expanded", "expanded", "extra-expanded", "ultra-expanded")
+
+
+@typed("str")
+def font_stretch(v: Any) -> str:
+    """A CSS ``font-stretch``: a keyword (``condensed``, …) or a percentage 50–200 %."""
+    if isinstance(v, str):
+        key = v.strip().lower().replace("_", "-")
+        if key in _STRETCHES:
+            return key
+        if key.endswith("%"):
+            try:
+                pct = float(key[:-1])
+            except ValueError:
+                pct = math.nan
+            if 50 <= pct <= 200:
+                return key
+    raise ValueError(f"expected a font-stretch keyword or a percentage 50%-200%, got {v!r}")
+
+
+#: The largest line height, as a multiple of the font size.
+_MAX_LINE_HEIGHT = 1000.0
+
+
+@typed("Literal['normal'] | SupportsFloat | str")
+def line_height(v: Any) -> Any:
+    """A CSS ``line-height``: ``"normal"`` (the font's ascent and descent), a multiple of
+    the font size (``1.2``) or a percentage of it (``"120%"``), at most 1000 times it."""
+    if isinstance(v, str):
+        key = v.strip().lower()
+        if key == "normal":
+            return key
+        if key.endswith("%"):
+            try:
+                pct = float(key[:-1])
+            except ValueError:
+                pct = math.nan
+            if 0 < pct <= 100 * _MAX_LINE_HEIGHT:
+                return pct / 100
+    elif (x := real(v)) is not None and 0 < x <= _MAX_LINE_HEIGHT:
+        return x
+    raise ValueError(f"expected 'normal', a positive number or a percentage (at most "
+                     f"{_MAX_LINE_HEIGHT:g} times the font size), got {v!r}")
+
+
+_VARIATION_RE = re.compile(r"""\s*(["'])(.{4})\1\s+([-+]?(?:\d+\.?\d*|\.\d+)(?:e[-+]?\d+)?)\s*""",
+                           re.I)
+
+
+@typed("Mapping[str, SupportsFloat] | str")
+def font_variations(v: Any) -> Any:
+    """Font variation settings: ``{"GRAD": 50}`` or ``'"GRAD" 50, "wght" 650'`` (axis tags
+    of 4 characters), or ``None``."""
+    if v is None:
+        return None
+    if isinstance(v, dict):
+        out = {}
+        for tag, x in v.items():
+            n = real(x)
+            if not (isinstance(tag, str) and len(tag) == 4) or n is None:
+                raise ValueError(f"expected {{axis tag: number}}, got {v!r}")
+            out[tag] = n
+        return out
+    if isinstance(v, str):
+        if v.strip().lower() == "normal":
+            return None
+        if all(_VARIATION_RE.fullmatch(part) for part in v.split(",")):
+            return v.strip()
+    raise ValueError(f"expected font variations such as {{'GRAD': 50}} or '\"GRAD\" 50', got {v!r}")
+
+
+@typed("tzinfo | str")
+def time_zone(v: Any) -> Any:
+    """A ``tzinfo``, or a zone name (``"Europe/Paris"``) as a ``zoneinfo.ZoneInfo``."""
+    if isinstance(v, datetime.tzinfo):
+        return v
+    if isinstance(v, str) and v.strip():
+        import zoneinfo
+        try:
+            return zoneinfo.ZoneInfo(v.strip())
+        except (zoneinfo.ZoneInfoNotFoundError, ValueError):
+            raise ValueError(f"unknown time zone {v!r}") from None
+    raise ValueError(f"expected a tzinfo or a time zone name, got {v!r}")