pvl-dotview 0.1.0__py3-none-any.whl

pvl_dotview/__main__.py

@@ -0,0 +1,15 @@
+"""Entry point: ``python -m pvl_dotview`` or ``pvl-dotview`` script."""
+
+from __future__ import annotations
+
+import sys
+
+from .app import PvlDotApp
+
+
+def main() -> None:
+    sys.exit(PvlDotApp().run())
+
+
+if __name__ == "__main__":
+    main()

pvl_dotview/app.py

@@ -0,0 +1,54 @@
+"""PvlDotApp — application singleton owning the QApplication and window registry."""
+
+from __future__ import annotations
+
+import contextlib
+import sys
+import traceback
+from types import TracebackType
+
+from PySide6.QtWidgets import QApplication, QMessageBox
+
+from .window import PvlDotWindow
+
+
+class PvlDotApp:
+    def __init__(self) -> None:
+        self._qapp = QApplication.instance() or QApplication(sys.argv)
+        self._windows: list[PvlDotWindow] = []
+        sys.excepthook = self._on_uncaught_exception
+        self.new_window()
+
+    def new_window(self) -> PvlDotWindow:
+        window = PvlDotWindow(self)
+        window.show()
+        self._windows.append(window)
+        return window
+
+    def remove_window(self, window: PvlDotWindow) -> None:
+        if window in self._windows:
+            self._windows.remove(window)
+
+    def run(self) -> int:
+        return self._qapp.exec()
+
+    def _on_uncaught_exception(
+        self,
+        exc_type: type[BaseException],
+        exc_value: BaseException,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        # Always print to stderr so the trace lands in the terminal too.
+        sys.__excepthook__(exc_type, exc_value, exc_tb)
+        # Don't pop a dialog for KeyboardInterrupt — let it propagate cleanly.
+        if issubclass(exc_type, KeyboardInterrupt):
+            return
+        tb = "".join(traceback.format_exception(exc_type, exc_value, exc_tb))
+        parent = self._windows[0] if self._windows else None
+        # If the dialog itself fails, we've already printed to stderr.
+        with contextlib.suppress(Exception):
+            QMessageBox.critical(
+                parent,
+                "Unexpected error",
+                f"{exc_type.__name__}: {exc_value}\n\n{tb}",
+            )

pvl_dotview/renderer.py

@@ -0,0 +1,35 @@
+"""Render a DOT source string to SVG bytes via the graphviz `dot` binary."""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+
+
+class GraphvizNotFoundError(RuntimeError):
+    """The `dot` binary is not on PATH."""
+
+
+class GraphvizRenderError(RuntimeError):
+    """`dot` exited non-zero (DOT syntax error or other failure)."""
+
+
+def render_dot_to_svg(dot_source: str) -> bytes:
+    """Invoke `dot -Tsvg` on the DOT source and return the SVG bytes."""
+    if not shutil.which("dot"):
+        raise GraphvizNotFoundError(
+            "Graphviz `dot` binary not found on PATH. "
+            "Install with `brew install graphviz` (macOS) or "
+            "`apt install graphviz` (Linux)."
+        )
+    try:
+        result = subprocess.run(
+            ["dot", "-Tsvg"],
+            input=dot_source.encode("utf-8"),
+            capture_output=True,
+            check=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        stderr = exc.stderr.decode("utf-8", errors="replace").strip()
+        raise GraphvizRenderError(stderr or f"dot exited {exc.returncode}") from exc
+    return result.stdout

pvl_dotview/window.py

@@ -0,0 +1,262 @@
+"""PvlDotWindow — viewer window backed by QWebEngineView for browser-grade rendering."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+from typing import TYPE_CHECKING, cast
+
+from PySide6.QtCore import QChildEvent, QEvent, QObject
+from PySide6.QtGui import (
+    QAction,
+    QCloseEvent,
+    QDragEnterEvent,
+    QDragMoveEvent,
+    QDropEvent,
+    QKeySequence,
+)
+from PySide6.QtWebEngineWidgets import QWebEngineView
+from PySide6.QtWidgets import QMainWindow, QMessageBox, QWidget
+
+from .renderer import GraphvizNotFoundError, GraphvizRenderError, render_dot_to_svg
+
+if TYPE_CHECKING:
+    from .app import PvlDotApp
+
+
+HTML_TEMPLATE = """<!DOCTYPE html>
+<html>
+<head>
+<meta charset="utf-8">
+<style>
+  html, body {
+    margin: 0; padding: 0; width: 100%; height: 100%;
+    overflow: hidden; background: #ffffff;
+    -webkit-user-select: none; user-select: none;
+  }
+  #viewport {
+    position: fixed; inset: 0; overflow: hidden;
+    cursor: grab;
+  }
+  #viewport.panning { cursor: grabbing; }
+  #content {
+    position: absolute; top: 0; left: 0;
+    transform-origin: 0 0;
+    will-change: transform;
+  }
+  #content svg { display: block; }
+  .placeholder {
+    display: flex; align-items: center; justify-content: center;
+    height: 100vh; padding: 0 24px;
+    font-family: -apple-system, BlinkMacSystemFont, "Helvetica Neue", sans-serif;
+    text-align: center; color: #888; font-size: 16px;
+  }
+</style>
+</head>
+<body>
+<div id="viewport"><div id="content">__CONTENT__</div></div>
+<script>
+(function(){
+  const viewport = document.getElementById('viewport');
+  const content = document.getElementById('content');
+
+  let scale = 1, tx = 0, ty = 0;
+  const ZOOM_BASE = 1.0015;
+  const ZOOM_MIN = 0.05;
+  const ZOOM_MAX = 50;
+
+  function applyTransform() {
+    content.style.transform = `translate(${tx}px, ${ty}px) scale(${scale})`;
+  }
+
+  function fitToViewport() {
+    const svg = content.querySelector('svg');
+    if (!svg) {
+      tx = 0; ty = 0; scale = 1;
+      applyTransform();
+      return;
+    }
+    let svgW = 0, svgH = 0;
+    if (svg.viewBox && svg.viewBox.baseVal && svg.viewBox.baseVal.width) {
+      svgW = svg.viewBox.baseVal.width;
+      svgH = svg.viewBox.baseVal.height;
+    } else if (svg.width && svg.width.baseVal) {
+      svgW = svg.width.baseVal.value;
+      svgH = svg.height.baseVal.value;
+    }
+    if (!svgW || !svgH) return;
+    svg.style.width = svgW + 'px';
+    svg.style.height = svgH + 'px';
+    const vw = viewport.clientWidth, vh = viewport.clientHeight;
+    scale = Math.min(vw / svgW, vh / svgH) * 0.95;
+    tx = (vw - svgW * scale) / 2;
+    ty = (vh - svgH * scale) / 2;
+    applyTransform();
+  }
+
+  viewport.addEventListener('wheel', (e) => {
+    e.preventDefault();
+    const delta = e.deltaY;
+    let factor = Math.pow(ZOOM_BASE, -delta);
+    let newScale = scale * factor;
+    if (newScale < ZOOM_MIN) { factor = ZOOM_MIN / scale; newScale = ZOOM_MIN; }
+    if (newScale > ZOOM_MAX) { factor = ZOOM_MAX / scale; newScale = ZOOM_MAX; }
+    const rect = viewport.getBoundingClientRect();
+    const cx = e.clientX - rect.left;
+    const cy = e.clientY - rect.top;
+    tx = cx - (cx - tx) * factor;
+    ty = cy - (cy - ty) * factor;
+    scale = newScale;
+    applyTransform();
+  }, { passive: false });
+
+  let panning = false, lastX = 0, lastY = 0;
+  viewport.addEventListener('mousedown', (e) => {
+    if (e.button !== 0) return;
+    panning = true;
+    lastX = e.clientX; lastY = e.clientY;
+    viewport.classList.add('panning');
+    e.preventDefault();
+  });
+  document.addEventListener('mousemove', (e) => {
+    if (!panning) return;
+    tx += e.clientX - lastX;
+    ty += e.clientY - lastY;
+    lastX = e.clientX; lastY = e.clientY;
+    applyTransform();
+  });
+  document.addEventListener('mouseup', () => {
+    if (!panning) return;
+    panning = false;
+    viewport.classList.remove('panning');
+  });
+
+  // Initial fit. setTimeout 0 lets the SVG layout settle first.
+  setTimeout(fitToViewport, 0);
+  window.addEventListener('load', fitToViewport);
+})();
+</script>
+</body>
+</html>
+"""
+
+
+PLACEHOLDER_BODY = '<div class="placeholder">Drop a .dot file here</div>'
+
+
+def _build_html(content: str) -> str:
+    return HTML_TEMPLATE.replace("__CONTENT__", content)
+
+
+def _strip_svg_prologue(svg_text: str) -> str:
+    """Drop <?xml?> / <!DOCTYPE> for clean HTML embedding."""
+    idx = svg_text.find("<svg")
+    return svg_text[idx:] if idx >= 0 else svg_text
+
+
+class _DropFilter(QObject):
+    """Intercept drag-drop events on the webview and any of its inner widgets.
+
+    QWebEngineView has internal Chromium widgets that consume drag-drop events;
+    a filter installed on the view and each of its children catches drops
+    regardless of which inner widget receives the OS event first.
+    """
+
+    def __init__(self, on_file_dropped: Callable[[str], None]) -> None:
+        super().__init__()
+        self._on_file_dropped = on_file_dropped
+
+    def eventFilter(self, obj: QObject, event: QEvent) -> bool:  # noqa: N802
+        t = event.type()
+        if t == QEvent.Type.DragEnter:
+            ev = cast(QDragEnterEvent, event)
+            if ev.mimeData().hasUrls():
+                ev.acceptProposedAction()
+                return True
+        elif t == QEvent.Type.DragMove:
+            mv = cast(QDragMoveEvent, event)
+            if mv.mimeData().hasUrls():
+                mv.acceptProposedAction()
+                return True
+        elif t == QEvent.Type.Drop:
+            drop = cast(QDropEvent, event)
+            for url in drop.mimeData().urls():
+                path = url.toLocalFile()
+                if path:
+                    self._on_file_dropped(path)
+                    drop.acceptProposedAction()
+                    return True
+        elif t == QEvent.Type.ChildAdded:
+            # A new internal widget was just attached — make sure it accepts
+            # drops and routes through this filter too.
+            child_ev = cast(QChildEvent, event)
+            child = child_ev.child()
+            if isinstance(child, QWidget):
+                child.setAcceptDrops(True)
+                child.installEventFilter(self)
+        return super().eventFilter(obj, event)
+
+
+class PvlDotWindow(QMainWindow):
+    def __init__(self, app: PvlDotApp) -> None:
+        super().__init__()
+        self._app = app
+        self.setWindowTitle("pvl-dotview")
+        self.resize(900, 700)
+
+        self._view = QWebEngineView(self)
+        self.setCentralWidget(self._view)
+
+        self._drop_filter = _DropFilter(on_file_dropped=self._load)
+        self.setAcceptDrops(True)
+        self.installEventFilter(self._drop_filter)
+        self._view.setAcceptDrops(True)
+        self._view.installEventFilter(self._drop_filter)
+        for child in self._view.findChildren(QWidget):
+            child.setAcceptDrops(True)
+            child.installEventFilter(self._drop_filter)
+
+        self._show_placeholder()
+        self._install_shortcuts()
+
+    def _install_shortcuts(self) -> None:
+        new_action = QAction("New Window", self)
+        new_action.setShortcut(QKeySequence.StandardKey.New)
+        new_action.triggered.connect(self._app.new_window)
+        self.addAction(new_action)
+
+    def _show_placeholder(self) -> None:
+        self._view.setHtml(_build_html(PLACEHOLDER_BODY))
+
+    def _load(self, path: str) -> None:
+        filename = os.path.basename(path)
+        try:
+            with open(path) as f:
+                dot_source = f.read()
+            svg_body = _strip_svg_prologue(render_dot_to_svg(dot_source).decode("utf-8"))
+        except GraphvizNotFoundError as exc:
+            QMessageBox.warning(self, "Graphviz not installed", str(exc))
+            return
+        except GraphvizRenderError as exc:
+            QMessageBox.warning(self, "Cannot render DOT file", f"{filename}\n\n{exc}")
+            return
+        except OSError as exc:
+            QMessageBox.warning(self, "Cannot read file", f"{filename}\n\n{exc}")
+            return
+        except Exception as exc:
+            # Catch-all so unexpected failures (UnicodeDecodeError, MemoryError,
+            # anything from the subprocess layer we didn't anticipate) show a
+            # dialog and the app keeps running instead of crashing.
+            QMessageBox.warning(
+                self,
+                "Unexpected error loading file",
+                f"{filename}\n\n{type(exc).__name__}: {exc}",
+            )
+            return
+
+        self._view.setHtml(_build_html(svg_body))
+        self.setWindowTitle(f"pvl-dotview — {filename}")
+
+    def closeEvent(self, event: QCloseEvent) -> None:  # noqa: N802
+        self._app.remove_window(self)
+        super().closeEvent(event)

pvl_dotview-0.1.0.dist-info/METADATA

@@ -0,0 +1,65 @@
+Metadata-Version: 2.4
+Name: pvl-dotview
+Version: 0.1.0
+Summary: Interactive Graphviz DOT file viewer with pan, zoom, and multi-window support.
+Project-URL: Homepage, https://github.com/ParkviewLab/pvl-dotview
+Project-URL: Source, https://github.com/ParkviewLab/pvl-dotview
+Project-URL: Issues, https://github.com/ParkviewLab/pvl-dotview/issues
+Author: GaryCoding, Claude Code
+License-Expression: MIT
+License-File: LICENSE
+Keywords: diagram,dot,graphviz,gui,viewer,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.11
+Requires-Dist: pyside6>=6.7
+Description-Content-Type: text/markdown
+
+# pvl-dotview
+
+Interactive Graphviz DOT file viewer. Drop a `.dot` file onto a blank window
+and the graph is rendered as crisp, pannable, zoomable vector graphics
+(via embedded Chromium / Qt WebEngine for browser-grade SVG fidelity). Open
+additional windows with **⌘N** (macOS) or **Ctrl+N** (Linux/Windows).
+
+## Install
+
+`pvl-dotview` shells out to the `dot` binary at runtime, so Graphviz must be
+installed system-wide before running.
+
+### As a tool (recommended for end users)
+
+```bash
+# macOS
+brew install graphviz
+uv tool install pvl-dotview
+
+# Debian/Ubuntu
+sudo apt install graphviz
+uv tool install pvl-dotview
+```
+
+Then run `pvl-dotview` from any terminal.
+
+### From a checkout (for development)
+
+```bash
+brew install graphviz   # or: apt install graphviz
+uv sync
+uv run pvl-dotview
+```
+
+## License
+
+This project is released under the [MIT License](LICENSE).
+
+Third-party components and their licenses are listed in [NOTICE](NOTICE):
+
+- **PySide6** (LGPL-3.0) — used as a dynamically-linked dependency
+- **Graphviz** (EPL-1.0, system dependency, invoked via the `dot` binary)

pvl_dotview-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+pvl_dotview/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pvl_dotview/__main__.py,sha256=P3V8lQkoqUWOe67qWuOIsW_LmK9p-Pd4MjEKdqewg7c,242
+pvl_dotview/app.py,sha256=qjLBdopila9dgdE-ZZTA4emjsFV3EspbZq6n0ke1slo,1776
+pvl_dotview/renderer.py,sha256=I53NmSjxwXC6X61gjfiei3l9fbFWt8Qi8MPHun8SBnY,1128
+pvl_dotview/window.py,sha256=gdMTaxn7TK3X27JQjEqbXgmItUEB9pP1w2LR43YfCI8,8678
+pvl_dotview-0.1.0.dist-info/METADATA,sha256=dtDEJi46hRJn5Fqr3InkzMbfktQuKHVw3PTwoT6qxn0,2056
+pvl_dotview-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pvl_dotview-0.1.0.dist-info/entry_points.txt,sha256=E7QkiLwb4OEaj1nz6i6uCnhoz0kuT-uWWFfkwjz5DEs,58
+pvl_dotview-0.1.0.dist-info/licenses/LICENSE,sha256=26WCesJP98Lzoif2-upgDz-cPTelFImt-mngg6CcF2w,1080
+pvl_dotview-0.1.0.dist-info/RECORD,,

pvl_dotview-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pvl_dotview-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pvl-dotview = pvl_dotview.__main__:main

pvl_dotview-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GaryCoding, Claude Code
+
+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.