plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/markup.py

@@ -0,0 +1,128 @@
+"""Text markup: tags in strings written as ``vec_io.Span`` objects.
+
+``<i>``/``<em>`` (italic), ``<b>``/``<strong>`` (bold), ``<u>`` (underline),
+``<s>``/``<del>`` (strikethrough), ``<sup>`` and ``<sub>`` (raised and lowered, 0.7 of the
+size), in either case, nested in any order, each closed by its own end tag.  Any other
+``<`` is text; ``&lt;``, ``&gt;`` and ``&amp;`` write a literal ``<``, ``>`` or ``&``.  Styles
+add to the text's own (``<b>`` in bold text stays bold).
+
+:func:`parse` turns content (a string, or a list of strings and spans: its strings are
+parsed) into rich content; text without tags or entities is returned as given.  The result
+parses to itself: literal text that could read as markup is kept in spans.
+"""
+
+import functools
+import re
+from typing import Any
+
+from vec_io import Span
+
+__all__ = ["TAGS", "parse", "check", "check_settings"]
+
+_SCALE = 0.7
+
+#: Tag → the span attributes it sets.
+TAGS: dict[str, dict[str, Any]] = {
+    "i": {"font_style": "italic"}, "em": {"font_style": "italic"},
+    "b": {"font_weight": "bold"}, "strong": {"font_weight": "bold"},
+    "u": {"underline": True},
+    "s": {"strikethrough": True}, "del": {"strikethrough": True},
+    "sup": {"baseline_shift": "super", "font_scale": _SCALE},
+    "sub": {"baseline_shift": "sub", "font_scale": _SCALE},
+}
+_ENTITIES = {"lt": "<", "gt": ">", "amp": "&"}
+_TOKEN = re.compile(r"<(/?)(%s)>|&(lt|gt|amp);" % "|".join(sorted(TAGS, key=len, reverse=True)),
+                    re.IGNORECASE)
+
+
+def _piece(text: str, open_: list[str]) -> Any:
+    """Text under the open tags: a span, or a string when nothing applies and it holds no
+    ``<`` or ``&`` (which a second parse would read)."""
+    if not open_ and "<" not in text and "&" not in text:
+        return text
+    attrs: dict[str, Any] = {}
+    for tag in open_:
+        attrs.update(TAGS[tag])
+    return Span(text, **attrs)
+
+
+@functools.lru_cache(maxsize=4096)
+def _parse(s: str) -> str | tuple[Any, ...]:
+    open_: list[str] = []
+    out: list[Any] = []
+    buf: list[str] = []
+    pos = 0
+    found = False
+
+    def flush() -> None:
+        text = "".join(buf)
+        buf.clear()
+        if text:
+            out.append(_piece(text, open_))
+
+    for m in _TOKEN.finditer(s):
+        found = True
+        buf.append(s[pos:m.start()])
+        pos = m.end()
+        if m.group(3) is not None:
+            buf.append(_ENTITIES[m.group(3).lower()])
+            continue
+        tag = m.group(2).lower()
+        flush()
+        if not m.group(1):
+            open_.append(tag)
+        elif not open_:
+            raise ValueError(f"markup: </{tag}> without <{tag}> in {s!r}")
+        elif open_[-1] != tag:
+            raise ValueError(f"markup: </{tag}> closes <{open_[-1]}> in {s!r}")
+        else:
+            open_.pop()
+    if not found:
+        return s
+    if open_:
+        raise ValueError(f"markup: unclosed <{open_[-1]}> in {s!r}")
+    buf.append(s[pos:])
+    flush()
+    return tuple(out)
+
+
+def parse(content: Any) -> Any:
+    """``content`` with its markup written as spans: a string without tags or entities as
+    given, else rich content (a list); spans are kept as they are.  Raises ``ValueError``
+    for an unclosed or crossed tag."""
+    if isinstance(content, str):
+        got = _parse(content)
+        return got if isinstance(got, str) else list(got)
+    if not isinstance(content, (list, tuple)):
+        return content
+    if not any(isinstance(item, str) and isinstance(_parse(item), tuple) for item in content):
+        return content
+    out: list[Any] = []
+    for item in content:
+        got = _parse(item) if isinstance(item, str) else item
+        out.extend(got if isinstance(got, tuple) else (got,))
+    return out
+
+
+def check(content: Any) -> None:
+    """Raise ``ValueError`` if the markup of ``content`` is unclosed or crossed."""
+    if isinstance(content, str):
+        _parse(content)
+    elif isinstance(content, (list, tuple)):
+        for item in content:
+            if isinstance(item, str):
+                _parse(item)
+
+
+def check_settings(obj: Any, values: dict[str, Any]) -> None:
+    """Check the markup of the text settings of ``obj`` (resolved ``values``) when its
+    ``markup`` is on; the error names the setting."""
+    from .settings import text
+    if not values.get("markup"):
+        return
+    for name, s in obj.SETTINGS.items():
+        if s.check is text:
+            try:
+                check(values[name])
+            except ValueError as e:
+                raise ValueError(f"{obj.kind} setting {name!r}: {e}") from None

plot_io/numbers.py

@@ -0,0 +1,354 @@
+"""Numbers as text: one formatter for tick labels, colorbars and heatmap cell labels.
+
+``fmt`` is ``"auto"``, a format string, a callable, or a preset (``"percent"``,
+``"sci"``, ``"eng"``, ``"si"``, ``"int"``).  A :class:`NumberStyle` carries the decimal
+and thousands separators, the minus sign, a prefix and suffix, and the precision.
+"""
+
+import decimal
+import math
+import re
+from collections.abc import Sequence
+from typing import Any
+
+from vec_io import Span
+
+from .validators import typed
+
+__all__ = ["NumberStyle", "format_numbers", "format_axis", "PRESETS", "check_format",
+           "additive_offset", "offset_label", "apply_format"]
+
+PRESETS = ("auto", "percent", "sci", "eng", "si", "int")
+_SI = {-24: "y", -21: "z", -18: "a", -15: "f", -12: "p", -9: "n", -6: "µ", -3: "m",
+       0: "", 3: "k", 6: "M", 9: "G", 12: "T", 15: "P", 18: "E", 21: "Z", 24: "Y"}
+_MINUS = {"hyphen": "-", "minus": "−"}
+
+
+@typed("str | Callable[..., Any]")
+def check_format(v: Any) -> Any:
+    if callable(v):
+        return v
+    if isinstance(v, str):
+        key = v.strip().lower()
+        if key in PRESETS:
+            return key
+        if "%" in v and "{" not in v:            # printf (numbers), strftime (time axes)
+            return v
+        if "{" in v:
+            try:
+                v.format(1.5)
+            except (IndexError, KeyError, ValueError) as e:
+                raise ValueError(f"invalid format string {v!r}: {e}") from None
+            return v
+        if v.strip():                             # a format spec: ".2f"
+            try:
+                format(1.5, v)
+                return v
+            except ValueError:
+                pass
+    raise ValueError(f"expected 'auto', a preset ({', '.join(PRESETS[1:])}), a format "
+                     f"string or a function, got {v!r}")
+
+
+def apply_format(fmt: str, v: Any, what: str = "tick_format") -> str:
+    """``v`` written by a format string: ``"{:.2f}"`` (``str.format``), ``"%.2f"``
+    (printf) or a bare format spec (``".2f"``)."""
+    try:
+        if "{" in fmt:
+            return fmt.format(v)
+        if "%" in fmt:
+            return fmt % v
+        return format(v, fmt)
+    except (TypeError, ValueError) as e:
+        raise ValueError(f"{what} {fmt!r} on {v!r}: {e}") from None
+
+
+class NumberStyle:
+    """Separators, minus sign, affixes and precision of formatted numbers."""
+
+    __slots__ = ("decimal", "thousands", "minus", "prefix", "suffix", "precision")
+
+    def __init__(self, decimal_separator: str = ".", thousands_separator: str = "",
+                 minus: str = "hyphen", prefix: str = "", suffix: str = "",
+                 precision: int | None = None) -> None:
+        self.decimal = decimal_separator
+        self.thousands = thousands_separator
+        self.minus = _MINUS[minus]
+        self.prefix = prefix
+        self.suffix = suffix
+        self.precision = precision
+
+    @classmethod
+    def of(cls, obj: Any) -> "NumberStyle":
+        """The style from an object's (inherited) settings."""
+        return cls(obj.resolve("decimal_separator"), obj.resolve("thousands_separator"),
+                   obj.resolve("minus"), obj.resolve("prefix"), obj.resolve("suffix"),
+                   obj.resolve("precision"))
+
+    def digits(self, s: str) -> str:
+        """A plain decimal string (``-1234.5``) with this style's signs and separators."""
+        neg = s.startswith("-")
+        if neg:
+            s = s[1:]
+        whole, _, frac = s.partition(".")
+        if self.thousands and len(whole) > 3:
+            groups = []
+            while len(whole) > 3:
+                groups.append(whole[-3:])
+                whole = whole[:-3]
+            groups.append(whole)
+            whole = self.thousands.join(reversed(groups))
+        out = whole + (self.decimal + frac if frac else "")
+        return (self.minus if neg else "") + out
+
+    def exponent(self, k: int) -> str:
+        return (self.minus if k < 0 else "") + str(abs(k))
+
+    def wrap(self, label: Any) -> Any:
+        if not (self.prefix or self.suffix):
+            return label
+        if isinstance(label, str):
+            return self.prefix + label + self.suffix
+        return [self.prefix] + list(label) + [self.suffix]
+
+
+def _fixed(v: float, d: int) -> str:
+    """``v`` with ``d`` decimals, rounding halves away from zero on the shortest decimal
+    form (1234.5 → 1235, 2.675 → 2.68)."""
+    if not math.isfinite(v):
+        return str(v)
+    q = decimal.Decimal(repr(float(v))).quantize(decimal.Decimal(1).scaleb(-d),
+                                                 rounding=decimal.ROUND_HALF_UP)
+    s = f"{q:f}"
+    if s.startswith("-") and float(s) == 0:
+        s = s[1:]
+    return s
+
+
+def _decimals(values: Sequence[float], precision: int | None, cap: int = 12,
+              distinct: bool = True) -> int:
+    """The fewest decimals telling the values apart and representing them (or giving
+    ``precision`` significant digits to the largest; ``distinct``: more when they would not
+    tell the values apart)."""
+    finite = [v for v in values if math.isfinite(v)]
+    if not finite:
+        return 0
+    big = max(abs(v) for v in finite)
+    if precision is not None:
+        if big == 0:
+            return 0
+        e = math.floor(math.log10(big))
+        d = precision - 1 - e
+        if abs(float(_fixed(big, max(0, d)))) >= 10.0 ** (e + 1):
+            d -= 1                          # rounding reached the next power (9.96 → 10)
+        d = max(0, min(cap, d))
+        while distinct and d < cap and len({_fixed(v, d) for v in finite}) < len(set(finite)):
+            d += 1                          # enough decimals to tell the values apart
+        return d
+    span = max(finite) - min(finite)
+    tol = max(1e-12, 1e-9 * big, span * 1e-6)
+    for d in range(cap + 1):
+        labels = [_fixed(v, d) for v in finite]
+        if len(set(labels)) == len(set(finite)) and all(abs(float(s) - v) <= tol
+                                                        for s, v in zip(labels, finite)):
+            return d
+    return cap
+
+
+def _superscript(text: str) -> Any:
+    from .text import superscript
+    return superscript(text)
+
+
+def _exp_form(values: Sequence[float], style: NumberStyle, step: int,
+              si: bool = False) -> list[Any]:
+    """Mantissa × 10ᵏ labels (``step`` 1: sci, 3: eng) or SI prefixes."""
+    parts: list[tuple[float, int] | None] = []
+    for v in values:
+        if not math.isfinite(v):
+            parts.append(None)
+        elif v == 0:
+            parts.append((0.0, 0))
+        else:
+            k = math.floor(math.log10(abs(v)) / step) * step
+            parts.append((v / 10.0 ** k, k))
+    mants = [p[0] for p in parts if p is not None]
+    prec = style.precision
+    if prec is None:
+        d = _decimals(mants, None, 10)
+    elif step == 1:
+        d = prec - 1
+    else:
+        bigm = max((abs(m) for m in mants), default=0.0)
+        d = max(0, prec - 1 - math.floor(math.log10(bigm))) if bigm else 0
+    out: list[Any] = []
+    for p in parts:
+        if p is None:
+            out.append("")
+            continue
+        m, k = p
+        dd = d
+        s = _fixed(m, dd)
+        if abs(float(s)) >= 10 ** step and m:      # rounding reached the next power
+            m, k = m / 10 ** step, k + step
+            if prec is not None and step == 3:
+                dd = prec - 1                     # the rounded mantissa is 1
+            s = _fixed(m, dd)
+        if si and k in _SI:
+            out.append(style.wrap(style.digits(s) + _SI[k]))
+        elif k == 0 or float(s) == 0:
+            out.append(style.wrap(style.digits(s)))
+        else:
+            out.append(style.wrap([style.digits(s) + "×10", _superscript(style.exponent(k))]))
+    return out
+
+
+_NUMBER = re.compile(r"(-?)(\d{1,3}(?:,\d{3})+|\d+)(?:\.(\d+))?")
+
+
+def _restyle(text: str, style: NumberStyle) -> str:
+    """Separators and minus applied to the numbers inside a formatted string."""
+    def sub(m: re.Match) -> str:
+        whole = m.group(2)
+        commas = "," in whole
+        whole = whole.replace(",", "")
+        s = (m.group(1) or "") + whole + ("." + m.group(3) if m.group(3) else "")
+        if commas and not style.thousands:
+            return NumberStyle(style.decimal, ",", "hyphen" if style.minus == "-" else "minus"
+                               ).digits(s)
+        return style.digits(s)
+    return _NUMBER.sub(sub, text)
+
+
+def format_axis(values: Sequence[float], fmt: Any = "auto", style: NumberStyle | None = None,
+                sci_limits: tuple[int, int] | None = (-4, 5),
+                what: str = "tick_format", distinct: bool = True) -> tuple[list[Any], int]:
+    """Labels of a set of values formatted together, and the exponent of a common ×10ᵏ
+    factor (``"auto"`` beyond ``10^sci_limits``; 0: none).  ``sci_limits=None``: no
+    factor, the labels carry their exponent (``"sci"``) instead.  ``distinct``: a
+    ``precision`` keeps enough decimals to tell the values apart (ticks)."""
+    style = style or NumberStyle()
+    vals = list(values)
+    finite = [v for v in vals if math.isfinite(v)]
+    if hasattr(fmt, "format_all"):                 # formats the values together
+        return fmt.format_all(vals, style), 0
+    if callable(fmt):
+        out: list[Any] = []
+        for v in vals:
+            if not math.isfinite(v):
+                out.append("")
+                continue
+            try:
+                r = fmt(v)
+            except (TypeError, ValueError) as e:
+                raise ValueError(f"{what} function {fmt!r} on {v!r}: {e}") from None
+            if not isinstance(r, (str, list, Span)):
+                raise ValueError(f"{what} function {fmt!r} on {v!r} returned {r!r}, "
+                                 f"expected text")
+            out.append(style.wrap(_restyle(r, style)) if isinstance(r, str) else r)
+        return out, 0
+    if fmt not in PRESETS:
+        return [style.wrap(_restyle(apply_format(fmt, v, what), style))
+                if math.isfinite(v) else "" for v in vals], 0
+    if fmt == "int":
+        return [style.wrap(style.digits(_fixed(math.copysign(math.floor(abs(v) + 0.5), v), 0)))
+                if math.isfinite(v) else "" for v in vals], 0
+    if fmt == "sci":
+        return _exp_form(vals, style, 1), 0
+    if fmt == "eng":
+        return _exp_form(vals, style, 3), 0
+    if fmt == "si":
+        return _exp_form(vals, style, 3, si=True), 0
+    scale = 100.0 if fmt == "percent" else 1.0
+    exp = 0
+    big = max((abs(v) for v in finite), default=0.0) * scale
+    if fmt == "auto" and big:
+        if sci_limits is None:
+            pass
+        elif big >= 10.0 ** sci_limits[1] or big < 10.0 ** sci_limits[0]:
+            exp = math.floor(math.log10(big))
+    half = -exp // 2                   # two factors: 10³²⁰ overflows, 10¹⁶⁰ twice does not
+    k1, k2 = scale * 10.0 ** half, 10.0 ** (-exp - half)
+    scaled = [v * k1 * k2 for v in vals]
+    d = _decimals(scaled, style.precision, distinct=distinct)
+    pct = "%" if fmt == "percent" else ""
+    return [style.wrap(style.digits(_fixed(v, d)) + pct) if math.isfinite(v) else ""
+            for v in scaled], exp
+
+
+def additive_offset(values: Sequence[float]) -> float:
+    """The part common to tick values that their labels leave out (written once at the
+    axis end), when it saves at least four digits; 0: none.  Ticks of both signs, or a
+    single value, take none."""
+    finite = [v for v in values if math.isfinite(v)]
+    if len(finite) < 2:
+        return 0.0
+    lo, hi = min(finite), max(finite)
+    if lo == hi or lo <= 0 <= hi:
+        return 0.0
+    small, big = sorted((abs(lo), abs(hi)))
+    top = math.ceil(math.log10(big))
+    k = top
+    while k > top - 400 and math.floor(small / 10.0 ** k) == math.floor(big / 10.0 ** k):
+        k -= 1
+    k += 1
+    if (big - small) / 10.0 ** k <= 1e-2:      # straddling a multiple of a larger power
+        k = top
+        while k > top - 400 and big - small < 10.0 ** (k - 2):
+            k -= 1
+        k += 1
+    whole = math.floor(big / 10.0 ** k)
+    if whole < 1000:
+        return 0.0
+    shift = whole * 10.0 ** k
+    if k < 0:
+        shift = round(shift, -k)
+    return math.copysign(shift, lo)
+
+
+def offset_label(shift: float, style: NumberStyle) -> list[Any]:
+    """The text of an additive offset: ``+1×10⁹``, ``−1.25×10⁶``."""
+    k = math.floor(math.log10(abs(shift)))
+    m = abs(shift) / 10.0 ** k
+    s = f"{m:.12g}"
+    if float(s) >= 10:                          # rounding reached the next power
+        k += 1
+        s = f"{m / 10:.12g}"
+    sign = "+" if shift > 0 else style.minus
+    return [sign + style.digits(s) + "×10", _superscript(style.exponent(k))]
+
+
+def format_numbers(values: Sequence[float], fmt: Any = "auto",
+                   settings: Any = None, what: str = "value_label_format") -> list[Any]:
+    """Labels of values formatted together; ``settings`` is a :class:`NumberStyle` or an
+    object with the number settings.  ``"auto"`` beyond 10⁵ or below 10⁻⁴ writes each
+    label in scientific form (there is no axis to carry a common factor)."""
+    style = settings if isinstance(settings, NumberStyle) or settings is None \
+        else NumberStyle.of(settings)
+    style = style or NumberStyle()
+    labels, exp = format_axis(values, fmt, style, what=what, distinct=False)
+    if exp:
+        return _exp_form(list(values), style, 1)
+    return labels
+
+
+@typed("Literal['hyphen', 'minus']")
+def _check_minus(v: Any) -> str:
+    if v not in _MINUS:
+        raise ValueError(f"expected 'hyphen' or 'minus', got {v!r}")
+    return v
+
+
+@typed("int")
+def _check_precision(v: Any) -> int:
+    if isinstance(v, bool) or not isinstance(v, int) or not 1 <= v <= 15:
+        raise ValueError(f"expected an integer from 1 to 15, got {v!r}")
+    return v
+
+
+@typed("str")
+def _check_str(v: Any) -> str:
+    if not isinstance(v, str):
+        raise ValueError(f"expected a string, got {v!r}")
+    return v
+