predictygraph 0.1.1__tar.gz → 0.2.2__tar.gz

{predictygraph-0.1.1 → predictygraph-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: predictygraph
-Version: 0.1.1
+Version: 0.2.2
 Summary: Predictable graphs: a readable, CSS-styled diagram DSL with per-group layouts, rendered to SVG/APNG
 Author-Email: Reza Jelveh <git@jelveh.me>
 License: GPL-3.0-or-later
@@ -32,6 +32,7 @@ uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg
 uv run pdg diagram.pdg --css theme.css -o out.svg
 uv run pdg diagram.pdg -o out.png                    # animated PNG (APNG)
 uv run pdg diagram.pdg --check                       # validate only
+uv run pdg diagram.pdg -o d.png --width 1000 --colors 64   # small PNG for chat
 uv run pdg diagram.pdg --target web                  # size labels to fit any browser font
 ```
 

{predictygraph-0.1.1 → predictygraph-0.2.2}/README.md

@@ -18,6 +18,7 @@ uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg
 uv run pdg diagram.pdg --css theme.css -o out.svg
 uv run pdg diagram.pdg -o out.png                    # animated PNG (APNG)
 uv run pdg diagram.pdg --check                       # validate only
+uv run pdg diagram.pdg -o d.png --width 1000 --colors 64   # small PNG for chat
 uv run pdg diagram.pdg --target web                  # size labels to fit any browser font
 ```
 

{predictygraph-0.1.1 → predictygraph-0.2.2}/pyproject.toml

@@ -12,7 +12,7 @@ dependencies = [
 ]
 requires-python = ">=3.11"
 readme = "README.md"
-version = "0.1.1"
+version = "0.2.2"
 
 [project.license]
 text = "GPL-3.0-or-later"

{predictygraph-0.1.1 → predictygraph-0.2.2}/src/predictygraph/cli.py

@@ -31,7 +31,9 @@ def main(
     at: float | None = typer.Option(None, "--at", help="SVG frozen at this time (seconds)"),
     fps: int = typer.Option(20, "--fps", help="APNG frames per second"),
     seconds: float | None = typer.Option(None, "--seconds", help="APNG length (default: one full loop)"),
-    scale: float = typer.Option(2.0, "--scale", help="APNG pixel scale"),
+    scale: float = typer.Option(2.0, "--scale", help="PNG pixel scale"),
+    width: int | None = typer.Option(None, "--width", help="PNG width in pixels (overrides --scale)"),
+    colors: int | None = typer.Option(None, "--colors", help="PNG palette size, 2-256 (smaller files)"),
     allow_outside: bool = typer.Option(False, "--allow-outside",
                                        help="Let image= and css \"...\" read files outside the input's directory"),
 ) -> None:
@@ -52,7 +54,7 @@ def main(
             typer.echo(f"{src}: ok")
             return
         if dest.suffix.lower() in (".png", ".apng"):
-            write_apng(scene, dest, fps, scale, seconds)
+            write_apng(scene, dest, fps, scale, seconds, width, static, colors)
         else:
             t = at if at is not None else (0.0 if static else None)
             dest.write_text(write_svg(scene, t), encoding="utf-8")

{predictygraph-0.1.1 → predictygraph-0.2.2}/src/predictygraph/default.css

@@ -14,3 +14,11 @@ group { fill: #f3f4f6; stroke: #9ca3af; stroke-width: 1; border-radius: 10px;
         padding: 14px; color: #374151; font-size: 12px; font-weight: bold;
         label-position: top; }
 edge  { stroke: #4b5563; stroke-width: 1.5; color: #374151; font-size: 11px; }
+
+/* Text parts: `sub=` lines, step badges, figure caption, legend box. */
+sub     { color: #6b7280; font-size: 0.85em; }
+group sub { font-weight: normal; }
+step    { fill: #374151; color: #ffffff; font-size: 11px; font-weight: bold; }
+caption { color: #6b7280; font-size: 12px; font-style: italic; text-align: center; }
+legend  { fill: #ffffff; stroke: #d1d5db; color: #374151; font-size: 11px; }
+bracket { stroke: #9ca3af; stroke-width: 1.5; color: #4b5563; font-size: 11px; font-style: italic; }

{predictygraph-0.1.1 → predictygraph-0.2.2}/src/predictygraph/layout.py

@@ -10,17 +10,22 @@ from collections import defaultdict
 
 from .model import Document, Group, Item, Node
 from .style import box4, px
-from .text import load_image, measure
+from .styleutil import has_title_band, node_padding, text_block, title_position
+from .text import load_image
 
 
 # ---------------------------------------------------------------- sizing
+SUB_GAP = 3.0  # px between a label and its `sub=` lines
+
+
 def size_node(n: Node, doc: Document) -> None:
     st = n.style
-    fs = px(st.get("font-size"), 14)
-    bold = st.get("font-weight", "normal") in ("bold", "600", "700", "800", "900")
     label = n.label if n.label is not None else n.id
-    n.text_w, n.text_h, n.text_lines = measure(label, st.get("font-family", "sans-serif"), fs, bold) if label else (0.0, 0.0, [])
-    pt, pr, pb, pl = box4(st.get("padding"), 8)
+    n.text_w, n.text_h, n.text_lines = text_block(label, st, 14)
+    sw, sh, n.sub_lines = text_block(n.attrs.get("sub"), n.sub_style or st, 12)
+    n.sub_h = sh + SUB_GAP if n.sub_lines else 0.0
+    n.text_w, n.text_h = max(n.text_w, sw), n.text_h + n.sub_h  # text_h covers label + sub
+    pt, pr, pb, pl = node_padding(st)
     shape = n.attrs.get("shape")
     if "image" in n.attrs:
         img = load_image(n.attrs["image"], doc.base_dir, doc.allow_outside)
@@ -114,19 +119,50 @@ class LineLayout(Layout):
         gap = px(opt(self.g, "gap", "24"))
         align = opt(self.g, "align", "center")
         cross = max((k.h if horizontal else k.w) for k in self.kids)
-        pos = 0.0
-        for k in self.kids:
+        need = self.label_gaps(horizontal)
+        pos, last = 0.0, 0.0
+        for idx, k in enumerate(self.kids):
+            if align == "stretch":  # every child as wide (column) / tall (row) as the widest
+                if horizontal:
+                    k.h = cross
+                else:
+                    grow = cross - k.w
+                    k.w = cross
+                    if isinstance(k, Group) and opt(k, "justify", "start") == "center":
+                        k.ox += grow / 2  # content stays left unless the tier asks to centre it
             size_c = k.h if horizontal else k.w
             off = {"start": 0, "end": cross - size_c}.get(align, (cross - size_c) / 2)
+            step = max(gap, need.get(idx, 0.0))
             if horizontal:
                 k.x, k.y = pos, off
-                pos += k.w + gap
+                pos += k.w + step
             else:
                 k.x, k.y = off, pos
-                pos += k.h + gap
-        pos -= gap
+                pos += k.h + step
+            last = step
+        pos -= last
         return (pos, cross) if horizontal else (cross, pos)
 
+    def label_gaps(self, horizontal: bool) -> dict[int, float]:
+        """Gap needed after child i so labels of edges between neighbours i and i+1 fit
+        (a row only: a label runs along the gap). Room = label width + arrowhead + margin."""
+        if not horizontal:
+            return {}
+        index = {k.id: i for i, k in enumerate(self.kids)}
+        need: dict[int, float] = {}
+        for e in self.doc.edges:
+            if not e.label:
+                continue
+            a, b = direct_child(self.doc.items[e.src], self.g), direct_child(self.doc.items[e.dst], self.g)
+            if a is None or b is None or a is b:
+                continue
+            i, j = sorted((index[a.id], index[b.id]))
+            if j != i + 1:
+                continue
+            w, _, _ = text_block(e.label, e.label_style or e.style, 11, bold=False)
+            need[i] = max(need.get(i, 0.0), w + 34)
+        return need
+
 
 class GridLayout(Layout):
     def run(self):
@@ -485,18 +521,28 @@ def layout_group(g: Group, doc: Document) -> None:
     else:
         lay = LAYOUTS[g.attrs["layout"]](g, doc)
         cw, ch = lay.run()
-    g.label_h = 0.0
+    g.label_h = g.title_h = 0.0
+    g.side_w = 0.0  # label-position: left -> a column for the rotated title
     lw = 0.0
-    if g.label and g.kind == "group":
-        fs = px(g.style.get("font-size"), 12)
-        lw, g.label_h, _ = measure(g.label, g.style.get("font-family", "sans-serif"), fs,
-                                   g.style.get("font-weight", "normal") in ("bold", "700"))
-        g.label_h += 6
+    pos = title_position(g.style)
+    if g.label and g.kind == "group" and pos == "left":
+        tw, th, _ = text_block(g.label, g.style, 12)
+        g.title_h = th
+        g.side_w = th + 12
+        lw = 0.0
+        ch = max(ch, tw - pt - pb + 20)  # tall enough for the rotated title, with a margin
+    elif g.label and g.kind == "group":
+        lw, g.title_h, _ = text_block(g.label, g.style, 12)
+        sw, sh, _ = text_block(g.attrs.get("sub"), g.sub_style or g.style, 11)
+        lw = max(lw, sw)
+        g.label_h = g.title_h + (sh + SUB_GAP if sh else 0.0) + 6
+        if has_title_band(g.style):
+            g.label_h += 6
     inner_w = max(cw, lw) + getattr(g, "extra_w", 0.0)  # extra_w: room requested for the title
-    top = g.style.get("label-position", "top") != "bottom"
-    g.ox = pl + (inner_w - cw) / 2
+    top = pos not in ("bottom", "left")
+    g.ox = pl + g.side_w + (inner_w - cw) / 2
     g.oy = pt + (g.label_h if top else 0)
-    g.w = inner_w + pl + pr
+    g.w = inner_w + pl + pr + g.side_w
     g.h = ch + pt + pb + g.label_h
     g.layout_obj = lay
 

{predictygraph-0.1.1 → predictygraph-0.2.2}/src/predictygraph/model.py

@@ -16,6 +16,7 @@ class Item:
     attrs: dict[str, str] = field(default_factory=dict)
     parent: "Group | None" = None
     style: dict[str, str] = field(default_factory=dict)
+    sub_style: dict[str, str] = field(default_factory=dict)  # `sub=` text (CSS `sub` selector)
     # layout results (relative to parent content origin, then absolute)
     w: float = 0.0
     h: float = 0.0
@@ -48,6 +49,8 @@ class Node(Item):
     text_lines: list[str] = field(default_factory=list)
     text_w: float = 0.0
     text_h: float = 0.0
+    sub_lines: list[str] = field(default_factory=list)  # secondary text under the label
+    sub_h: float = 0.0
 
 
 @dataclass
@@ -59,6 +62,9 @@ class Group(Item):
     ox: float = 0.0
     oy: float = 0.0
     label_h: float = 0.0
+    title_h: float = 0.0  # label only; label_h also counts the subtitle
+    side_w: float = 0.0  # label-position: left -> width of the rotated-title column
+    part_styles: dict[str, dict[str, str]] = field(default_factory=dict)  # root: caption, legend
 
 
 @dataclass
@@ -73,6 +79,7 @@ class Edge:
     scope: Group | None = None
     style: dict[str, str] = field(default_factory=dict)
     label_style: dict[str, str] = field(default_factory=dict)
+    step_style: dict[str, str] = field(default_factory=dict)
     index: int = 0
     waypoints: list[tuple[float, float]] = field(default_factory=list)
     wp_owner: Group | None = None
@@ -81,6 +88,18 @@ class Edge:
     id: str = ""
 
 
+@dataclass
+class Bracket:
+    """`bracket a, b "note"`: a curly bracket beside the span of the listed items."""
+    ids: list[str]
+    label: str = ""
+    classes: list[str] = field(default_factory=list)
+    attrs: dict[str, str] = field(default_factory=dict)
+    style: dict[str, str] = field(default_factory=dict)
+    kind: str = "bracket"
+    id: str = ""
+
+
 @dataclass
 class Document:
     root: Group
@@ -89,6 +108,9 @@ class Document:
     items: dict[str, Item] = field(default_factory=dict)
     base_dir: str = "."
     allow_outside: bool = False  # let image=/css "..." read files outside base_dir
+    legend: list[Node] = field(default_factory=list)  # `legend .cls "text"` entries (not laid out)
+    legend_title: str | None = None
+    brackets: list["Bracket"] = field(default_factory=list)
 
     def walk(self, g: Group | None = None):
         g = g or self.root

{predictygraph-0.1.1 → predictygraph-0.2.2}/src/predictygraph/parser.py

@@ -8,9 +8,11 @@ from __future__ import annotations
 import re
 from pathlib import Path
 
-from .model import Document, Edge, Group, Node
+from .model import Bracket, Document, Edge, Group, Node
 from .safe import MAX_EDGES, safe_path
 
+MAX_ANNOTATIONS = 64  # legend entries / brackets per diagram
+
 
 class PdgSyntaxError(ValueError):
     def __init__(self, msg: str, line: int):
@@ -133,6 +135,13 @@ class Parser:
                 raise PdgSyntaxError(f"unexpected token {val!r}", lineno)
         return label, classes, attrs
 
+    def _annotation_room(self, stmt: str, existing: list, what: str, lineno: int) -> None:
+        """`legend` / `bracket`: top level only, at most MAX_ANNOTATIONS of each."""
+        if self.scope is not self.root:
+            raise PdgSyntaxError(f"'{stmt}' only allowed at top level", lineno)
+        if len(existing) >= MAX_ANNOTATIONS:
+            raise PdgSyntaxError(f"too many {what} (limit {MAX_ANNOTATIONS})", lineno)
+
     def _get_node(self, nid: str, lineno: int):
         item = self.doc.items.get(nid)
         if item is None:
@@ -189,6 +198,27 @@ class Parser:
             if classes:
                 d["__classes__"] = " ".join(classes)
             return
+        if head == "bracket" and len(toks) >= 2 and toks[1][0] == "ident":
+            self._annotation_room(head, self.doc.brackets, "brackets", lineno)
+            ids, i = [], 1
+            while i < len(toks) and toks[i][0] in ("ident", "punct") and toks[i][1] != "{":
+                if toks[i][0] == "ident":
+                    ids.append(toks[i][1])
+                i += 1
+            label, classes, attrs = self._tail(toks, i, lineno)
+            self.doc.brackets.append(Bracket(ids=ids, label=label or "", classes=list(classes), attrs=attrs))
+            return
+        if head == "legend" and (len(toks) == 1 or toks[1][0] in ("string", "cls")):
+            label, classes, attrs = self._tail(toks, 1, lineno)
+            if not classes:  # `legend "Key"` names the box
+                self._annotation_room(head, [], "", lineno)
+                self.doc.legend_title = label
+                return
+            self._annotation_room(head, self.doc.legend, "legend entries", lineno)
+            entry = Node(id=f"pdg-legend-{len(self.doc.legend)}", label=label or " ".join(classes),
+                         classes=list(classes), attrs=attrs, parent=self.root)
+            self.doc.legend.append(entry)
+            return
         if head == "group" and len(toks) >= 2 and toks[1][0] == "ident":
             if toks[-1] != ("punct", "{"):
                 raise PdgSyntaxError("group needs '{'", lineno)
@@ -298,6 +328,10 @@ class Parser:
             for nid in (e.src, e.dst):
                 if nid not in self.doc.items:
                     raise PdgSyntaxError(f"unknown id {nid!r}", 0)
+        for b in self.doc.brackets:
+            missing = [i for i in b.ids if i not in self.doc.items]
+            if missing or not b.ids:
+                raise PdgSyntaxError(f"bracket: unknown id {missing[0]!r}" if missing else "bracket needs ids", 0)
         return self.doc
 
 

predictygraph-0.2.2/src/predictygraph/render/apng.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""PNG / APNG writer: Scene IR -> PNG (one frame) or animated PNG (frames sampled from
+the animation tracks).
+
+Size controls: `scale` (pixel scale) or `width` (target pixel width, overrides scale);
+`still` forces one frame; `colors` quantises to a palette (much smaller files for flat
+diagram colours). A scene without animation is always written as a single frame.
+"""
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+from ..anim import loop_length
+from ..ir import Scene
+from .svg import write_svg
+
+MAX_PIXELS = 8000  # longest side; keeps a typo in --width/--scale from eating memory
+
+
+class ApngWriter:
+    def __init__(self, scene: Scene, fps: int = 20, scale: float = 2.0, seconds: float | None = None,
+                 width: int | None = None, still: bool = False, colors: int | None = None):
+        self.scene, self.fps = scene, fps
+        if width:
+            scale = width / max(scene.width, 1.0)
+        longest = max(scene.width, scene.height, 1.0)
+        self.scale = max(0.05, min(scale, MAX_PIXELS / longest))
+        durs = scene.durations()
+        self.still = still or not durs
+        self.seconds = seconds or (loop_length(durs) if durs else 1.0)
+        self.colors = max(2, min(int(colors), 256)) if colors else None
+
+    def _raster(self, svg: str):
+        try:
+            import cairosvg
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError("PNG export needs cairosvg: install predictygraph[apng]") from exc
+        from PIL import Image
+        png = cairosvg.svg2png(bytestring=svg.encode(), scale=self.scale)
+        return Image.open(io.BytesIO(png)).convert("RGBA")
+
+    def frames(self):
+        n = 1 if self.still else max(1, round(self.seconds * self.fps))
+        return [self._raster(write_svg(self.scene, i / self.fps)) for i in range(n)]
+
+    def _flatten(self, im):
+        """Opaque RGB (diagrams have a background) and, with `colors`, a palette image."""
+        from PIL import Image
+        bg = Image.new("RGBA", im.size, self.scene.background or "#ffffff")
+        rgb = Image.alpha_composite(bg, im).convert("RGB")
+        if self.colors:
+            return rgb.quantize(self.colors, method=Image.Quantize.MEDIANCUT, dither=Image.Dither.NONE)
+        return rgb
+
+    def save(self, out: Path) -> Path:
+        frames = [self._flatten(f) for f in self.frames()]
+        if len(frames) == 1:
+            frames[0].save(out, format="PNG", optimize=True)
+        else:
+            frames[0].save(out, format="PNG", save_all=True, append_images=frames[1:],
+                           duration=round(1000 / self.fps), loop=0, disposal=1, blend=0,
+                           default_image=False, optimize=True)
+        return out
+
+
+def write_apng(scene: Scene, out: Path, fps: int = 20, scale: float = 2.0, seconds: float | None = None,
+               width: int | None = None, still: bool = False, colors: int | None = None) -> Path:
+    return ApngWriter(scene, fps, scale, seconds, width, still, colors).save(out)

{predictygraph-0.1.1 → predictygraph-0.2.2}/src/predictygraph/render/svg.py

@@ -71,6 +71,8 @@ class SvgWriter:
             return f"<g {self.attrs_str(base)}>\n{inner}\n</g>" if base else f"<g>\n{inner}\n</g>"
         if el.kind == "text":
             a = {"x": num(float(g["x"])), "y": num(float(g["y"])), "text-anchor": g.get("anchor", "middle")}
+            if g.get("rotate"):  # about the text's own anchor point
+                a["transform"] = f"rotate({num(float(g['rotate']))} {a['x']} {a['y']})"
             a.update(self.paint_attrs(el))
             a.update(base)
             return f"<text {self.attrs_str(a)}>{escape(g['text'])}</text>"

{predictygraph-0.1.1 → predictygraph-0.2.2}/src/predictygraph/route.py

@@ -365,6 +365,19 @@ class Router:
         if da.id in ri and db.id in ri and abs(ri[da.id] - ri[db.id]) == 1:
             self.gapkey[e.id] = (owner.id, min(ri[da.id], ri[db.id]))
 
+    def span_items(self, a, b):
+        """Leaf nodes overlapping the band between a and b (both axes), plus a and b:
+        the things a same-side C-shaped edge must go around."""
+        x0, x1 = min(a.ax, b.ax), max(a.ax + a.w, b.ax + b.w)
+        y0, y1 = min(a.ay, b.ay), max(a.ay + a.h, b.ay + b.h)
+        out = [a, b]
+        for it in self.doc.walk():
+            if isinstance(it, Group) or it in (a, b):
+                continue
+            if it.ay < y1 and it.ay + it.h > y0 and it.ax < x1 and it.ax + it.w > x0:
+                out.append(it)
+        return out
+
     def geometry(self, e: Edge):
         """-> (points, axis). axis: v | h (flow axis), L (explicit L port) or free."""
         a, b = self.doc.items[e.src], self.doc.items[e.dst]
@@ -383,6 +396,17 @@ class Router:
             if v0 != v1:  # L-shape: one corner
                 corner = (p0[0], p1[1]) if v0 else (p1[0], p0[1])
                 return [p0, corner, p1], "L"
+            if ex == en and not wps:  # same side: C-shape around everything in between
+                gap = px(e.style.get("stub"), 24) if e.style.get("stub") else 24.0
+                if ex in ("left", "right"):
+                    lo = min(it.ax for it in self.span_items(a, b)) if ex == "left" else None
+                    hi = max(it.ax + it.w for it in self.span_items(a, b)) if ex == "right" else None
+                    x = lo - gap if ex == "left" else hi + gap
+                    return [p0, (x, p0[1]), (x, p1[1]), p1], "L"
+                lo = min(it.ay for it in self.span_items(a, b)) if ex == "top" else None
+                hi = max(it.ay + it.h for it in self.span_items(a, b)) if ex == "bottom" else None
+                y = lo - gap if ex == "top" else hi + gap
+                return [p0, (p0[0], y), (p1[0], y), p1], "L"
             return [p0] + wps + [p1], ("v" if v0 else "h")
         if d in ("TB", "BT", "LR", "RL") and route != "straight":
             vert = d in ("TB", "BT")