plot-io 0.12.0__py3-none-win_arm64.whl

plot_io/text.py

@@ -0,0 +1,412 @@
+"""Text: one line of plain or rich content shaped by :mod:`vec_io.text`, placed as a
+:class:`Run` and drawn from the same shaped line.
+
+Rich content is a list of strings and ``vec_io.Span`` objects.  Exponents are spans with
+``baseline_shift="super"`` and ``font_scale=0.7``.  Markup in strings (``<b>``, ``<i>``, …:
+:mod:`plot_io.markup`) becomes spans where text is shaped, when the font's ``markup`` is on
+(:func:`rich`).
+
+Text is shaped with a font database and needs no canvas (``fonts``: a ``FontDB``, or a
+canvas whose document's database is used).  A line is shaped once: plain strings are
+memoized in the font database, rich content in the render in progress; :func:`run` keeps
+the shaped line, so what the layout measured is what is drawn (kerned).
+
+The font databases of outputs come from :func:`document_db` (shared between renders, keyed
+by their font sources); :func:`has_family` tells whether a family has a face.
+"""
+
+import dataclasses
+import math
+import os
+import warnings
+from collections.abc import Iterator
+from typing import Any
+
+from vec_io import Span
+from vec_io import text as _text
+from vec_io.fonts.download import mode as _download_mode
+from vec_io.fonts.fontdb import GENERIC_FAMILIES, FontDB, env_font_dirs
+from vec_io.text import GlyphRun
+
+from .canvas import Canvas
+from . import markup as _markup
+
+__all__ = ["superscript", "Font", "font_of", "font_db", "document_db", "has_family", "shape",
+           "measure", "box", "Run", "run", "draw_run", "draw_text", "paragraphs", "wrap",
+           "runs_of", "plain", "rich", "lines_box", "lines_run"]
+
+_SUPER_SHIFT = 0.33
+_SUPER_SCALE = 0.7
+# Cap height in em (0.71-0.73 in common fonts): "center" centres digits and capitals.
+_CAP_HEIGHT = 0.72
+
+
+def superscript(text: str) -> Any:
+    return Span(text, baseline_shift="super", font_scale=_SUPER_SCALE)
+
+
+def runs_of(content: Any) -> Iterator[tuple[str, float, float]]:
+    """``(text, size factor, baseline shift in em)`` of each run."""
+    if isinstance(content, str):
+        yield content, 1.0, 0.0
+        return
+    for item in content:
+        if isinstance(item, str):
+            yield item, 1.0, 0.0
+        else:
+            shift = getattr(item, "baseline_shift", None)
+            scale = getattr(item, "font_scale", None) or 1.0
+            em = {"super": _SUPER_SHIFT, "sub": -0.2}.get(shift, shift) if shift else 0.0
+            yield item.text, float(scale), float(em or 0.0)
+
+
+def plain(content: Any) -> str:
+    """The text of content, without styles."""
+    return "".join(t for t, _, _ in runs_of(content))
+
+
+class Font:
+    """Font settings of a piece of text (sizes in px) and its color; :attr:`face` is the
+    ``vec_io.text.Font`` it is shaped with; ``markup``: whether markup in its strings is
+    read."""
+
+    __slots__ = ("size", "family", "weight", "style", "color", "stretch", "variations",
+                 "optical_sizing", "line_height", "markup", "_face")
+
+    def __init__(self, size: float, family: str = "sans-serif", weight: Any = "normal",
+                 style: str = "normal", color: Any = "black", stretch: str = "normal",
+                 variations: Any = None, optical_sizing: str = "auto",
+                 line_height: Any = "normal", markup: bool = True) -> None:
+        self.size = float(size)
+        self.family = family
+        self.weight = weight
+        self.style = style
+        self.color = color
+        self.stretch = stretch
+        self.variations = variations
+        self.optical_sizing = optical_sizing
+        self.line_height = line_height
+        self.markup = bool(markup)
+        self._face: _text.Font | None = None
+
+    @property
+    def face(self) -> _text.Font:
+        """The font description shaping uses (px; not the color)."""
+        if self._face is None:
+            self._face = _text.Font(self.family, self.size, weight=self.weight or "normal",
+                                    style=self.style or "normal",
+                                    stretch=self.stretch or "normal",
+                                    variations=self.variations or None,
+                                    optical_sizing=self.optical_sizing)
+        return self._face
+
+    def with_color(self, color: Any) -> "Font":
+        f = Font(self.size, self.family, self.weight, self.style, color, self.stretch,
+                 self.variations, self.optical_sizing, self.line_height, self.markup)
+        f._face = self._face
+        return f
+
+
+def font_of(obj: Any, size: float, weight: Any = "normal", style: str = "normal",
+            color: Any = "black", markup: bool | None = None) -> Font:
+    """The font of settings object ``obj`` (its family and inherited variation settings)
+    at ``size``; ``markup`` (default: ``obj``'s) whether markup in its text is read."""
+    return Font(size, obj.resolve("font_family"), weight or "normal", style or "normal", color,
+                obj.resolve("font_stretch"), obj.resolve("font_variations"),
+                obj.resolve("font_optical_sizing"), obj.resolve("line_height"),
+                obj.resolve("markup") if markup is None else markup)
+
+
+def font_db(fonts: Any) -> Any:
+    """The font database of ``fonts``: a ``FontDB``, a canvas (its document's) or ``None``
+    (vec_io's default database)."""
+    if fonts is None:
+        return _text.default_db()
+    doc = getattr(fonts, "document", None)
+    return doc.font_db if doc is not None else fonts
+
+
+#: The ``system`` of a ``fonts`` dict that does not give it (plot_io's tests turn it off, so
+#: that their text uses only the fonts of ``VEC_IO_FONT_DIRS``).
+SYSTEM_FONTS = True
+
+_DBS: dict[Any, FontDB] = {}
+
+
+def document_db(dirs: Any = None, system: bool | None = None, downloads: Any = None) -> FontDB:
+    """A font database for documents with these font sources (vec_io ``Fonts`` fields),
+    shared between renders (so are the shaped lines it memoizes); a change of
+    ``VEC_IO_FONT_DIRS`` or (with ``downloads=None``) ``VEC_IO_FONT_DOWNLOADS`` gives
+    another.  ``system=None``: :data:`SYSTEM_FONTS`."""
+    if system is None:
+        system = SYSTEM_FONTS
+    dirs = tuple(os.fspath(d) for d in dirs or ())
+    mode = _download_mode(downloads)
+    key = (dirs, bool(system), mode, tuple(env_font_dirs()))
+    db = _DBS.get(key)
+    if db is None:
+        if len(_DBS) >= 16:
+            _DBS.clear()
+        db = _DBS[key] = FontDB(list(dirs), bool(system), font_downloads=mode)
+    return db
+
+
+def has_family(db: Any, family: str) -> bool:
+    """Whether ``db`` has a face of one of the families of ``family`` (comma-separated;
+    generic families and metric aliases count), downloaded faces included."""
+    names = [n.strip().strip("\"'").lower() for n in family.split(",")]
+    if any(n in GENERIC_FAMILIES for n in names):
+        return True
+    if any(n and db.match(n, aliases=True) is not None for n in names):
+        return True
+    return any(n in f.families for f in db.all_faces() for n in names)
+
+
+def _hashable(v: Any) -> Any:
+    if isinstance(v, list):
+        return tuple(_hashable(x) for x in v)
+    if isinstance(v, dict):
+        return tuple(sorted((k, _hashable(x)) for k, x in v.items()))
+    return v
+
+
+_SPAN_KEYS = Span.__slots__
+
+
+def _content_key(content: Any) -> Any:
+    if isinstance(content, Span):
+        content = [content]
+    return tuple(item if isinstance(item, str) else
+                 tuple(_hashable(getattr(item, k, None)) for k in _SPAN_KEYS)
+                 for item in content)
+
+
+def rich(content: Any, font: Font) -> Any:
+    """``content`` with its markup written as spans when ``font.markup`` is on (strings
+    without markup as given); raises ``ValueError`` for an unclosed or crossed tag."""
+    return _markup.parse(content) if font.markup else content
+
+
+def shape(fonts: Any, content: Any, font: Font) -> GlyphRun:
+    """``content`` (its markup read, see :func:`rich`) shaped on one line with ``font``
+    (kerned).  Plain strings are memoized in the font database, rich content in the render
+    in progress."""
+    return _shape(fonts, rich(content, font), font)
+
+
+#: ``(id(db), family)`` pairs already checked for an installed face.
+_CHECKED: set[tuple[int, str]] = set()
+
+
+def _check_family(db: Any, family: str) -> None:
+    """Warns once per font database and family when no family of ``family`` has a face."""
+    key = (id(db), family)
+    if key in _CHECKED:
+        return
+    _CHECKED.add(key)
+    if not has_family(db, family):
+        warnings.warn(f"no font of the family {family!r} is installed: its text is drawn "
+                      f"with a fallback font", stacklevel=4)
+
+
+def _shape(fonts: Any, content: Any, font: Font) -> GlyphRun:
+    db = font_db(fonts)
+    if (id(db), font.family) not in _CHECKED:
+        _text.shape("", font.face, db)        # downloads the family when allowed
+        _check_family(db, font.family)
+    if isinstance(content, str):
+        return _text.shape(content, font.face, db)
+    from .spec import current
+    r = current()
+    if r is None:
+        return _text.shape(content, font.face, db)
+    key = (id(db), font.face, _content_key(content))
+    got = r.runs.get(key)
+    if got is None:
+        got = r.runs[key] = _text.shape(content, font.face, db)
+    return got
+
+
+def _empty(content: Any) -> bool:
+    return content is None or content == "" or content == []
+
+
+def half_leading(fonts: Any, font: Font) -> float:
+    """What ``font.line_height`` adds above and below a line (negative: takes away): half
+    the difference between it and the font's ascent and descent."""
+    if font.line_height == "normal":
+        return 0.0
+    g = _text.shape("", font.face, font_db(fonts))
+    return (font.line_height * font.size - g.ascent - g.descent) / 2
+
+
+def line_pitch(fonts: Any, font: Font) -> float:
+    """The distance between the baselines of lines of text in ``font``."""
+    g = _text.shape("", font.face, font_db(fonts))
+    return g.ascent + g.descent + 2 * half_leading(fonts, font)
+
+
+def measure(fonts: Any, content: Any, font: Font) -> tuple[float, float, float]:
+    """``(width, ascent, descent)`` of a line of content (see :func:`shape`), its box
+    ``font.line_height`` tall (see :func:`half_leading`)."""
+    if _empty(content):
+        return 0.0, 0.0, 0.0
+    g = shape(fonts, content, font)
+    lead = half_leading(fonts, font)
+    return g.width, g.ascent + lead, g.descent + lead
+
+
+def box(fonts: Any, content: Any, font: Font, rotation: float = 0.0) -> tuple[float, float]:
+    """Width and height of the bounding box of rotated text (degrees, counterclockwise)."""
+    w, a, d = measure(fonts, content, font)
+    h = a + d
+    if not rotation:
+        return w, h
+    r = math.radians(rotation)
+    c, s = abs(math.cos(r)), abs(math.sin(r))
+    return w * c + h * s, w * s + h * c
+
+
+@dataclasses.dataclass(frozen=True, slots=True)
+class Run:
+    """A line of content placed on the page: anchored at ``(x, y)``, its baseline start
+    ``(dx, dy)`` from the anchor in its own frame, rotated by ``rotation`` degrees
+    (counterclockwise) about the anchor; ``glyphs`` is the shaped line drawn."""
+
+    content: Any
+    x: float
+    y: float
+    font: Font
+    dx: float = 0.0
+    dy: float = 0.0
+    rotation: float = 0.0
+    glyphs: GlyphRun | None = dataclasses.field(default=None, compare=False, repr=False)
+
+
+def run(fonts: Any, content: Any, x: float, y: float, font: Font, ha: str = "left",
+        va: str = "baseline", rotation: float = 0.0) -> Run | None:
+    """``content`` anchored at ``(x, y)``: ``ha`` left/center/right, ``va``
+    baseline/top/center/bottom, in the text's own (rotated) frame (``center``: the middle
+    of the cap height); ``None`` for empty content.  The run holds the content with its
+    markup read."""
+    if _empty(content):
+        return None
+    content = rich(content, font)
+    g = _shape(fonts, content, font)
+    lead = half_leading(fonts, font)
+    w, a, d = g.width, g.ascent + lead, g.descent + lead
+    dx = {"left": 0.0, "center": -w / 2, "right": -w}[ha]
+    dy = {"baseline": 0.0, "top": a, "center": _CAP_HEIGHT * font.size / 2, "bottom": -d}[va]
+    return Run(content, x, y, font, dx, dy, rotation, g)
+
+
+def _block(fonts: Any, content: Any, font: Font
+           ) -> tuple[list[Any], list[tuple[float, float, float]], float, float] | None:
+    """Content of several lines (split at ``\\n``, its markup read): the lines, each
+    one's ``measure``, the distance between baselines and the block's height; ``None``
+    for one line."""
+    from .rows import lines
+    if _empty(content):
+        return None
+    ls = lines(content, font)
+    if len(ls) < 2:
+        return None
+    ms = [measure(fonts, ln, font) for ln in ls]
+    pitch = line_pitch(fonts, font)
+    return ls, ms, pitch, ms[0][1] + (len(ls) - 1) * pitch + ms[-1][2]
+
+
+def lines_box(fonts: Any, content: Any, font: Font, rotation: float = 0.0
+              ) -> tuple[float, float]:
+    """:func:`box` of content whose lines are split at ``\\n`` (stacked ``line_pitch``
+    apart)."""
+    b = _block(fonts, content, font)
+    if b is None:
+        return box(fonts, content, font, rotation)
+    w, h = max(m[0] for m in b[1]), b[3]
+    if not rotation:
+        return w, h
+    r = math.radians(rotation)
+    c, s = abs(math.cos(r)), abs(math.sin(r))
+    return w * c + h * s, w * s + h * c
+
+
+def lines_run(fonts: Any, content: Any, x: float, y: float, font: Font, ha: str = "left",
+              va: str = "baseline", rotation: float = 0.0) -> "Run | tuple[Run, ...] | None":
+    """:func:`run` of content whose lines are split at ``\\n``: a run per line, each
+    aligned by ``ha``, the block placed by ``va`` (``center``: its middle; ``baseline``:
+    the first line's), all rotated about the anchor."""
+    b = _block(fonts, content, font)
+    if b is None:
+        return run(fonts, content, x, y, font, ha, va, rotation)
+    ls, ms, pitch, h = b
+    top = {"baseline": -ms[0][1], "top": 0.0, "center": -h / 2, "bottom": -h}[va]
+    out = []
+    for k, ln in enumerate(ls):
+        r = run(fonts, ln, x, y, font, ha, "baseline", rotation)
+        if r is not None:
+            out.append(dataclasses.replace(r, dy=top + ms[0][1] + k * pitch))
+    return tuple(out)
+
+
+def draw_run(canvas: Canvas, r: "Run | tuple[Run | None, ...] | None") -> None:
+    """Draw a placed run (a tuple: each of its runs, the lines of a wrapped label; nothing
+    for ``None``) in its font's color; the canvas' text alignment is ``start`` while
+    plot_io draws."""
+    if isinstance(r, tuple):
+        for one in r:
+            draw_run(canvas, one)
+        return
+    if r is None:
+        return
+    g = r.glyphs if r.glyphs is not None else shape(canvas, r.content, r.font)
+    if not r.rotation:
+        canvas.draw_text(g, r.x + r.dx, r.y + r.dy, fill=r.font.color, stroke=None)
+        return
+    with canvas.state():
+        canvas.translate(r.x, r.y)
+        canvas.rotate(-r.rotation)
+        canvas.draw_text(g, r.dx, r.dy, fill=r.font.color, stroke=None)
+
+
+def draw_text(canvas: Canvas, content: Any, x: float, y: float, font: Font, ha: str = "left",
+              va: str = "baseline", rotation: float = 0.0) -> None:
+    """Draw a line of content anchored at ``(x, y)`` (see :func:`run`)."""
+    draw_run(canvas, run(canvas, content, x, y, font, ha, va, rotation))
+
+
+def wrap(fonts: Any, content: Any, font: Font, width: float) -> Any:
+    """String ``content`` with its lines broken at spaces into lines at most ``width``
+    wide (a word longer than that keeps its own line); other content as given."""
+    if not isinstance(content, str) or measure(fonts, content, font)[0] <= width:
+        return content
+    out = []
+    for line in content.split("\n"):
+        cur = ""
+        for word in line.split(" "):
+            trial = word if not cur else cur + " " + word
+            if cur and measure(fonts, trial, font)[0] > width:
+                out.append(cur)
+                cur = word
+            else:
+                cur = trial
+        out.append(cur)
+    return "\n".join(out)
+
+
+def paragraphs(fonts: Any, content: Any, font: Font, width: float, align: str = "start") -> Any:
+    """``content`` (its markup read, see :func:`rich`) broken into lines ``width`` wide
+    (``vec_io.text.layout``: kerned, lines ``font.line_height`` apart, 1.2 for ``normal``):
+    ``Paragraphs`` to draw with :func:`draw_paragraphs`."""
+    lh = 1.2 if font.line_height == "normal" else font.line_height
+    return _text.layout(rich(content, font), font.face, width, db=font_db(fonts),
+                        text_align=align, line_height=lh)
+
+
+def draw_paragraphs(canvas: Canvas, p: Any, x: float, y: float, fill: Any) -> None:
+    """Draw paragraphs ``p`` (see :func:`paragraphs`) with the top-left corner of their box
+    at ``(x, y)``; glyphs without a colour in ``fill`` (``None``: the canvas' fill)."""
+    if fill is None:
+        canvas.draw_paragraphs(p, x, y)
+    else:
+        canvas.draw_paragraphs(p, x, y, fill=fill)