predictygraph 0.1.0__py3-none-any.whl

predictygraph/parser.py

@@ -0,0 +1,310 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Line-oriented parser for the Predictygraph DSL (see docs/SPEC.md)."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+from .model import Document, Edge, Group, Node
+from .safe import MAX_EDGES, safe_path
+
+
+class PdgSyntaxError(ValueError):
+    def __init__(self, msg: str, line: int):
+        super().__init__(f"line {line}: {msg}")
+        self.line = line
+
+
+TOKEN_RE = re.compile(
+    r"""
+    (?P<ws>[ \t]+)
+  | (?P<string>"(?:[^"\\]|\\.)*")
+  | (?P<arrow><?[-=.]{1,64}>|<[-=.]{1,64}|[-=.]{2,64})
+  | (?P<attr>[A-Za-z_][\w-]*=(?:"(?:[^"\\]|\\.)*"|[^\s{}]+))
+  | (?P<cls>\.[A-Za-z_][\w-]*)
+  | (?P<ident>[A-Za-z_][\w-]*)
+  | (?P<punct>[{},;])
+    """,
+    re.VERBOSE,
+)
+
+BODIES = {"-": "solid", "=": "thick", ".": "dashed"}
+
+
+def unquote(s: str) -> str:
+    if s.startswith('"') and s.endswith('"'):
+        s = s[1:-1]
+        return re.sub(r"\\(.)", lambda m: "\n" if m.group(1) == "n" else m.group(1), s)
+    return s
+
+
+def strip_comment(line: str) -> str:
+    out, in_str, esc = [], False, False
+    for i, ch in enumerate(line):
+        if in_str:
+            out.append(ch)
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                in_str = False
+        elif ch == '"':
+            in_str = True
+            out.append(ch)
+        elif ch == "#" and (not out or out[-1] in " \t") and (i + 1 == len(line) or line[i + 1] in " \t#!"):
+            break
+        else:
+            out.append(ch)
+    return "".join(out)
+
+
+def tokenize(text: str, lineno: int) -> list[tuple[str, str]]:
+    pos, toks = 0, []
+    while pos < len(text):
+        m = TOKEN_RE.match(text, pos)
+        if not m:
+            raise PdgSyntaxError(f"unexpected {text[pos:pos + 12]!r}", lineno)
+        kind = m.lastgroup
+        if kind != "ws":
+            toks.append((kind, m.group()))
+        pos = m.end()
+    return toks
+
+
+def split_statements(toks):
+    """Split on ';' and after '{' / around '}' so blocks may share a line."""
+    cur = []
+    for t in toks:
+        if t == ("punct", ";"):
+            if cur:
+                yield cur
+            cur = []
+        elif t == ("punct", "{"):
+            cur.append(t)
+            yield cur
+            cur = []
+        elif t == ("punct", "}"):
+            if cur:
+                yield cur
+            yield [t]
+            cur = []
+        else:
+            cur.append(t)
+    if cur:
+        yield cur
+
+
+def parse_arrow(tok: str) -> tuple[str, str]:
+    start = tok.startswith("<")
+    end = tok.endswith(">")
+    body = tok.strip("<>")
+    arrow = {(False, False): "none", (False, True): "end", (True, False): "start", (True, True): "both"}[(start, end)]
+    return arrow, BODIES[body[0]]
+
+
+class Parser:
+    def __init__(self, base_dir: str = ".", allow_outside: bool = False):
+        self.root = Group(id="__root__", kind="graph")
+        self.doc = Document(root=self.root, base_dir=base_dir, allow_outside=allow_outside)
+        self.stack = [self.root]
+
+    @property
+    def scope(self) -> Group:
+        return self.stack[-1]
+
+    # -- helpers ---------------------------------------------------------
+    def _tail(self, toks, i, lineno):
+        label, classes, attrs = None, [], {}
+        for kind, val in toks[i:]:
+            if kind == "string" and label is None:
+                label = unquote(val)
+            elif kind == "cls":
+                classes.append(val[1:])
+            elif kind == "attr":
+                k, v = val.split("=", 1)
+                attrs[k] = unquote(v)
+            elif kind == "punct" and val == "{":
+                pass
+            else:
+                raise PdgSyntaxError(f"unexpected token {val!r}", lineno)
+        return label, classes, attrs
+
+    def _get_node(self, nid: str, lineno: int):
+        item = self.doc.items.get(nid)
+        if item is None:
+            item = Node(id=nid, implicit=True, parent=self.scope)
+            self.scope.children.append(item)
+            self.doc.items[nid] = item
+        return item
+
+    def _declare(self, item_id, lineno, cls=Node):
+        existing = self.doc.items.get(item_id)
+        if existing is not None:
+            if isinstance(existing, Node) and existing.implicit and cls is Node:
+                existing.parent.children.remove(existing)
+                existing.parent = self.scope
+                self.scope.children.append(existing)
+                existing.implicit = False
+                return existing
+            if cls is Node and isinstance(existing, Node):
+                return existing  # re-declaration merges attributes
+            raise PdgSyntaxError(f"duplicate id {item_id!r}", lineno)
+        item = cls(id=item_id, parent=self.scope)
+        self.scope.children.append(item)
+        self.doc.items[item_id] = item
+        return item
+
+    # -- statements ------------------------------------------------------
+    def statement(self, toks, lineno):
+        kinds = [k for k, _ in toks]
+        head = toks[0][1]
+        if toks == [("punct", "}")]:
+            if len(self.stack) == 1:
+                raise PdgSyntaxError("unbalanced '}'", lineno)
+            self.stack.pop()
+            return
+        if "arrow" in kinds:
+            return self.edge(toks, lineno)
+        if toks[0][0] != "ident":
+            raise PdgSyntaxError(f"statement cannot start with {head!r}", lineno)
+        if head == "graph" and (len(toks) == 1 or toks[1][0] != "string"):
+            if self.scope is not self.root:
+                raise PdgSyntaxError("'graph' only allowed at top level", lineno)
+            _, classes, attrs = self._tail(toks, 1, lineno)
+            self.root.classes += classes
+            self.root.attrs.update(attrs)
+            return
+        if head == "css" and len(toks) == 2 and toks[1][0] == "string":
+            path = safe_path(self.doc.base_dir, unquote(toks[1][1]), self.doc.allow_outside)
+            self.doc.stylesheets.append((path.read_text(encoding="utf-8"), str(path.parent)))
+            return
+        if head == "default" and len(toks) >= 2 and toks[1][1] in ("node", "edge", "group"):
+            _, classes, attrs = self._tail(toks, 2, lineno)
+            d = self.scope.defaults.setdefault(toks[1][1], {})
+            d.update(attrs)
+            if classes:
+                d["__classes__"] = " ".join(classes)
+            return
+        if head == "group" and len(toks) >= 2 and toks[1][0] == "ident":
+            if toks[-1] != ("punct", "{"):
+                raise PdgSyntaxError("group needs '{'", lineno)
+            g = self._declare(toks[1][1], lineno, cls=Group)
+            g.label, g.classes, g.attrs = self._tail(toks[:-1], 2, lineno)
+            self._apply_defaults(g, "group")
+            self.stack.append(g)
+            return
+        # node declaration
+        n = self._declare(head, lineno)
+        label, classes, attrs = self._tail(toks, 1, lineno)
+        if label is not None:
+            n.label = label
+        n.classes += classes
+        n.attrs.update(attrs)
+        self._apply_defaults(n, "node")
+
+    def _apply_defaults(self, item, kind):
+        merged: dict[str, str] = {}
+        for g in reversed([self.scope] + self.scope.ancestors()):
+            merged.update(g.defaults.get(kind, {}))
+        extra = merged.pop("__classes__", "")
+        item.classes = extra.split() + [c for c in item.classes if c not in extra.split()]
+        item.attrs = {**merged, **item.attrs}
+
+    def edge(self, toks, lineno):
+        groups: list[list[str]] = [[]]
+        arrows: list[tuple[str, str]] = []
+        i = 0
+        while i < len(toks):
+            kind, val = toks[i]
+            if kind == "ident":
+                groups[-1].append(val)
+            elif kind == "punct" and val == ",":
+                pass
+            elif kind == "arrow":
+                if not groups[-1]:
+                    raise PdgSyntaxError("arrow without source", lineno)
+                arrows.append(parse_arrow(val))
+                groups.append([])
+            else:
+                break
+            i += 1
+        if not groups[-1]:
+            raise PdgSyntaxError("arrow without target", lineno)
+        label, classes, attrs = self._tail(toks, i, lineno)
+        defaults: dict[str, str] = {}
+        for g in reversed([self.scope] + self.scope.ancestors()):
+            defaults.update(g.defaults.get("edge", {}))
+        dcls = defaults.pop("__classes__", "").split()
+        for a in groups:
+            for nid in a:
+                self._get_node(nid, lineno)
+        count = sum(len(s) * len(d) for s, d in zip(groups, groups[1:]))
+        if len(self.doc.edges) + count > MAX_EDGES:
+            raise PdgSyntaxError(f"too many edges (limit {MAX_EDGES})", lineno)
+        for (srcs, dsts), (arrow, body) in zip(zip(groups, groups[1:]), arrows):
+            for s in srcs:
+                for d in dsts:
+                    e = Edge(src=s, dst=d, arrow=arrow, body=body, label=label,
+                             classes=dcls + list(classes), attrs={**defaults, **attrs},
+                             scope=self.scope, index=len(self.doc.edges))
+                    e.id = f"e{e.index}"
+                    self.doc.edges.append(e)
+
+    # -- driver ----------------------------------------------------------
+    def parse(self, text: str) -> Document:
+        lines = text.splitlines()
+        i = 0
+        while i < len(lines):
+            lineno = i + 1
+            raw = strip_comment(lines[i])
+            stripped = raw.strip()
+            m = re.match(r"^\s*css\s*\{(.*)$", lines[i])
+            if m:  # raw inline css block
+                buf, depth, rest = [], 1, m.group(1)
+                while True:
+                    for j, ch in enumerate(rest):
+                        if ch == "{":
+                            depth += 1
+                        elif ch == "}":
+                            depth -= 1
+                            if depth == 0:
+                                break
+                        buf.append(ch)
+                    if depth == 0:
+                        break
+                    buf.append("\n")
+                    i += 1
+                    if i >= len(lines):
+                        raise PdgSyntaxError("unterminated css block", lineno)
+                    rest = lines[i]
+                self.doc.stylesheets.append(("".join(buf), self.doc.base_dir))
+                tail = strip_comment(rest[j + 1:]).strip()
+                if tail:  # statements after the closing brace on the same line
+                    for stmt in split_statements(tokenize(tail, i + 1)):
+                        self.statement(stmt, i + 1)
+                i += 1
+                continue
+            if stripped:
+                for stmt in split_statements(tokenize(stripped, lineno)):
+                    self.statement(stmt, lineno)
+            i += 1
+        if len(self.stack) != 1:
+            raise PdgSyntaxError(f"unclosed group {self.stack[-1].id!r}", len(lines))
+        for e in self.doc.edges:
+            for nid in (e.src, e.dst):
+                if nid not in self.doc.items:
+                    raise PdgSyntaxError(f"unknown id {nid!r}", 0)
+        return self.doc
+
+
+def parse(text: str, base_dir: str = ".", allow_outside: bool = False) -> Document:
+    return Parser(base_dir, allow_outside).parse(text)
+
+
+def parse_file(path: str | Path, allow_outside: bool = False) -> Document:
+    p = Path(path)
+    return parse(p.read_text(encoding="utf-8"), str(p.parent), allow_outside)

predictygraph/render/__init__.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Output handlers. Each one consumes a Scene IR and knows nothing about the DSL.
+
+    svg   animated (SMIL) or frozen SVG
+    apng  animated PNG, frames sampled from the scene's animation tracks
+"""
+from __future__ import annotations
+
+from .apng import write_apng
+from .svg import write_svg
+
+WRITERS = {"svg": write_svg, "apng": write_apng}
+
+__all__ = ["WRITERS", "write_svg", "write_apng"]

predictygraph/render/apng.py

@@ -0,0 +1,43 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""APNG writer: Scene IR -> animated PNG (frames sampled from the animation tracks)."""
+from __future__ import annotations
+
+import io
+from pathlib import Path
+
+from ..anim import loop_length
+from ..ir import Scene
+from .svg import write_svg
+
+
+class ApngWriter:
+    def __init__(self, scene: Scene, fps: int = 20, scale: float = 2.0, seconds: float | None = None):
+        self.scene, self.fps, self.scale = scene, fps, scale
+        durs = scene.durations()
+        self.seconds = seconds or (loop_length(durs) if durs else 1.0)
+
+    def _raster(self, svg: str):
+        try:
+            import cairosvg
+        except ImportError as exc:  # pragma: no cover
+            raise RuntimeError("APNG 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 = max(1, round(self.seconds * self.fps))
+        return [self._raster(write_svg(self.scene, i / self.fps)) for i in range(n)]
+
+    def save(self, out: Path) -> Path:
+        frames = self.frames()
+        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)
+        return out
+
+
+def write_apng(scene: Scene, out: Path, fps: int = 20, scale: float = 2.0, seconds: float | None = None) -> Path:
+    return ApngWriter(scene, fps, scale, seconds).save(out)

predictygraph/render/svg.py

@@ -0,0 +1,121 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""SVG writer: Scene IR -> SVG text.
+
+t=None  animated SVG: static values are the first keyframe, SMIL <animate> drives tracks.
+t=float frozen frame at that time (used for --static/--at and APNG frames).
+"""
+from __future__ import annotations
+
+from xml.sax.saxutils import escape, quoteattr
+
+from ..ir import Elem, Scene
+
+SHADOW = ('<filter id="pdg-shadow" x="-20%" y="-20%" width="140%" height="150%">'
+          '<feDropShadow dx="0" dy="2" stdDeviation="2.5" flood-opacity="0.18"/></filter>')
+
+
+def num(v) -> str:
+    if isinstance(v, float):
+        s = f"{v:.2f}".rstrip("0").rstrip(".")
+        return s if s not in ("", "-0") else "0"
+    return str(v)
+
+
+def path_d(segs) -> str:
+    out = []
+    for s in segs:
+        out.append(s[0] + (" " + " ".join(num(float(x)) for x in s[1:]) if len(s) > 1 else ""))
+    return " ".join(out)
+
+
+class SvgWriter:
+    def __init__(self, scene: Scene, t: float | None = None):
+        self.scene, self.t = scene, t
+
+    # ------------------------------------------------------------ attrs
+    def paint_attrs(self, el: Elem) -> dict[str, str]:
+        a = {}
+        for k, v in el.paint.items():
+            if k == "filter":
+                a["filter"] = f"url(#pdg-{v})"
+            else:
+                a[k] = num(v)
+        for tr in el.tracks:
+            v = tr.values[0] if self.t is None else tr.at(self.t)
+            a[tr.attr] = num(float(v))
+        return a
+
+    def smil(self, el: Elem) -> str:
+        if self.t is not None:
+            return ""
+        return "".join(f'<animate attributeName="{tr.attr}" values="{";".join(num(float(v)) for v in tr.values)}" '
+                       f'dur="{num(float(tr.dur))}s" repeatCount="indefinite"/>' for tr in el.tracks)
+
+    @staticmethod
+    def attrs_str(a: dict) -> str:
+        return " ".join(f"{k}={quoteattr(str(v))}" for k, v in a.items())
+
+    # ------------------------------------------------------------ elements
+    def elem(self, el: Elem) -> str:
+        g = el.geom
+        base = {}
+        if el.id:
+            base["id"] = el.id
+        if el.cls:
+            base["class"] = el.cls
+        if el.kind == "group":
+            inner = "\n".join(self.elem(c) for c in el.children)
+            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")}
+            a.update(self.paint_attrs(el))
+            a.update(base)
+            return f"<text {self.attrs_str(a)}>{escape(g['text'])}</text>"
+        if el.kind == "rect":
+            a = {"x": g["x"], "y": g["y"], "width": g["w"], "height": g["h"]}
+            if g.get("rx"):
+                a["rx"] = g["rx"]
+        elif el.kind == "ellipse":
+            a = {"cx": g["cx"], "cy": g["cy"], "rx": g["rx"], "ry": g["ry"]}
+        elif el.kind == "circle":
+            a = {"cx": g["cx"], "cy": g["cy"], "r": g["r"]}
+        elif el.kind in ("polygon", "polyline"):
+            a = {"points": " ".join(f"{num(float(x))},{num(float(y))}" for x, y in g["points"])}
+        elif el.kind == "line":
+            a = {k: g[k] for k in ("x1", "y1", "x2", "y2")}
+        elif el.kind == "path":
+            a = {"d": path_d(g["segs"])}
+        elif el.kind == "image":
+            a = {"x": g["x"], "y": g["y"], "width": g["w"], "height": g["h"], "href": g["href"],
+                 "xlink:href": g["href"], "preserveAspectRatio": "xMidYMid meet"}
+        else:
+            return ""
+        a = {k: num(float(v)) if isinstance(v, (int, float)) else v for k, v in a.items()}
+        a.update(self.paint_attrs(el))
+        a.update(base)
+        kids = self.smil(el)
+        tag = "path" if el.kind == "path" else el.kind
+        return f"<{tag} {self.attrs_str(a)}>{kids}</{tag}>" if kids else f"<{tag} {self.attrs_str(a)}/>"
+
+    # ------------------------------------------------------------ document
+    def write(self) -> str:
+        s = self.scene
+        body = [self.elem(layer) for layer in s.layers]
+        defs = []
+        if "shadow" in s.effects():
+            defs.append(SHADOW)
+        head = [f'<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" '
+                f'width="{s.width:.0f}" height="{s.height:.0f}" viewBox="0 0 {num(s.width)} {num(s.height)}" '
+                f'class="predictygraph">']
+        if defs:
+            head.append("<defs>" + "".join(defs) + "</defs>")
+        if s.background:
+            head.append(f'<rect x="0" y="0" width="{num(s.width)}" height="{num(s.height)}" fill="{s.background}"/>')
+        return "\n".join(head + body + ["</svg>"]) + "\n"
+
+
+def write_svg(scene: Scene, t: float | None = None) -> str:
+    return SvgWriter(scene, t).write()