predictygraph 0.1.0__py3-none-any.whl

predictygraph/theme.py

@@ -0,0 +1,107 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""TOML colour themes -> CSS (variables + base rules). See docs/THEMES.md."""
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+
+BUNDLED = Path(__file__).parent / "themes"
+HUES = ("red", "orange", "yellow", "green", "cyan", "blue", "purple")
+ROLE_DEFAULTS = {
+    "accent": "blue", "danger": "red", "node-fill": "surface", "node-stroke": "border",
+    "node-text": "fg", "group-fill": "bg-alt", "group-stroke": "border", "group-text": "muted",
+    "edge": "muted", "edge-text": "fg",
+}
+REQUIRED = ("bg", "surface", "fg", "muted", "border") + HUES
+
+
+class ThemeError(ValueError):
+    pass
+
+
+def _mix(a: str, b: str, t: float) -> str:
+    ca = [int(a[i:i + 2], 16) for i in (1, 3, 5)]
+    cb = [int(b[i:i + 2], 16) for i in (1, 3, 5)]
+    return "#" + "".join(f"{round(x * t + y * (1 - t)):02x}" for x, y in zip(ca, cb))
+
+
+def find_theme(name: str, base_dir: str = ".") -> Path:
+    cand = Path(base_dir) / name
+    if name.endswith(".toml") and cand.exists():
+        return cand
+    dirs = [d for d in os.environ.get("PDG_THEME_PATH", "").split(os.pathsep) if d] + [str(BUNDLED)]
+    for d in dirs:
+        p = Path(d) / f"{name}.toml"
+        if p.exists():
+            return p
+    raise ThemeError(f"unknown theme {name!r} (available: {', '.join(list_themes())})")
+
+
+def list_themes() -> list[str]:
+    return sorted(p.stem for p in BUNDLED.glob("*.toml"))
+
+
+def load_theme(name: str, base_dir: str = ".", _seen=()) -> dict:
+    path = find_theme(name, base_dir)
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    if data.get("schema", 1) != 1:
+        raise ThemeError(f"{path}: unsupported schema {data['schema']}")
+    if "extends" in data:
+        if data["extends"] in _seen:
+            raise ThemeError(f"{path}: extends cycle")
+        parent = load_theme(data["extends"], str(path.parent), _seen + (name,))
+        for sect in ("palette", "roles", "shape"):
+            parent.setdefault(sect, {}).update(data.get(sect, {}))
+        parent["name"] = data.get("name", name)
+        parent["dark"] = data.get("dark", parent.get("dark", False))
+        data = parent
+    return data
+
+
+def theme_css(name: str, base_dir: str = ".") -> str:
+    t = load_theme(name, base_dir)
+    pal = dict(t.get("palette", {}))
+    missing = [k for k in REQUIRED if k not in pal]
+    if missing:
+        raise ThemeError(f"theme {name!r} palette missing: {', '.join(missing)}")
+    for k, v in pal.items():
+        if not (isinstance(v, str) and v.startswith("#") and len(v) == 7):
+            raise ThemeError(f"theme {name!r}: palette.{k} must be #rrggbb, got {v!r}")
+    pal.setdefault("bg-alt", _mix(pal["surface"], pal["bg"], 0.45))
+    for h in HUES:
+        pal.setdefault(f"{h}-soft", _mix(pal[h], pal["bg"], 0.22))
+    roles = {**ROLE_DEFAULTS, **t.get("roles", {})}
+    unknown = set(t.get("roles", {})) - set(ROLE_DEFAULTS)
+    if unknown:
+        raise ThemeError(f"theme {name!r}: unknown roles {sorted(unknown)}")
+    shape = t.get("shape", {})
+
+    def ref(v):
+        return f"var(--{v})" if v in pal else v
+
+    lines = [":root {"]
+    lines += [f"  --{k}: {v};" for k, v in pal.items()]
+    lines += [f"  --{k}: {ref(v)};" for k, v in roles.items()]
+    lines.append("}")
+    radius = shape.get("radius", 6)
+    lines.append("graph { background: var(--bg); color: var(--fg); }")
+    if "font" in shape:
+        lines.append(f'graph {{ font-family: "{shape["font"]}", sans-serif; }}')
+    lines.append(f"node {{ fill: var(--node-fill); stroke: var(--node-stroke); color: var(--node-text); "
+                 f"border-radius: {radius}px; }}")
+    lines.append("group { fill: var(--group-fill); stroke: var(--group-stroke); color: var(--group-text); }")
+    lines.append("edge { stroke: var(--edge); color: var(--edge-text); }")
+    # semantic helper classes usable on any node/group/edge: .red .green .accent ...
+    for h in HUES + ("accent", "danger"):
+        base = f"var(--{h})"
+        soft = f"var(--{h}-soft)" if h in HUES else f"var(--{roles[h]}-soft)" if roles[h] in HUES else "var(--surface)"
+        lines.append(f"node.{h}, group.{h} {{ fill: {soft}; stroke: {base}; }}")
+        lines.append(f"edge.{h} {{ stroke: {base}; color: {base}; }}")
+    lines.append("node.solid { fill: var(--fg); stroke: var(--fg); color: var(--bg); }")
+    if "edge-width" in shape:
+        lines.append(f"edge {{ stroke-width: {shape['edge-width']}; }}")
+    return "\n".join(lines) + "\n"

predictygraph/themes/catppuccin-frappe.toml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "catppuccin-frappe"
+dark = true
+
+[palette]
+bg = "#303446"
+surface = "#414559"
+fg = "#c6d0f5"
+muted = "#a5adce"
+border = "#626880"
+red = "#e78284"
+orange = "#ef9f76"
+yellow = "#e5c890"
+green = "#a6d189"
+cyan = "#81c8be"
+blue = "#8caaee"
+purple = "#ca9ee6"
+
+[roles]
+accent = "purple"
+
+[shape]
+radius = 10

predictygraph/themes/catppuccin-latte.toml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "catppuccin-latte"
+dark = false
+
+[palette]
+bg = "#eff1f5"
+surface = "#e6e9ef"
+fg = "#4c4f69"
+muted = "#6c6f85"
+border = "#9ca0b0"
+red = "#d20f39"
+orange = "#fe640b"
+yellow = "#df8e1d"
+green = "#40a02b"
+cyan = "#179299"
+blue = "#1e66f5"
+purple = "#8839ef"
+
+[roles]
+accent = "purple"
+
+[shape]
+radius = 10

predictygraph/themes/catppuccin-macchiato.toml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "catppuccin-macchiato"
+dark = true
+
+[palette]
+bg = "#24273a"
+surface = "#363a4f"
+fg = "#cad3f5"
+muted = "#a5adcb"
+border = "#5b6078"
+red = "#ed8796"
+orange = "#f5a97f"
+yellow = "#eed49f"
+green = "#a6da95"
+cyan = "#8bd5ca"
+blue = "#8aadf4"
+purple = "#c6a0f6"
+
+[roles]
+accent = "purple"
+
+[shape]
+radius = 10

predictygraph/themes/catppuccin-mocha.toml

@@ -0,0 +1,27 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "catppuccin-mocha"
+dark = true
+
+[palette]
+bg = "#1e1e2e"
+surface = "#313244"
+fg = "#cdd6f4"
+muted = "#a6adc8"
+border = "#585b70"
+red = "#f38ba8"
+orange = "#fab387"
+yellow = "#f9e2af"
+green = "#a6e3a1"
+cyan = "#94e2d5"
+blue = "#89b4fa"
+purple = "#cba6f7"
+
+[roles]
+accent = "purple"
+
+[shape]
+radius = 10

predictygraph/themes/default.toml

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "default"
+dark = false
+
+[palette]
+bg = "#ffffff"
+surface = "#ffffff"
+fg = "#111827"
+muted = "#4b5563"
+border = "#374151"
+bg-alt = "#f3f4f6"
+red = "#dc2626"
+orange = "#ea580c"
+yellow = "#ca8a04"
+green = "#16a34a"
+cyan = "#0891b2"
+blue = "#2563eb"
+purple = "#7c3aed"

predictygraph/themes/dracula.toml

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "dracula"
+dark = true
+
+[palette]
+bg = "#282a36"
+surface = "#44475a"
+fg = "#f8f8f2"
+muted = "#bfc3d9"
+border = "#bd93f9"
+red = "#ff5555"
+orange = "#ffb86c"
+yellow = "#f1fa8c"
+green = "#50fa7b"
+cyan = "#8be9fd"
+blue = "#6272a4"
+purple = "#bd93f9"
+
+[roles]
+accent = "purple"
+edge = "purple"

predictygraph/themes/github-light.toml

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "github-light"
+dark = false
+
+[palette]
+bg = "#ffffff"
+surface = "#f6f8fa"
+fg = "#1f2328"
+muted = "#656d76"
+border = "#d0d7de"
+red = "#cf222e"
+orange = "#bc4c00"
+yellow = "#9a6700"
+green = "#1a7f37"
+cyan = "#1b7c83"
+blue = "#0969da"
+purple = "#8250df"
+
+[roles]
+node-stroke = "muted"
+group-fill = "bg"

predictygraph/themes/gruvbox-dark.toml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "gruvbox-dark"
+dark = true
+
+[palette]
+bg = "#282828"
+surface = "#3c3836"
+fg = "#ebdbb2"
+muted = "#a89984"
+border = "#665c54"
+red = "#fb4934"
+orange = "#fe8019"
+yellow = "#fabd2f"
+green = "#b8bb26"
+cyan = "#8ec07c"
+blue = "#83a598"
+purple = "#d3869b"
+
+[roles]
+accent = "yellow"

predictygraph/themes/nord.toml

@@ -0,0 +1,25 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "nord"
+dark = true
+
+[palette]
+bg = "#2e3440"
+surface = "#3b4252"
+fg = "#eceff4"
+muted = "#d8dee9"
+border = "#81a1c1"
+red = "#bf616a"
+orange = "#d08770"
+yellow = "#ebcb8b"
+green = "#a3be8c"
+cyan = "#88c0d0"
+blue = "#81a1c1"
+purple = "#b48ead"
+
+[roles]
+accent = "cyan"
+edge = "cyan"

predictygraph/themes/solarized-dark.toml

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "solarized-dark"
+extends = "solarized-light"
+dark = true
+
+[palette]
+bg = "#002b36"
+surface = "#073642"
+fg = "#eee8d5"
+muted = "#93a1a1"
+border = "#586e75"

predictygraph/themes/solarized-light.toml

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2026 The predictygraph Authors
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+schema = 1
+name = "solarized-light"
+dark = false
+
+[palette]
+bg = "#fdf6e3"
+surface = "#eee8d5"
+fg = "#073642"
+muted = "#657b83"
+border = "#93a1a1"
+red = "#dc322f"
+orange = "#cb4b16"
+yellow = "#b58900"
+green = "#859900"
+cyan = "#2aa198"
+blue = "#268bd2"
+purple = "#6c71c4"
+
+[roles]
+group-fill = "bg"

predictygraph-0.1.0.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.1
+Name: predictygraph
+Version: 0.1.0
+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
+Requires-Python: >=3.11
+Requires-Dist: tinycss2>=1.5.1
+Requires-Dist: typer>=0.26.8
+Requires-Dist: pillow>=11.0.0
+Provides-Extra: apng
+Requires-Dist: cairosvg>=2.7; extra == "apng"
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2026 The predictygraph Authors
+
+SPDX-License-Identifier: GPL-3.0-or-later
+-->
+
+# predictygraph
+
+**Predictable graphs.** A readable diagram DSL with per-group layouts ("balancing styles"),
+plain-CSS styling, and static or animated SVG/APNG output (no browser).
+Spec: [docs/SPEC.md](docs/SPEC.md). Docs: [predictygraph.github.io](https://predictygraph.github.io/).
+Editor support: [tree-sitter-pdg](https://github.com/predictygraph/tree-sitter-pdg).
+Rendered examples and the gallery: [predictygraph.github.io](https://predictygraph.github.io/). This repo keeps
+only `.pdg` sources; images live in the docs repo (git-lfs).
+
+```bash
+uv run pdg examples/hami_flow.pdg                    # -> examples/hami_flow.svg (not committed)
+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 --target web                  # size labels to fit any browser font
+```
+
+`pdg` is the short alias of the `predictygraph` command.
+
+## Credits
+
+This project stands on the shoulders of two giants.
+
+**[Graphviz](https://graphviz.org/) (dot)** taught a generation that diagrams can be
+text. Its layered layout algorithm is still the reference for graph drawing, and
+we are grateful for decades of work on it. But dot optimises for the whole graph
+at once: you describe nodes and edges, and the engine decides where they go.
+Nudging one cluster without disturbing the rest means fighting `rank`, `weight`
+and invisible edges. Styling lives in attributes rather than CSS, and the output
+often looks like a paper figure rather than a slide.
+
+**[Mermaid](https://mermaid.js.org/)** made text diagrams mainstream by putting
+them in Markdown, READMEs and docs sites. Its syntax is friendly and we borrowed
+from its spirit. But it renders through a browser and JavaScript, leaves little
+control over layout, and the same source can render differently across versions
+and hosts.
+
+predictygraph keeps what we love from both (diagrams as readable text) and adds what we
+missed: per-group layouts, plain-CSS styling, and deterministic static SVG with no
+browser in the loop.

predictygraph-0.1.0.dist-info/RECORD

@@ -0,0 +1,44 @@
+predictygraph-0.1.0.dist-info/METADATA,sha256=CoDqApa_uMOvZDcWrJ3tIrcUtT80fgNGzhRengYnJTU,2689
+predictygraph-0.1.0.dist-info/WHEEL,sha256=IuIk3wbaEnFH1cx75iM2R1CmliRI3dFLXTbRakgvgFQ,90
+predictygraph-0.1.0.dist-info/entry_points.txt,sha256=yde4kgZ0WRlm5G5l-bjg2OgDIrtUCIYfkPbLgVoJq6g,100
+predictygraph/__init__.py,sha256=f7zBi_TUZDt4V-ELDQyHk31fzhi2OQEH4YvHuN-xZzY,4395
+predictygraph/__main__.py,sha256=0F2Unhc4kKA6uxBytbfvF03Fn2hNKDr9r6HyDi2s8Ig,132
+predictygraph/anim.py,sha256=gsjFrTwykcvZW9ICdWaYuu0HlOU4WWTRso0t2l2C6f4,3162
+predictygraph/cli.py,sha256=7l5U1IRedyCmwEWWM-5ZDIQA25BcuFZ_3HKwGAn69jA,3088
+predictygraph/default.css,sha256=vbBfmABACFHe3ZQVhJ7IJbpLpmv7aip2dFwytxWOs-Q,751
+predictygraph/fonts.py,sha256=3CdQFgjvzpyL6YdAhudB_tBBFq-mPBpYZOvZ8XqDd5o,7647
+predictygraph/fonts/Carlito-Bold.ttf,sha256=uyNP56DvE4vqsqoFk02kl7LkOUd1pWUs48iW2TAFwsQ,58012
+predictygraph/fonts/Carlito-Regular.ttf,sha256=MN2s88fyeXioDICb_MkWZp3ouIvMU9cJmgIwuncqKjU,46056
+predictygraph/fonts/DejaVuSans-Bold.ttf,sha256=8z1aujFUcQllZd4gESIK0AVFTuxTHOaCEE0RsrkTkeY,31864
+predictygraph/fonts/DejaVuSans.ttf,sha256=APTQyByjSZV9-sYuoCnXe276iFZmny3CcW90zrVBWKY,38268
+predictygraph/fonts/LiberationMono-Bold.ttf,sha256=y25HdnJTYHyPnxFOAnHprHigxxtqJAq2_9QbWC9emkA,10300
+predictygraph/fonts/LiberationMono-Regular.ttf,sha256=-lAx0L1_BJPW1Nl_AALhaD_kD4sf_5URKKRGuaDK3gY,9680
+predictygraph/fonts/LiberationSans-Bold.ttf,sha256=cDQz0tZxoafJM-oQBgZ4jYRQSb4Sphc8qPl0XHBsaMQ,19408
+predictygraph/fonts/LiberationSans-Regular.ttf,sha256=MDnbaCx53AHWIMqvPiBpy-TUL6PH6YvOcMa5NpKHKv8,19736
+predictygraph/fonts/LiberationSerif-Bold.ttf,sha256=WE7FT4YNjPETuGFlvyslCL6cYd-1rdh4UNQqzWnNfws,10740
+predictygraph/fonts/LiberationSerif-Regular.ttf,sha256=3BuekcztcwjkSZ20inLWZuBLp3xpDLRgkE7j5uUqH4Y,10060
+predictygraph/ir.py,sha256=xY4K-qa5F06JMpkROPO-8E2qmyKv9VpfF-fGXObWGJ4,2110
+predictygraph/layout.py,sha256=mue-hjQ5QeNb4o4vn3GuLfAXgAvPMdU06hjooljA56E,22106
+predictygraph/model.py,sha256=jz_GDCqu8C-KqjvYiu2bkH-f8NgUhOCmYuyNya1tD1s,2684
+predictygraph/parser.py,sha256=r26WZp0oTS1mm3o8-EAx8qII0GEpGtAL9MSvQs0i0TA,11586
+predictygraph/render/__init__.py,sha256=ALzR1UUJcUW1KvjzidRsmg7GQckUlXr3zbceNprzGBQ,496
+predictygraph/render/apng.py,sha256=JYeThbH7xjYW_zmZHl4HDcCqUxgp4xCGT3Iw6RkH8Eo,1639
+predictygraph/render/svg.py,sha256=nURaWmmgl-j7Lw_Eas0sSES4PSw3Es7Z_8N69J-nJt0,4877
+predictygraph/route.py,sha256=RsJL3B9-x8iYTTm06k_yUel1HtcTvslKXSVzmxgF4X8,20559
+predictygraph/safe.py,sha256=yogRtscoKxYDi6C7TX13HJ6CFXfFn7B_i7oFW-WREb8,1331
+predictygraph/scene.py,sha256=6-6j335ziIwYgwNVUNbYJlnYlKqbXhOekcf7r_dKvY8,18422
+predictygraph/style.py,sha256=2vecRNRYKum8cx0eZ89ldPDU6HAR-S9F4F-jtepz-7U,7731
+predictygraph/text.py,sha256=x3Tm7FbQXjhPuREofQkh-zG3Q_1Sd9oUkvOrbVC6AIQ,2723
+predictygraph/theme.py,sha256=sY1VR7wtsQbLi06eqPzOpF3g6Ril447aM9cu84Vfqes,4543
+predictygraph/themes/catppuccin-frappe.toml,sha256=1IfcQWEu6zHnKMViicqhPtpbNKpRvVsCM5j3DdMCKHI,425
+predictygraph/themes/catppuccin-latte.toml,sha256=4aWAdU7fvs0j0SzVG0s3I8xl63XLgo7CGTqq4ziFYA0,425
+predictygraph/themes/catppuccin-macchiato.toml,sha256=7PjwFAATdAhhj-x2O04Pjxnw-Q6olEwMMozQi1b5zcg,428
+predictygraph/themes/catppuccin-mocha.toml,sha256=VwGfiF2aKXe9TbqJUASEslLW3Wqf-_e6wOvsZ4-oKfI,424
+predictygraph/themes/default.toml,sha256=0SJw8oGTJVw9N_Hj5w40vvBHz6-g9fF-TbkFWA_f_ss,387
+predictygraph/themes/dracula.toml,sha256=WR9EkNw4LGSBlIk1s47JylRUhFyHPiI_h3rPbxUqYmQ,410
+predictygraph/themes/github-light.toml,sha256=qlG2LPuuYPfkpbV9wEHmAV2Iinlhii8NRJ-IP8hXMrk,422
+predictygraph/themes/gruvbox-dark.toml,sha256=_qTu1OcT54kg4HWCPSm78W60Vo11WU21WrvjD1r3sFY,399
+predictygraph/themes/nord.toml,sha256=OiSYUlGUcdK3oniAY4AhBLgFTsIQS8VJ183Q1ChV124,403
+predictygraph/themes/solarized-dark.toml,sha256=0aYVb90TDBhUd8MWrI_3hqQ9-PcRNbokWFLjWVwZhM8,277
+predictygraph/themes/solarized-light.toml,sha256=8H6EBjALiUEGNll5zrH_5o0iT0PwbJ1amrAlfmEu088,403
+predictygraph-0.1.0.dist-info/RECORD,,

predictygraph-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: pdm-backend (2.5.0)
+Root-Is-Purelib: true
+Tag: py3-none-any

predictygraph-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,6 @@
+[console_scripts]
+pdg = predictygraph.cli:app
+predictygraph = predictygraph.cli:app
+
+[gui_scripts]
+