pugflow 2026.1__py3-none-any.whl

pugflow/__init__.py

@@ -0,0 +1,7 @@
+"""Pugflow diagram editor and renderer."""
+
+__version__ = "2026.1"
+
+from .server import DiagramServer, create_server, serve
+
+__all__ = ["DiagramServer", "create_server", "serve", "__version__"]

pugflow/__main__.py

@@ -0,0 +1,5 @@
+from pugflow.cli import main
+
+
+if __name__ == "__main__":
+    main()

pugflow/cli.py

@@ -0,0 +1,59 @@
+"""Command-line interface for Pugflow."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from . import __version__
+from .server import serve
+from .render import render_png
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="pugflow",
+        description="Open the editor or render a Pug diagram to PNG.",
+    )
+    parser.add_argument("input", nargs="?", type=Path, help="Pug source to render. Omit to open the editor.")
+    parser.add_argument("-o", "--output", type=Path, help="PNG output path (default: input filename with .png).")
+    parser.add_argument("--css", type=Path, help="External reusable-style CSS file.")
+    parser.add_argument("--scale", type=float, default=2, help="PNG scale multiplier (default: 2).")
+    parser.add_argument("--timeout", type=float, default=30, help="Headless rendering timeout in seconds (default: 30).")
+    parser.add_argument("--host", default="127.0.0.1", help="Interface to bind (default: 127.0.0.1).")
+    parser.add_argument("--port", default=4173, type=int, help="Port to bind; use 0 for an available port (default: 4173).")
+    parser.add_argument("--no-browser", action="store_true", help="Do not open the application in the default browser.")
+    parser.add_argument("--vim", action="store_true", help="Open the GUI with Vim editing mode enabled.")
+    parser.add_argument("--gui", action="store_true", help="Open the input Pug and optional CSS in the GUI instead of rendering.")
+    parser.add_argument("--demo", action="store_true", help="Open the GUI with the full feature-tour example.")
+    parser.add_argument("--quiet", action="store_true", help="Suppress HTTP request logging.")
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    return parser
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    if args.input and not args.gui:
+        if args.scale <= 0:
+            raise SystemExit("--scale must be greater than zero")
+        output = args.output or args.input.with_suffix(".png")
+        try:
+            render_png(args.input, output, css_path=args.css, scale=args.scale, timeout=args.timeout)
+        except (OSError, RuntimeError) as error:
+            raise SystemExit(f"error: {error}") from error
+        print(f"Wrote {output}")
+        return
+    if args.output:
+        raise SystemExit("--output requires rendering an input .pug file")
+    if args.css and not args.input:
+        raise SystemExit("--css requires an input .pug file")
+    css_path = args.css
+    if args.input and css_path is None:
+        candidate = args.input.with_suffix(".css")
+        css_path = candidate if candidate.is_file() else None
+    serve(args.host, args.port, open_browser=not args.no_browser, quiet=args.quiet, vim=args.vim,
+          demo=args.demo, pug_path=args.input, css_path=css_path)
+
+
+if __name__ == "__main__":
+    main()

pugflow/render.py

@@ -0,0 +1,71 @@
+"""Headless browser-backed PNG rendering."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+import threading
+from pathlib import Path
+
+from .server import create_server
+
+
+def find_browser() -> str:
+    configured = os.environ.get("PUGFLOW_BROWSER")
+    candidates = [configured] if configured else []
+    candidates += [shutil.which(name) for name in ("msedge", "chrome", "chromium", "chromium-browser")]
+    if os.name == "nt":
+        candidates += [
+            str(Path(os.environ.get("PROGRAMFILES(X86)", "C:/Program Files (x86)")) / "Microsoft/Edge/Application/msedge.exe"),
+            str(Path(os.environ.get("PROGRAMFILES", "C:/Program Files")) / "Google/Chrome/Application/chrome.exe"),
+        ]
+    for candidate in candidates:
+        if candidate and Path(candidate).is_file():
+            return candidate
+    raise RuntimeError("No Chromium browser found. Install Edge/Chrome/Chromium or set PUGFLOW_BROWSER.")
+
+
+def render_png(source_path: Path, output_path: Path, *, css_path: Path | None = None, scale: float = 2, timeout: float = 30) -> None:
+    source_path = source_path.resolve()
+    output_path = output_path.resolve()
+    css_path = css_path.resolve() if css_path else None
+    if not source_path.is_file():
+        raise FileNotFoundError(f"Diagram source not found: {source_path}")
+    if css_path and not css_path.is_file():
+        raise FileNotFoundError(f"Stylesheet not found: {css_path}")
+    server = create_server("127.0.0.1", 0, quiet=True)
+    server.render_source = source_path.read_text(encoding="utf-8")
+    server.render_styles = css_path.read_text(encoding="utf-8") if css_path else ""
+    server.render_result = None
+    server.render_error = None
+    server.render_event = threading.Event()
+    server.asset_root = source_path.parent
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    browser = None
+    profile = Path(tempfile.mkdtemp(prefix="pugflow-render-"))
+    try:
+        url = f"http://127.0.0.1:{server.server_address[1]}/render.html?scale={scale}"
+        browser = subprocess.Popen([find_browser(), "--headless=new", "--disable-gpu", "--no-first-run", "--disable-extensions", f"--user-data-dir={profile}", url], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+        if not server.render_event.wait(timeout):
+            raise RuntimeError(f"Rendering timed out after {timeout:g} seconds.")
+        if server.render_error:
+            raise RuntimeError(server.render_error)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+        output_path.write_bytes(server.render_result)
+    finally:
+        if browser and browser.poll() is None:
+            try:
+                browser.wait(timeout=3)
+            except subprocess.TimeoutExpired:
+                browser.terminate()
+                try:
+                    browser.wait(timeout=3)
+                except subprocess.TimeoutExpired:
+                    browser.kill()
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=2)
+        shutil.rmtree(profile, ignore_errors=True)

pugflow/server.py

@@ -0,0 +1,133 @@
+"""Dependency-free HTTP server for the Pugflow frontend."""
+
+from __future__ import annotations
+
+import json
+import threading
+import webbrowser
+from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from urllib.parse import quote, urlsplit
+
+from . import __version__
+
+
+STATIC_ROOT = Path(__file__).resolve().with_name("web")
+
+
+class DiagramRequestHandler(SimpleHTTPRequestHandler):
+    """Serve packaged assets and expose a small health endpoint."""
+
+    server_version = f"Pugflow/{__version__}"
+    extensions_map = {**SimpleHTTPRequestHandler.extensions_map, ".mjs": "text/javascript"}
+
+    def __init__(self, *args, directory=None, **kwargs):
+        super().__init__(*args, directory=str(directory or STATIC_ROOT), **kwargs)
+
+    def do_GET(self):  # noqa: N802 - required by BaseHTTPRequestHandler
+        path = urlsplit(self.path).path
+        if path == "/healthz":
+            payload = json.dumps({"status": "ok", "version": __version__}).encode("utf-8")
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json; charset=utf-8")
+            self.send_header("Content-Length", str(len(payload)))
+            self.send_header("Cache-Control", "no-store")
+            self.end_headers()
+            self.wfile.write(payload)
+            return
+        if path == "/__render_source.pug" and hasattr(self.server, "render_source"):
+            return self._send_text(self.server.render_source, "text/plain; charset=utf-8")
+        if path == "/__render_styles.css" and hasattr(self.server, "render_styles"):
+            return self._send_text(self.server.render_styles, "text/css; charset=utf-8")
+        if path == "/__project.pug" and hasattr(self.server, "project_pug"):
+            return self._send_text(self.server.project_pug, "text/plain; charset=utf-8")
+        if path == "/__project.css" and hasattr(self.server, "project_css"):
+            return self._send_text(self.server.project_css, "text/css; charset=utf-8")
+        if hasattr(self.server, "asset_root") and path not in {"/", "/render.html"}:
+            asset = (self.server.asset_root / path.lstrip("/")).resolve()
+            if asset.is_relative_to(self.server.asset_root.resolve()) and asset.is_file():
+                self.directory = str(self.server.asset_root)
+        super().do_GET()
+
+    def do_POST(self):  # noqa: N802 - required by BaseHTTPRequestHandler
+        path = urlsplit(self.path).path
+        if path not in {"/__render_output", "/__render_error"} or not hasattr(self.server, "render_event"):
+            self.send_error(404)
+            return
+        payload = self.rfile.read(int(self.headers.get("Content-Length", "0")))
+        if path == "/__render_output":
+            self.server.render_result = payload
+        else:
+            self.server.render_error = payload.decode("utf-8", errors="replace")
+        self.send_response(204)
+        self.end_headers()
+        self.server.render_event.set()
+
+    def _send_text(self, value, content_type):
+        payload = value.encode("utf-8")
+        self.send_response(200)
+        self.send_header("Content-Type", content_type)
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    def end_headers(self):
+        if urlsplit(self.path).path != "/healthz":
+            self.send_header("Cache-Control", "no-cache")
+        self.send_header("X-Content-Type-Options", "nosniff")
+        self.send_header("Referrer-Policy", "no-referrer")
+        super().end_headers()
+
+    def log_message(self, format, *args):
+        if not getattr(self.server, "quiet", False):
+            super().log_message(format, *args)
+
+
+class DiagramServer(ThreadingHTTPServer):
+    """Threaded development/desktop server with clean process shutdown."""
+
+    allow_reuse_address = True
+    daemon_threads = True
+
+
+def create_server(host="127.0.0.1", port=4173, *, quiet=False):
+    """Create a configured server without starting its blocking loop."""
+
+    if not STATIC_ROOT.joinpath("index.html").is_file():
+        raise RuntimeError(
+            f"Packaged web assets are missing from {STATIC_ROOT}."
+        )
+    server = DiagramServer((host, port), DiagramRequestHandler)
+    server.quiet = quiet
+    return server
+
+
+def serve(host="127.0.0.1", port=4173, *, open_browser=True, quiet=False, vim=False, demo=False, pug_path=None, css_path=None):
+    """Run the web application until interrupted and return the bound URL."""
+
+    server = create_server(host, port, quiet=quiet)
+    if pug_path:
+        server.project_pug = Path(pug_path).read_text(encoding="utf-8")
+        server.project_css = Path(css_path).read_text(encoding="utf-8") if css_path else ""
+    actual_port = server.server_address[1]
+    browser_host = "127.0.0.1" if host in {"0.0.0.0", "::"} else host
+    query = []
+    if vim: query.append("vim=1")
+    if demo: query.append("demo=1")
+    if pug_path:
+        query.extend(["project=1", f"name={quote(Path(pug_path).stem)}", f"pug_name={quote(Path(pug_path).name)}"])
+        if css_path: query.append(f"css_name={quote(Path(css_path).name)}")
+    url = f"http://{browser_host}:{actual_port}" + ("?" + "&".join(query) if query else "")
+    print(f"Pugflow {__version__}: {url}")
+    print("Press Ctrl+C to stop.")
+
+    if open_browser:
+        threading.Timer(0.25, webbrowser.open, args=(url,)).start()
+
+    try:
+        server.serve_forever()
+    except KeyboardInterrupt:
+        print("\nStopping Pugflow.")
+    finally:
+        server.server_close()
+    return url