plot-io 0.12.0__py3-none-win_amd64.whl

plot_io/canvas.py

@@ -0,0 +1,389 @@
+"""The canvas plot_io draws on, and a canvas that records the drawing.
+
+:class:`Canvas` is the protocol of what plot_io calls: drawing state attributes, the
+transform, clips, groups and vec_io's drawing calls, typed as ``vec_io.Page``'s; a vec_io
+page is one.  ``document`` gives the font database text is shaped with and the points per
+unit (:class:`CanvasDocument`).
+
+:class:`Recording` is a canvas that draws nothing: it records each call and each state
+assignment, in order, as plain data (``items``, ``dump()``, ``digest()``), so a figure's
+drawing can be compared under any vec_io version.  Text is still measured with vec_io's
+fonts (the recording's ``font_db``).
+"""
+
+import contextlib
+import hashlib
+import json
+import math
+from collections.abc import Generator, Sequence
+from contextlib import AbstractContextManager
+from typing import Any, Protocol, Unpack, overload
+
+import vec_io
+from vec_io.types import ArrayLike, Dashes, ItemStyle, LineStyle, PaintLike, SegmentStyle
+
+__all__ = ["Canvas", "CanvasDocument", "Recording"]
+
+
+class CanvasDocument(Protocol):
+    """What plot_io reads of a canvas' document: the font database text is shaped with and
+    the points per canvas unit (``0.75`` for px)."""
+
+    @property
+    def font_db(self) -> Any: ...
+
+    @property
+    def points_per_unit(self) -> float: ...
+
+
+class Canvas(Protocol):
+    """The drawing surface plot_io draws on (a ``vec_io.Page`` is one): drawing state
+    attributes, the transform and clip, groups and vec_io's drawing calls, with
+    ``vec_io.Page``'s signatures."""
+
+    fill: vec_io.Paint
+    stroke: vec_io.Paint
+    stroke_width: float
+    stroke_linecap: str
+    stroke_linejoin: str
+    stroke_dasharray: Any
+    opacity: float
+    text_anchor: str
+
+    @property
+    def document(self) -> CanvasDocument: ...
+
+    def state(self, **style: Unpack[vec_io.Style]) -> AbstractContextManager[Any]: ...
+
+    def translate(self, tx: float, ty: float) -> None: ...
+
+    def scale(self, sx: float, sy: float | None = None) -> None: ...
+
+    def rotate(self, degrees: float, cx: float = 0.0, cy: float = 0.0) -> None: ...
+
+    @overload
+    def transform(self, a: vec_io.Matrix) -> None: ...
+
+    @overload
+    def transform(self, a: float, b: float, c: float, d: float, e: float, f: float) -> None: ...
+
+    def clip(self, path: vec_io.Path | str, *, clip_rule: str | None = None) -> None: ...
+
+    def group(self, *, opacity: float = 1.0, rasterize: bool = False,
+              dpi: float | None = None) -> AbstractContextManager[Any]: ...
+
+    def draw_rect(self, x: float, y: float, width: float, height: float, *, rx: float = 0.0,
+                  ry: float | None = None, **style: Unpack[vec_io.Style]) -> None: ...
+
+    def draw_path(self, path: vec_io.Path | str, **style: Unpack[vec_io.Style]) -> None: ...
+
+    def draw_text(self, text: "str | vec_io.Content | vec_io.GlyphRun", x: float, y: float,
+                  **style: Unpack[vec_io.Style]) -> None: ...
+
+    def draw_markers(self, x: ArrayLike, y: ArrayLike, *,
+                     marker: "vec_io.Path | str | vec_io.Marker | Sequence[vec_io.Path | str]"
+                     " | None" = None,
+                     size: float | ArrayLike = 6.0, fill: PaintLike = ...,
+                     stroke: PaintLike = ..., stroke_width: float | ArrayLike | None = None,
+                     opacity: float | ArrayLike = 1.0,
+                     simplify: bool | float | str | None = None,
+                     **style: Unpack[ItemStyle]) -> None: ...
+
+    def draw_lines(self, x: ArrayLike | Sequence[ArrayLike],
+                   y: ArrayLike | Sequence[ArrayLike], *, stroke: PaintLike = ...,
+                   stroke_width: float | ArrayLike | None = None,
+                   stroke_dasharray: Dashes | Sequence[Dashes] = None,
+                   opacity: float | ArrayLike = 1.0,
+                   stroke_linecap: str | None = None, stroke_linejoin: str | None = None,
+                   simplify: bool | float | str | None = None,
+                   interpolation: str | Sequence[str] = "linear", missing: str = "break",
+                   **style: Unpack[LineStyle]) -> None: ...
+
+    def draw_segments(self, x0: float | ArrayLike, y0: float | ArrayLike,
+                      x1: float | ArrayLike, y1: float | ArrayLike, *,
+                      stroke: PaintLike = ..., stroke_width: float | ArrayLike | None = None,
+                      opacity: float | ArrayLike = 1.0, stroke_linecap: str | None = None,
+                      simplify: bool | float | str | None = None,
+                      **style: Unpack[SegmentStyle]) -> None: ...
+
+    def draw_rects(self, x: float | ArrayLike, y: float | ArrayLike,
+                   width: float | ArrayLike, height: float | ArrayLike, *,
+                   fill: PaintLike = ..., stroke: PaintLike = ...,
+                   stroke_width: float | ArrayLike | None = None,
+                   opacity: float | ArrayLike = 1.0,
+                   simplify: bool | float | str | None = None,
+                   **style: Unpack[ItemStyle]) -> None: ...
+
+    def draw_polygons(self, paths: "Sequence[vec_io.Path | str] | tuple[ArrayLike, ...]", *,
+                      fill: PaintLike = ..., stroke: PaintLike = None,
+                      stroke_width: float | ArrayLike | None = None,
+                      opacity: float | ArrayLike = 1.0,
+                      simplify: bool | float | str | None = None,
+                      **style: Unpack[ItemStyle]) -> None: ...
+
+    def draw_area(self, x: ArrayLike, y1: ArrayLike, y2: float | ArrayLike = 0.0, *,
+                  fill: vec_io.Paint = ..., stroke: vec_io.Paint = None,
+                  stroke_width: float | None = None, opacity: float = 1.0,
+                  simplify: bool | float | str | None = None,
+                  interpolation: str = "linear", missing: str = "break",
+                  **style: Unpack[ItemStyle]) -> None: ...
+
+    def draw_cells(self, x_edges: ArrayLike, y_edges: ArrayLike, fill: Any, *,
+                   palette: Sequence[vec_io.ColorLike] | None = None,
+                   bounds: ArrayLike | None = None, bad: vec_io.ColorLike | None = None,
+                   mode: str = "image", opacity: float = 1.0) -> None: ...
+
+    def draw_paragraphs(self, paragraphs: "vec_io.text.Paragraphs", x: float, y: float,
+                        **style: Unpack[vec_io.Style]) -> None: ...
+
+
+#: The drawing state attributes of :class:`Canvas` and their values on a new canvas.
+_STATE = {"fill": "black", "stroke": None, "stroke_width": 1.0, "stroke_linecap": "butt",
+          "stroke_linejoin": "miter", "stroke_dasharray": None, "opacity": 1.0,
+          "text_anchor": "start"}
+
+#: The names of the positional arguments of each call (to read each value in its unit).
+_POSITIONAL = {
+    "state": (), "group": (), "translate": ("tx", "ty"), "scale": ("sx", "sy"),
+    "rotate": ("degrees", "cx", "cy"), "transform": ("a", "b", "c", "d", "e", "f"),
+    "clip": ("path",), "draw_rect": ("x", "y", "width", "height"), "draw_path": ("path",),
+    "draw_text": ("text", "x", "y"), "draw_markers": ("x", "y"), "draw_lines": ("x", "y"),
+    "draw_segments": ("x0", "y0", "x1", "y1"), "draw_rects": ("x", "y", "width", "height"),
+    "draw_polygons": ("paths",), "draw_area": ("x", "y1", "y2"),
+    "draw_cells": ("x_edges", "y_edges", "fill"),
+    "draw_paragraphs": ("paragraphs", "x", "y"),
+}
+
+#: Arguments in px, rounded to 1/64 px (:data:`plot_io.geometry.GRID`); colours are kept
+#: as given; other numbers keep 12 significant digits.
+_PX = frozenset({"tx", "ty", "cx", "cy", "e", "f", "path", "paths", "x", "y", "x0", "y0",
+                 "x1", "y1", "y2", "width", "height", "rx", "ry", "size", "stroke_width",
+                 "stroke_dasharray", "x_edges", "y_edges", "text", "paragraphs"})
+_COLORS = frozenset({"fill", "stroke", "palette", "bad"})
+_GRID = 64
+
+
+def _number(v: float, px: bool) -> float:
+    if not math.isfinite(v):
+        return v
+    r = round(v * _GRID) / _GRID if px else float(f"{v:.12g}")
+    return 0.0 if r == 0 else r
+
+
+def _run(run: Any) -> dict[str, Any]:
+    """A glyph run as its text and its segments (see :func:`_glyphs`)."""
+    return {"text": run.text, "segments": _glyphs(run.glyphs)}
+
+
+def _glyphs(glyphs: Any) -> list[list[Any]]:
+    """Glyphs as segments ``[text, font, size, advance, colour, synthetic]``: consecutive
+    glyphs of one face, size, colour and synthetic bold and italic."""
+    out: list[list[Any]] = []
+    key = None
+    for g in glyphs:
+        k = (g.face.postscript_name, g.style.size, g.style.color, list(g.synth))
+        if k != key:
+            out.append(["", k[0], k[1], 0.0, k[2], k[3]])
+            key = k
+        out[-1][0] += g.text
+        out[-1][3] += g.advance + g.adjust
+    for seg in out:
+        seg[2:5] = _number(seg[2], False), _number(seg[3], True), _plain(seg[4], "color")
+    return out
+
+
+def _lines(paragraphs: Any) -> list[Any]:
+    """Placed paragraph lines: x offset, baseline and segments."""
+    return [[_number(ln.offset, True), _number(ln.baseline, True), _glyphs(ln.glyphs)]
+            for ln in paragraphs.line_cells() if ln.glyphs]
+
+
+def _plain(value: Any, kind: str = "px") -> Any:
+    """``value`` as JSON data: numbers rounded by ``kind`` (``"px"``: to 1/64 px;
+    ``"color"``: as given; else 12 significant digits), paths as their segments, glyph
+    runs as their text and segments, sequences and buffers as lists, objects as their
+    class name and fields."""
+    if value is None or isinstance(value, (bool, str)):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return value if kind == "color" else _number(value, kind == "px")
+    if isinstance(value, vec_io.Path):
+        return [[s[0], *(_plain(v, kind) for v in s[1:])] for s in value]
+    if isinstance(value, vec_io.GlyphRun):
+        return _run(value)
+    if isinstance(value, vec_io.Matrix):
+        return ["Matrix", *(_plain(float(v), "") for v in (value.a, value.b, value.c, value.d)),
+                _plain(float(value.e), kind), _plain(float(value.f), kind)]
+    if hasattr(value, "line_cells"):
+        return _lines(value)
+    if hasattr(value, "tolist") and not isinstance(value, type):
+        return _plain(value.tolist(), kind)
+    if isinstance(value, dict):
+        return {str(k): _plain(v, kind) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_plain(v, kind) for v in value]
+    if isinstance(value, (bytes, bytearray)):
+        return value.hex()
+    fields = getattr(type(value), "__slots__", None) or getattr(value, "__dict__", None)
+    if fields:
+        names = [fields] if isinstance(fields, str) else list(fields)
+        return {"type": type(value).__name__,
+                **{n: _plain(getattr(value, n), kind) for n in names
+                   if not n.startswith("_") and hasattr(value, n)}}
+    text = repr(value)
+    if " at 0x" in text:
+        raise TypeError(f"a recording cannot record {type(value).__name__} values")
+    return text
+
+
+def _kind(name: str) -> str:
+    return "px" if name in _PX else "color" if name in _COLORS else ""
+
+
+class _Document:
+    """The document of a :class:`Recording`: px (``points_per_unit`` 0.75) and its font
+    database."""
+
+    points_per_unit = 0.75
+
+    def __init__(self, font_db: Any) -> None:
+        self.font_db = font_db
+
+
+class Recording:
+    """A :class:`Canvas` ``width`` × ``height`` px that draws nothing and records what is
+    drawn on it: each call and each state assignment is one item ``(member, args,
+    keywords)``, in order, as plain data (numbers in px rounded to 1/64 px, paths as their
+    segments, glyph runs as their text, font, size and advance, colours as given).  A
+    ``with`` block of ``state()`` or ``group()`` ends with the item ``("end",
+    (member,), {})``.  Text is shaped with ``font_db`` (default: the font database plot_io
+    writes with).
+
+    ``items``: the items; ``dump()``: one JSON line per item; ``digest()``: the SHA-256 of
+    the dump.  :meth:`add` records an item: a subclass extends it to see the values as
+    given."""
+
+    fill: vec_io.Paint
+    stroke: vec_io.Paint
+    stroke_width: float
+    stroke_linecap: str
+    stroke_linejoin: str
+    stroke_dasharray: Any
+    opacity: float
+    text_anchor: str
+    width: float
+    height: float
+    items: list[tuple[str, tuple[Any, ...], dict[str, Any]]]
+    _document: _Document
+    _saved: list[dict[str, Any]]
+
+    def __init__(self, width: float, height: float, font_db: Any = None) -> None:
+        if font_db is None:
+            from .render import font_db_of, fonts_of
+            font_db = font_db_of(fonts_of(None, {}))
+        object.__setattr__(self, "width", float(width))
+        object.__setattr__(self, "height", float(height))
+        object.__setattr__(self, "items", [])
+        object.__setattr__(self, "_document", _Document(font_db))
+        object.__setattr__(self, "_saved", [])
+        for name, value in _STATE.items():
+            object.__setattr__(self, name, value)
+
+    @property
+    def document(self) -> CanvasDocument:
+        return self._document
+
+    def __setattr__(self, name: str, value: Any) -> None:
+        if name in _STATE:
+            self.add(name, (value,), {})
+        object.__setattr__(self, name, value)
+
+    def add(self, member: str, args: tuple[Any, ...], keywords: dict[str, Any]) -> None:
+        """Record call ``member(*args, **keywords)`` (or, for a state attribute, its
+        assignment: ``args`` is the value)."""
+        names = (member,) if member in _STATE else _POSITIONAL.get(member, ())
+        plain_args = tuple(_plain(v, _kind(names[k]) if k < len(names) else "")
+                           for k, v in enumerate(args))
+        plain_kw = {k: _plain(v, _kind(k)) for k, v in keywords.items()}
+        self.items.append((member, plain_args, plain_kw))
+
+    def dump(self) -> str:
+        """The items, one JSON line each (``[member, args, keywords]``)."""
+        return "".join(json.dumps([m, list(a), k], sort_keys=True, separators=(",", ":"))
+                       + "\n" for m, a, k in self.items)
+
+    def digest(self) -> str:
+        """The SHA-256 (hex) of :meth:`dump`."""
+        return hashlib.sha256(self.dump().encode()).hexdigest()
+
+    @contextlib.contextmanager
+    def _scope(self, member: str, keywords: dict[str, Any]) -> Generator["Recording"]:
+        self.add(member, (), keywords)
+        self._saved.append({k: getattr(self, k) for k in _STATE})
+        for k, v in keywords.items():
+            if k in _STATE:
+                object.__setattr__(self, k, v)
+        try:
+            yield self
+        finally:
+            for k, v in self._saved.pop().items():
+                object.__setattr__(self, k, v)
+            self.add("end", (member,), {})
+
+    def state(self, **style: Any) -> AbstractContextManager["Recording"]:
+        return self._scope("state", style)
+
+    def group(self, **options: Any) -> AbstractContextManager["Recording"]:
+        return self._scope("group", options)
+
+    def translate(self, *args: Any, **kw: Any) -> None:
+        self.add("translate", args, kw)
+
+    def scale(self, *args: Any, **kw: Any) -> None:
+        self.add("scale", args, kw)
+
+    def rotate(self, *args: Any, **kw: Any) -> None:
+        self.add("rotate", args, kw)
+
+    def transform(self, *args: Any, **kw: Any) -> None:
+        self.add("transform", args, kw)
+
+    def clip(self, *args: Any, **kw: Any) -> None:
+        self.add("clip", args, kw)
+
+    def draw_rect(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_rect", args, kw)
+
+    def draw_path(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_path", args, kw)
+
+    def draw_text(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_text", args, kw)
+
+    def draw_markers(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_markers", args, kw)
+
+    def draw_lines(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_lines", args, kw)
+
+    def draw_segments(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_segments", args, kw)
+
+    def draw_rects(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_rects", args, kw)
+
+    def draw_polygons(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_polygons", args, kw)
+
+    def draw_area(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_area", args, kw)
+
+    def draw_cells(self, *args: Any, **kw: Any) -> None:
+        self.add("draw_cells", args, kw)
+
+    def draw_paragraphs(self, *args: Any, **kw: Any) -> None:
+        """Paragraphs (``vec_io.text`` ``Paragraphs``) with the top-left corner of their box
+        at ``(x, y)``: recorded as their placed lines (x offset, baseline, segments)."""
+        self.add("draw_paragraphs", args, kw)

plot_io/color/__init__.py

@@ -0,0 +1,3 @@
+"""Colors: values and named scales (:mod:`.values`), color maps, every set of colors with
+its kind: qualitative, sequential, diverging, cyclic (:mod:`.maps`), and the bundled data
+(:mod:`.data`).  Color space conversions are vec_io's (:mod:`vec_io.paint`)."""