codefig 0.17.0__py3-none-any.whl

codefig/icon.py

@@ -0,0 +1,288 @@
+"""Icon and Image nodes (v0.4.0).
+
+``Icon("gpu", size=16, color=…)`` draws a bundled Tabler icon (see :mod:`codefig.icons`)
+as inline vector paths; ``Icon.from_svg(path)`` loads any SVG file. ``Image(path,
+width=…)`` embeds a PNG / JPG / SVG (base64) with its aspect ratio preserved,
+``fit="contain" | "cover"``, rounded corners and an optional border.
+
+Both are *hard* obstacles (edges route around them, check_overlaps() flags crossings).
+Neither takes coordinates: they measure themselves and sit in Row / Col / Box like any node.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Any, List, Optional, Sequence, Tuple, Union
+
+from . import icons as _icons
+from .node import Node
+
+_SVG_NS = "{http://www.w3.org/2000/svg}"
+_PRESENTATION = ("fill", "stroke", "stroke-width", "stroke-linecap", "stroke-linejoin")
+
+
+class Icon(Node):
+    """A small vector pictogram.
+
+    name: bundled icon (``codefig.icons.list()``) or alias (frozen → snowflake,
+    trainable → flame, …). size: height in px (default ≈ 1.4 × theme font size).
+    color: stroke / fill colour. filled: Tabler's filled variant. stroke_width: line
+    weight in icon units (Tabler default 2 on a 24 grid). bg: optional disc / rounded
+    square behind the glyph (``bg_shape="circle" | "rounded"``).
+    """
+
+    def __init__(self, name: Optional[str] = None, *, size: Optional[float] = None,
+                 color: Optional[str] = None, filled: bool = False,
+                 stroke_width: Optional[float] = None, bg: Optional[str] = None,
+                 bg_shape: str = "circle", bg_pad: float = 0.22, opacity: float = 1.0,
+                 _spec: Optional[dict] = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        if _spec is None:
+            if name is None:
+                raise ValueError("Icon needs a name (codefig.icons.list()) or use Icon.from_svg()")
+            _spec = _icons.get(name, filled=filled)
+        if bg_shape not in ("circle", "rounded", "square"):
+            raise ValueError("bg_shape must be circle|rounded|square")
+        self.name = name
+        self.spec = _spec
+        self.size = None if size is None else float(size)
+        self.color = color
+        self.filled = filled
+        self.stroke_width = stroke_width
+        self.bg = bg
+        self.bg_shape = bg_shape
+        self.bg_pad = float(bg_pad)
+        self.opacity = float(opacity)
+
+    # ---- construction -------------------------------------------------------
+    @classmethod
+    def from_svg(cls, path: Union[str, Path], *, size: Optional[float] = None,
+                 color: Optional[str] = None, **kwargs: Any) -> "Icon":
+        """Load any SVG file. With ``color=`` every non-``none`` stroke / fill is
+        recoloured (monochrome icon); without it the file's own colours are kept."""
+        root = ET.fromstring(Path(path).read_text(encoding="utf-8"))
+        vb = root.get("viewBox")
+        if vb:
+            box = tuple(float(v) for v in re.split(r"[\s,]+", vb.strip()))
+        else:
+            w = float(re.sub(r"[^\d.]", "", root.get("width", "24")) or 24)
+            h = float(re.sub(r"[^\d.]", "", root.get("height", "24")) or 24)
+            box = (0.0, 0.0, w, h)
+        inherited = {k: root.get(k) for k in _PRESENTATION if root.get(k) is not None}
+        elems: List[str] = []
+        for child in root:
+            tag = child.tag.replace(_SVG_NS, "")
+            if tag in ("title", "desc", "metadata", "style"):
+                continue
+            for el in child.iter():
+                el.tag = el.tag.replace(_SVG_NS, "")
+                if color is not None:
+                    for a in ("fill", "stroke"):
+                        v = el.get(a)
+                        if v is not None and v != "none":
+                            el.set(a, color)
+            elems.append(ET.tostring(child, encoding="unicode").replace(' xmlns="http://www.w3.org/2000/svg"', ""))
+        if color is not None:
+            inherited = {k: (color if k in ("fill", "stroke") and v not in ("none",) else v)
+                         for k, v in inherited.items()}
+        spec = {"elements": elems, "viewbox": box, "mode": "native", "attrs": inherited}
+        return cls(None, size=size, color=color, _spec=spec, **kwargs)
+
+    # ---- layout -------------------------------------------------------------
+    def _size(self) -> float:
+        return self.size if self.size is not None else round(self.theme.font_size * 1.4, 1)
+
+    def _measure(self) -> Tuple[float, float]:
+        s = self._size()
+        _x, _y, vw, vh = self.spec["viewbox"]
+        w = s * vw / vh if vh else s
+        if self.bg:
+            p = 2 * self.bg_pad * s
+            return w + p, s + p
+        return w, s
+
+    def _color(self) -> str:
+        return self.color or self.theme.stroke
+
+    # ---- drawing ------------------------------------------------------------
+    def paint(self, buf: List[str], x: float, y: float, w: float, h: float,
+              color: Optional[str] = None) -> None:
+        """Draw the glyph fitted (contain, centred) into the rectangle (x, y, w, h)."""
+        vx, vy, vw, vh = self.spec["viewbox"]
+        s = min(w / vw, h / vh)
+        dx = x + (w - vw * s) / 2 - vx * s
+        dy = y + (h - vh * s) / 2 - vy * s
+        col = color or self._color()
+        mode = self.spec.get("mode", "stroke")
+        op = f' opacity="{self.opacity:.3f}"' if self.opacity < 0.999 else ""
+        if mode == "stroke":
+            sw = 2.0 if self.stroke_width is None else float(self.stroke_width)
+            attrs = (f'fill="none" stroke="{col}" stroke-width="{sw:g}" '
+                     f'stroke-linecap="round" stroke-linejoin="round"')
+        elif mode == "fill":
+            attrs = f'fill="{col}" stroke="none"'
+        else:
+            a = dict(self.spec.get("attrs", {}))
+            if self.stroke_width is not None:
+                a["stroke-width"] = f"{float(self.stroke_width):g}"
+            a = {k: (col if v == "currentColor" else v) for k, v in a.items()}
+            attrs = " ".join(f'{k}="{v}"' for k, v in a.items())
+        body = "".join(e.replace("currentColor", col) for e in self.spec["elements"])
+        buf.append(f'<g data-cf-icon="1" transform="translate({dx:.2f},{dy:.2f}) scale({s:.4f})" {attrs}{op}>'
+                   f"{body}</g>")
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_circle, draw_rect
+
+        g = self.geom
+        x, y, w, h = g.x + ox, g.y + oy, g.w, g.h
+        if self.bg:
+            if self.bg_shape == "circle":
+                draw_circle(buf, x + w / 2, y + h / 2, min(w, h) / 2, fill=self.bg)
+            else:
+                draw_rect(buf, x, y, w, h, fill=self.bg, stroke="none", stroke_width=0,
+                          radius=min(w, h) * 0.22 if self.bg_shape == "rounded" else 0)
+            p = self.bg_pad * self._size()
+            x, y, w, h = x + p, y + p, w - 2 * p, h - 2 * p
+        self.paint(buf, x, y, w, h)
+
+    def legend_key(self, label: str):
+        from .legend import Key
+
+        return Key(label, kind="icon", icon=self)
+
+
+def as_icon(v: Any, *, size: Optional[float] = None, color: Optional[str] = None,
+            theme: Any = None) -> Optional[Icon]:
+    """``"gpu"`` / Icon / None → Icon (used by Box(icon=…), badges, legends)."""
+    if v is None or v is False:
+        return None
+    if isinstance(v, Icon):
+        return v
+    if isinstance(v, str):
+        return Icon(v, size=size, color=color, theme=theme)
+    raise TypeError(f"icon must be a name or Icon, got {type(v).__name__}")
+
+
+# ---------------------------------------------------------------------------- Image
+_MIME = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".gif": "image/gif",
+         ".webp": "image/webp", ".svg": "image/svg+xml"}
+
+
+def _svg_size(data: bytes) -> Tuple[float, float]:
+    root = ET.fromstring(data.decode("utf-8"))
+    vb = root.get("viewBox")
+    if vb:
+        p = [float(v) for v in re.split(r"[\s,]+", vb.strip())]
+        return p[2], p[3]
+
+    def num(s: Optional[str]) -> float:
+        m = re.match(r"[\d.]+", s or "")
+        return float(m.group(0)) if m else 100.0
+    return num(root.get("width")), num(root.get("height"))
+
+
+class Image(Node):
+    """Embedded raster / SVG picture (base64 in the SVG output).
+
+    Give ``width=`` or ``height=`` (the other follows the aspect ratio) or both with
+    ``fit="contain"`` (letterbox inside the box) / ``"cover"`` (fill and crop).
+    ``radius=`` rounds the corners, ``border=True`` / a colour draws a frame.
+    """
+
+    def __init__(self, path: Union[str, Path], *, width: Optional[float] = None,
+                 height: Optional[float] = None, fit: str = "contain", radius: float = 0.0,
+                 border: Any = None, border_color: Optional[str] = None,
+                 border_width: Optional[float] = None, opacity: float = 1.0, **kwargs: Any) -> None:
+        if fit not in ("contain", "cover", "stretch"):
+            raise ValueError("fit must be contain|cover|stretch")
+        frame = border
+        if isinstance(border, str) and border.startswith("#"):
+            border_color, frame = border, "solid"
+        elif border is True:
+            frame = "solid"
+        elif border is False:
+            frame = None
+        super().__init__(border=frame, **kwargs)
+        self.path = Path(path)
+        data = self.path.read_bytes()
+        ext = self.path.suffix.lower()
+        if ext not in _MIME:
+            raise ValueError(f"unsupported image type {ext!r}; use PNG / JPG / GIF / WEBP / SVG")
+        self.mime = _MIME[ext]
+        if ext == ".svg":
+            self.px_w, self.px_h = _svg_size(data)
+        else:
+            from PIL import Image as _PIL
+
+            with _PIL.open(self.path) as im:
+                self.px_w, self.px_h = float(im.width), float(im.height)
+        self._b64 = base64.b64encode(data).decode("ascii")
+        self.width = width
+        self.height = height
+        self.fit = fit
+        self.radius = float(radius)
+        self.border_color = border_color
+        self._border_width = None if border_width is None else float(border_width)
+        self.opacity = float(opacity)
+
+    @property
+    def ratio(self) -> float:
+        return self.px_w / self.px_h if self.px_h else 1.0
+
+    def _measure(self) -> Tuple[float, float]:
+        if self.width is not None and self.height is not None:
+            return float(self.width), float(self.height)
+        if self.width is not None:
+            return float(self.width), float(self.width) / self.ratio
+        if self.height is not None:
+            return float(self.height) * self.ratio, float(self.height)
+        w = min(self.px_w, 160.0)
+        return w, w / self.ratio
+
+    _seq = 0
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_rect
+
+        g = self.geom
+        x, y, w, h = g.x + ox, g.y + oy, g.w, g.h
+        par = {"contain": "xMidYMid meet", "cover": "xMidYMid slice", "stretch": "none"}[self.fit]
+        Image._seq += 1
+        clip = ""
+        if self.radius > 0 or self.fit == "cover":
+            cid = f"cf-img-{Image._seq}"
+            buf.append(f'<defs><clipPath id="{cid}"><rect x="{x:.2f}" y="{y:.2f}" width="{w:.2f}" '
+                       f'height="{h:.2f}" rx="{self.radius:.2f}" ry="{self.radius:.2f}"/></clipPath></defs>')
+            clip = f' clip-path="url(#{cid})"'
+        op = f' opacity="{self.opacity:.3f}"' if self.opacity < 0.999 else ""
+        buf.append(f'<image x="{x:.2f}" y="{y:.2f}" width="{w:.2f}" height="{h:.2f}" '
+                   f'preserveAspectRatio="{par}"{clip}{op} '
+                   f'xlink:href="data:{self.mime};base64,{self._b64}" />')
+        if self.border not in (None, "none"):
+            if self.fit == "contain":  # frame the drawn picture, not the letterbox
+                s = min(w / self.px_w, h / self.px_h)
+                iw, ih = self.px_w * s, self.px_h * s
+                x, y, w, h = x + (w - iw) / 2, y + (h - ih) / 2, iw, ih
+            draw_rect(buf, x, y, w, h, fill="none", stroke=self.border_color or self.theme.stroke,
+                      stroke_width=self.border_width, radius=self.radius,
+                      dasharray=self._dash(self.border_width))
+
+
+def _image_border_width(self) -> float:
+    """Frame width: explicit ``border_width=`` or the theme's default stroke (1.0 classic)."""
+    if self._border_width is not None:
+        return self._border_width
+    return self.theme.SW(1.0)
+
+
+def _set_image_border_width(self, v) -> None:
+    self._border_width = None if v is None else float(v)
+
+
+Image.border_width = property(_image_border_width, _set_image_border_width)
+
+__all__ = ["Icon", "Image", "as_icon"]

codefig/icons/LICENSE-tabler-icons.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Paweł Kuna
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

codefig/icons/__init__.py

@@ -0,0 +1,101 @@
+"""Bundled icon set: a curated subset of Tabler Icons (MIT, https://tabler.io/icons).
+
+    from codefig import icons, Icon
+    icons.list()            # sorted names
+    icons.search("cloud")   # names containing a substring
+    Icon("gpu", size=18, color="#2e6fd0")
+    Box("Encoder", icon="snowflake")
+
+Icons are 24×24 stroke drawings stored as inline SVG elements, so they recolour with
+``color=`` and stay vector in SVG / PDF output. ``filled=True`` uses Tabler's filled
+variant where one exists (``icons.list(filled=True)``). The Tabler licence text ships
+next to the data as ``LICENSE-tabler-icons.txt`` (see README "Credits").
+Register your own drawings with :func:`register` or load a file with ``Icon.from_svg``.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Dict, List, Optional, Sequence
+
+_DIR = Path(__file__).resolve().parent
+_DATA: Optional[dict] = None
+_EXTRA: Dict[str, dict] = {}
+
+# common synonyms → bundled names
+ALIASES = {
+    "frozen": "snowflake", "trainable": "flame", "fire": "flame", "llm": "brain",
+    "model": "brain", "agent": "robot", "bot": "robot", "chat": "message", "doc": "file-text",
+    "document": "file-text", "storage": "database", "db": "database", "people": "users",
+    "person": "user", "gear": "settings", "lightning": "bolt", "image": "photo",
+    "picture": "photo", "web": "world", "internet": "world", "cache": "stack-2",
+    "memory": "device-sd-card", "disk": "device-floppy", "tick": "check", "cross": "x",
+    "close": "x", "idea": "bulb", "magic": "wand", "time": "clock", "tree": "binary-tree",
+}
+
+
+def _data() -> dict:
+    global _DATA
+    if _DATA is None:
+        _DATA = json.loads((_DIR / "tabler.json").read_text(encoding="utf-8"))
+    return _DATA
+
+
+def list(*, filled: bool = False) -> List[str]:  # noqa: A001 - public API name
+    """Sorted names of the bundled (and registered) icons."""
+    d = _data()
+    names = set(d["filled" if filled else "outline"])
+    names |= {n for n, e in _EXTRA.items() if (not filled or e.get("mode") == "fill")}
+    return sorted(names)
+
+
+def search(text: str) -> List[str]:
+    """Bundled icon names containing ``text`` (aliases included)."""
+    t = text.lower()
+    hits = {n for n in list() if t in n}
+    hits |= {v for k, v in ALIASES.items() if t in k}
+    return sorted(hits)
+
+
+def resolve_name(name: str) -> str:
+    n = name.strip().lower().replace("_", "-").replace(" ", "-")
+    if n in _EXTRA or n in _data()["outline"]:
+        return n
+    if n in ALIASES:
+        return ALIASES[n]
+    raise KeyError(
+        f"unknown icon {name!r}; see codefig.icons.list() / icons.search(), "
+        f"or use Icon.from_svg(path) / icons.register()")
+
+
+def get(name: str, *, filled: bool = False) -> dict:
+    """Icon spec: ``{"elements": [...], "viewbox": (x, y, w, h), "mode": "stroke"|"fill"|"native"}``."""
+    n = resolve_name(name)
+    if n in _EXTRA:
+        return _EXTRA[n]
+    d = _data()
+    vb = float(d.get("viewbox", 24))
+    if filled:
+        if n not in d["filled"]:
+            raise KeyError(f"icon {n!r} has no filled variant; filled ones: icons.list(filled=True)")
+        return {"elements": d["filled"][n], "viewbox": (0.0, 0.0, vb, vb), "mode": "fill"}
+    return {"elements": d["outline"][n], "viewbox": (0.0, 0.0, vb, vb), "mode": "stroke"}
+
+
+def register(name: str, elements: Sequence[str], *, viewbox=(0, 0, 24, 24), mode: str = "stroke") -> None:
+    """Add a custom icon from raw SVG elements (``mode``: stroke | fill | native)."""
+    if mode not in ("stroke", "fill", "native"):
+        raise ValueError("mode must be stroke|fill|native")
+    _EXTRA[name.lower()] = {"elements": [str(e) for e in elements],
+                            "viewbox": tuple(float(v) for v in viewbox), "mode": mode}
+
+
+def info() -> dict:
+    d = _data()
+    return {"source": d["source"], "version": d["version"], "license": d["license"],
+            "count": len(d["outline"]), "filled": len(d["filled"]),
+            "license_file": str(_DIR / "LICENSE-tabler-icons.txt")}
+
+
+__all__ = ["ALIASES", "get", "info", "list", "register", "resolve_name", "search"]