anywidget-graph 0.1.0__py3-none-any.whl

anywidget_graph/__init__.py

@@ -0,0 +1,6 @@
+"""Interactive graph visualization for Python notebooks."""
+
+from anywidget_graph.widget import Graph
+
+__all__ = ["Graph"]
+__version__ = "0.1.0"

anywidget_graph/widget.py

@@ -0,0 +1,293 @@
+"""Main Graph widget using anywidget and Sigma.js."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import anywidget
+import traitlets
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+_ESM = """
+import Graph from "https://esm.sh/graphology@0.25.4";
+import Sigma from "https://esm.sh/sigma@3.0.0";
+
+function render({ model, el }) {
+  const container = document.createElement("div");
+  container.style.width = model.get("width") + "px";
+  container.style.height = model.get("height") + "px";
+  container.style.border = "1px solid #ddd";
+  container.style.borderRadius = "4px";
+  container.style.background = model.get("background") || "#fafafa";
+  el.appendChild(container);
+
+  const graph = new Graph();
+
+  const nodes = model.get("nodes") || [];
+  nodes.forEach((node) => {
+    graph.addNode(node.id, {
+      label: node.label || node.id,
+      x: node.x ?? Math.random() * 100,
+      y: node.y ?? Math.random() * 100,
+      size: node.size || 10,
+      color: node.color || "#6366f1",
+    });
+  });
+
+  const edges = model.get("edges") || [];
+  edges.forEach((edge, i) => {
+    graph.addEdge(edge.source, edge.target, {
+      label: edge.label || "",
+      size: edge.size || 2,
+      color: edge.color || "#94a3b8",
+    });
+  });
+
+  const renderer = new Sigma(graph, container, {
+    renderLabels: model.get("show_labels"),
+    renderEdgeLabels: model.get("show_edge_labels"),
+    defaultNodeColor: "#6366f1",
+    defaultEdgeColor: "#94a3b8",
+    labelColor: { color: "#333" },
+    labelSize: 12,
+    labelWeight: "500",
+  });
+
+  renderer.on("clickNode", ({ node }) => {
+    const nodeData = graph.getNodeAttributes(node);
+    model.set("selected_node", { id: node, ...nodeData });
+    model.save_changes();
+  });
+
+  renderer.on("clickEdge", ({ edge }) => {
+    const edgeData = graph.getEdgeAttributes(edge);
+    const [source, target] = graph.extremities(edge);
+    model.set("selected_edge", { source, target, ...edgeData });
+    model.save_changes();
+  });
+
+  renderer.on("clickStage", () => {
+    model.set("selected_node", null);
+    model.set("selected_edge", null);
+    model.save_changes();
+  });
+
+  model.on("change:nodes", () => {
+    graph.clear();
+    const newNodes = model.get("nodes") || [];
+    newNodes.forEach((node) => {
+      graph.addNode(node.id, {
+        label: node.label || node.id,
+        x: node.x ?? Math.random() * 100,
+        y: node.y ?? Math.random() * 100,
+        size: node.size || 10,
+        color: node.color || "#6366f1",
+      });
+    });
+    const newEdges = model.get("edges") || [];
+    newEdges.forEach((edge) => {
+      graph.addEdge(edge.source, edge.target, {
+        label: edge.label || "",
+        size: edge.size || 2,
+        color: edge.color || "#94a3b8",
+      });
+    });
+    renderer.refresh();
+  });
+
+  model.on("change:edges", () => {
+    graph.clearEdges();
+    const newEdges = model.get("edges") || [];
+    newEdges.forEach((edge) => {
+      graph.addEdge(edge.source, edge.target, {
+        label: edge.label || "",
+        size: edge.size || 2,
+        color: edge.color || "#94a3b8",
+      });
+    });
+    renderer.refresh();
+  });
+
+  return () => {
+    renderer.kill();
+  };
+}
+
+export default { render };
+"""
+
+_CSS = """
+.anywidget-graph {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+}
+"""
+
+
+class Graph(anywidget.AnyWidget):
+    """Interactive graph visualization widget using Sigma.js."""
+
+    _esm = _ESM
+    _css = _CSS
+
+    nodes = traitlets.List(trait=traitlets.Dict()).tag(sync=True)
+    edges = traitlets.List(trait=traitlets.Dict()).tag(sync=True)
+
+    width = traitlets.Int(default_value=800).tag(sync=True)
+    height = traitlets.Int(default_value=600).tag(sync=True)
+    background = traitlets.Unicode(default_value="#fafafa").tag(sync=True)
+    show_labels = traitlets.Bool(default_value=True).tag(sync=True)
+    show_edge_labels = traitlets.Bool(default_value=False).tag(sync=True)
+
+    selected_node = traitlets.Dict(allow_none=True, default_value=None).tag(sync=True)
+    selected_edge = traitlets.Dict(allow_none=True, default_value=None).tag(sync=True)
+
+    def __init__(
+        self,
+        nodes: list[dict[str, Any]] | None = None,
+        edges: list[dict[str, Any]] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(nodes=nodes or [], edges=edges or [], **kwargs)
+        self._node_click_callbacks: list[Callable] = []
+        self._edge_click_callbacks: list[Callable] = []
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any], **kwargs: Any) -> Graph:
+        """Create a Graph from a dictionary with nodes and edges keys."""
+        return cls(nodes=data.get("nodes", []), edges=data.get("edges", []), **kwargs)
+
+    @classmethod
+    def from_cypher(cls, result: Any, **kwargs: Any) -> Graph:
+        """Create a Graph from Cypher query results."""
+        nodes: dict[str, dict] = {}
+        edges: list[dict] = []
+
+        records = list(result) if hasattr(result, "__iter__") else [result]
+
+        for record in records:
+            if hasattr(record, "items"):
+                items = record.items() if callable(record.items) else record.items
+            elif hasattr(record, "data"):
+                items = record.data().items()
+            else:
+                items = record.items() if isinstance(record, dict) else []
+
+            for key, value in items:
+                if _is_node(value):
+                    node_id = _get_node_id(value)
+                    if node_id not in nodes:
+                        nodes[node_id] = _node_to_dict(value)
+                elif _is_relationship(value):
+                    edges.append(_relationship_to_dict(value))
+
+        return cls(nodes=list(nodes.values()), edges=edges, **kwargs)
+
+    def on_node_click(self, callback: Callable[[str, dict], None]) -> Callable:
+        """Register a callback for node click events."""
+        self._node_click_callbacks.append(callback)
+
+        def observer(change: dict) -> None:
+            if change["new"] is not None:
+                node_data = change["new"].copy()
+                node_id = node_data.pop("id", None)
+                for cb in self._node_click_callbacks:
+                    cb(node_id, node_data)
+
+        self.observe(observer, names=["selected_node"])
+        return callback
+
+    def on_edge_click(self, callback: Callable[[dict], None]) -> Callable:
+        """Register a callback for edge click events."""
+        self._edge_click_callbacks.append(callback)
+
+        def observer(change: dict) -> None:
+            if change["new"] is not None:
+                for cb in self._edge_click_callbacks:
+                    cb(change["new"])
+
+        self.observe(observer, names=["selected_edge"])
+        return callback
+
+
+def _is_node(obj: Any) -> bool:
+    if hasattr(obj, "labels") and hasattr(obj, "element_id"):
+        return True
+    if hasattr(obj, "labels") and hasattr(obj, "properties"):
+        return True
+    if isinstance(obj, dict) and "id" in obj:
+        return True
+    return False
+
+
+def _is_relationship(obj: Any) -> bool:
+    if hasattr(obj, "type") and hasattr(obj, "start_node"):
+        return True
+    if hasattr(obj, "type") and hasattr(obj, "source") and hasattr(obj, "target"):
+        return True
+    if isinstance(obj, dict) and "source" in obj and "target" in obj:
+        return True
+    return False
+
+
+def _get_node_id(node: Any) -> str:
+    if hasattr(node, "element_id"):
+        return str(node.element_id)
+    if hasattr(node, "id"):
+        return str(node.id)
+    if isinstance(node, dict):
+        return str(node.get("id", id(node)))
+    return str(id(node))
+
+
+def _node_to_dict(node: Any) -> dict:
+    result: dict[str, Any] = {"id": _get_node_id(node)}
+
+    if hasattr(node, "labels"):
+        labels = list(node.labels) if hasattr(node.labels, "__iter__") else [node.labels]
+        if labels:
+            result["label"] = labels[0]
+            result["labels"] = labels
+
+    if hasattr(node, "properties"):
+        props = node.properties if isinstance(node.properties, dict) else dict(node.properties)
+        result.update(props)
+    elif hasattr(node, "items"):
+        result.update(dict(node))
+    elif isinstance(node, dict):
+        result.update(node)
+
+    if "label" not in result and "name" in result:
+        result["label"] = result["name"]
+
+    return result
+
+
+def _relationship_to_dict(rel: Any) -> dict:
+    result: dict[str, Any] = {}
+
+    if hasattr(rel, "start_node") and hasattr(rel, "end_node"):
+        result["source"] = _get_node_id(rel.start_node)
+        result["target"] = _get_node_id(rel.end_node)
+    elif hasattr(rel, "source") and hasattr(rel, "target"):
+        result["source"] = _get_node_id(rel.source)
+        result["target"] = _get_node_id(rel.target)
+    elif isinstance(rel, dict):
+        result["source"] = str(rel.get("source", ""))
+        result["target"] = str(rel.get("target", ""))
+
+    if hasattr(rel, "type"):
+        result["label"] = str(rel.type)
+    elif isinstance(rel, dict) and "type" in rel:
+        result["label"] = str(rel["type"])
+    elif isinstance(rel, dict) and "label" in rel:
+        result["label"] = str(rel["label"])
+
+    if hasattr(rel, "properties"):
+        props = rel.properties if isinstance(rel.properties, dict) else dict(rel.properties)
+        result.update(props)
+    elif hasattr(rel, "items") and not isinstance(rel, dict):
+        result.update(dict(rel))
+
+    return result

anywidget_graph-0.1.0.dist-info/METADATA

@@ -0,0 +1,258 @@
+Metadata-Version: 2.4
+Name: anywidget-graph
+Version: 0.1.0
+Summary: Interactive graph visualization for Python notebooks using anywidget
+Project-URL: Homepage, https://grafeo.dev/
+Project-URL: Repository, https://github.com/GrafeoDB/anywidget-graph
+Author-email: "S.T. Grond" <widget@grafeo.dev>
+License: Apache-2.0
+Keywords: anywidget,cypher,graph,jupyter,marimo,neo4j,visualization
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Jupyter
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Requires-Dist: anywidget>=0.9.21
+Provides-Extra: dev
+Requires-Dist: marimo>=0.19.7; extra == 'dev'
+Requires-Dist: prek>=0.3.1; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: ruff>=0.14.14; extra == 'dev'
+Requires-Dist: ty>=0.0.14; extra == 'dev'
+Provides-Extra: networkx
+Requires-Dist: networkx>=3.0; extra == 'networkx'
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == 'pandas'
+Description-Content-Type: text/markdown
+
+# anywidget-graph
+
+Interactive graph visualization for Python notebooks.
+
+Works with Marimo, Jupyter, VS Code, Colab, anywhere [anywidget](https://anywidget.dev/) runs.
+
+## Features
+
+- **Universal** — One widget, every notebook environment
+- **Backend-agnostic** — Grafeo, Neo4j, NetworkX, pandas, or raw dicts
+- **Interactive** — Pan, zoom, click, expand neighbors, select paths
+- **Customizable** — Colors, sizes, shapes, layouts
+- **Performant** — Virtualized rendering for large graphs
+- **Exportable** — PNG, SVG, JSON
+
+## Installation
+
+```bash
+uv add anywidget-graph
+```
+
+## Quick Start
+
+```python
+from anywidget_graph import Graph
+
+graph = Graph.from_dict({
+    "nodes": [
+        {"id": "alice", "label": "Alice", "group": "person"},
+        {"id": "bob", "label": "Bob", "group": "person"},
+        {"id": "paper", "label": "Graph Theory", "group": "document"},
+    ],
+    "edges": [
+        {"source": "alice", "target": "bob", "label": "knows"},
+        {"source": "alice", "target": "paper", "label": "authored"},
+    ]
+})
+
+graph
+```
+
+## Data Sources
+
+### Dictionary
+
+```python
+from anywidget_graph import Graph
+
+graph = Graph.from_dict({
+    "nodes": [{"id": "a"}, {"id": "b"}],
+    "edges": [{"source": "a", "target": "b"}]
+})
+```
+
+### Grafeo
+
+```python
+from grafeo import GrafeoDB
+from anywidget_graph import Graph
+
+db = GrafeoDB()
+db.execute("INSERT (:Person {name: 'Alice'})-[:KNOWS]->(:Person {name: 'Bob'})")
+
+result = db.execute("MATCH (a)-[r]->(b) RETURN a, r, b")
+graph = Graph.from_grafeo(result)
+```
+
+### Neo4j
+
+```python
+from neo4j import GraphDatabase
+from anywidget_graph import Graph
+
+driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
+
+with driver.session() as session:
+    result = session.run("MATCH (a)-[r]->(b) RETURN a, r, b LIMIT 100")
+    graph = Graph.from_neo4j(result)
+```
+
+### NetworkX
+
+```python
+import networkx as nx
+from anywidget_graph import Graph
+
+G = nx.karate_club_graph()
+graph = Graph.from_networkx(G)
+```
+
+### pandas
+
+```python
+import pandas as pd
+from anywidget_graph import Graph
+
+edges = pd.DataFrame({
+    "source": ["alice", "alice", "bob"],
+    "target": ["bob", "carol", "carol"],
+    "weight": [1.0, 0.5, 0.8]
+})
+
+graph = Graph.from_pandas(edges)
+```
+
+## Interactivity
+
+### Events
+
+```python
+graph = Graph.from_dict(data)
+
+@graph.on_node_click
+def handle_node(node_id, node_data):
+    print(f"Clicked: {node_id}")
+
+@graph.on_edge_click  
+def handle_edge(edge_id, edge_data):
+    print(f"Edge: {edge_data['label']}")
+```
+
+### Selection
+
+```python
+graph.selected_nodes         # Get current selection
+graph.select(["alice"])      # Select nodes
+graph.clear_selection()      # Clear
+```
+
+### Expansion
+
+```python
+graph.expand("alice")        # Show neighbors
+graph.collapse("alice")      # Hide neighbors
+```
+
+## Styling
+
+### By Group
+
+```python
+graph = Graph.from_dict(
+    data,
+    node_styles={
+        "person": {"color": "#4CAF50", "size": 30},
+        "document": {"color": "#2196F3", "shape": "square"},
+    }
+)
+```
+
+### By Property
+
+```python
+graph = Graph.from_dict(
+    data,
+    node_color="group",                    # Color by field
+    node_size=lambda n: n["score"] * 10,   # Size by function
+    edge_width="weight",                   # Width by field
+)
+```
+
+### Layouts
+
+```python
+Graph.from_dict(data, layout="force")        # Default
+Graph.from_dict(data, layout="hierarchical")
+Graph.from_dict(data, layout="circular")
+Graph.from_dict(data, layout="grid")
+```
+
+## Options
+
+```python
+graph = Graph.from_dict(
+    data,
+    width=800,
+    height=600,
+    directed=True,
+    labels=True,
+    edge_labels=False,
+    physics=True,
+    zoom=(0.1, 4),
+)
+```
+
+## Large Graphs
+
+For 1000+ nodes:
+
+```python
+graph = Graph.from_dict(
+    data,
+    virtualize=True,
+    cluster=True,
+)
+```
+
+## Export
+
+```python
+graph.to_png("graph.png")
+graph.to_svg("graph.svg")
+graph.to_json("graph.json")
+```
+
+## Environment Support
+
+| Environment | Supported |
+|-------------|-----------|
+| Marimo | ✅ |
+| JupyterLab | ✅ |
+| Jupyter Notebook | ✅ |
+| VS Code | ✅ |
+| Google Colab | ✅ |
+| Databricks | ✅ |
+
+## Related
+
+- [anywidget](https://anywidget.dev/) — Custom Jupyter widgets made easy
+- [Grafeo](https://github.com/GrafeoDB/grafeo) — Embeddable graph database
+- [grafeo-wasm](https://github.com/GrafeoDB/grafeo-wasm) — Grafeo in the browser
+
+## License
+
+Apache-2.0

anywidget_graph-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+anywidget_graph/__init__.py,sha256=uPbg0OSg6iO8dySwupCzx6zc0LWjsjQcnr-VgLQTSEM,145
+anywidget_graph/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+anywidget_graph/widget.py,sha256=HRcbtmJLnOWzrusKy7Ikedoe_HryNJmDHgK4HK3rCYc,9444
+anywidget_graph-0.1.0.dist-info/METADATA,sha256=RP9R6XK4DQkarK-GXsM-9s6hiR7mBElLgv7TSEFL0Q0,5747
+anywidget_graph-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+anywidget_graph-0.1.0.dist-info/RECORD,,

anywidget_graph-0.1.0.dist-info/WHEEL

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