anywidget-graph 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

anywidget_graph/converters/common.py

@@ -0,0 +1,92 @@
+"""Common node and edge conversion utilities."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def is_node(obj: Any) -> bool:
+    """Check if an object represents a graph node."""
+    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:
+    """Check if an object represents a graph relationship."""
+    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:
+    """Extract the ID from a node object."""
+    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[str, Any]:
+    """Convert a node object to a dictionary."""
+    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[str, Any]:
+    """Convert a relationship object to a dictionary."""
+    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/converters/cypher.py

@@ -0,0 +1,107 @@
+"""Converter for Cypher/Neo4j query results."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anywidget_graph.converters.base import GraphData
+from anywidget_graph.converters.common import (
+    get_node_id,
+    is_node,
+    is_relationship,
+    node_to_dict,
+    relationship_to_dict,
+)
+
+
+class CypherConverter:
+    """Convert Cypher query results to graph data.
+
+    Handles various result formats from Neo4j and compatible databases:
+    - Neo4j Python driver Result objects
+    - Record objects with .items() or .data() methods
+    - Path objects containing nodes and relationships
+    - Lists of nodes/relationships
+
+    Example
+    -------
+    >>> from neo4j import GraphDatabase
+    >>> driver = GraphDatabase.driver(uri, auth=auth)
+    >>> with driver.session() as session:
+    ...     result = session.run("MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 10")
+    ...     converter = CypherConverter()
+    ...     data = converter.convert(result)
+    ...     print(f"Found {len(data['nodes'])} nodes")
+    """
+
+    def convert(self, result: Any) -> GraphData:
+        """Convert Cypher result to nodes and edges.
+
+        Parameters
+        ----------
+        result : Any
+            Query result from Neo4j driver or compatible database.
+
+        Returns
+        -------
+        GraphData
+            Dictionary with 'nodes' and 'edges' lists.
+        """
+        nodes: dict[str, dict[str, Any]] = {}
+        edges: list[dict[str, Any]] = []
+
+        records = list(result) if hasattr(result, "__iter__") else [result]
+
+        for record in records:
+            for _key, value in self._extract_items(record):
+                self._process_value(value, nodes, edges)
+
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+    def _extract_items(self, record: Any) -> list[tuple[str, Any]]:
+        """Extract key-value items from a record.
+
+        Handles multiple record formats:
+        - Records with .items() method (Neo4j Record)
+        - Records with .data() method
+        - Plain dictionaries
+        """
+        if hasattr(record, "items"):
+            items = record.items() if callable(record.items) else record.items
+            return list(items)
+        elif hasattr(record, "data"):
+            return list(record.data().items())
+        elif isinstance(record, dict):
+            return list(record.items())
+        return []
+
+    def _process_value(
+        self,
+        value: Any,
+        nodes: dict[str, dict[str, Any]],
+        edges: list[dict[str, Any]],
+    ) -> None:
+        """Process a single value, handling paths and collections recursively."""
+        if value is None:
+            return
+
+        # Handle Path objects (have .nodes and .relationships attributes)
+        if hasattr(value, "nodes") and hasattr(value, "relationships"):
+            for node in value.nodes:
+                node_id = get_node_id(node)
+                if node_id not in nodes:
+                    nodes[node_id] = node_to_dict(node)
+            for rel in value.relationships:
+                edges.append(relationship_to_dict(rel))
+        # Handle individual nodes
+        elif is_node(value):
+            node_id = get_node_id(value)
+            if node_id not in nodes:
+                nodes[node_id] = node_to_dict(value)
+        # Handle individual relationships
+        elif is_relationship(value):
+            edges.append(relationship_to_dict(value))
+        # Handle lists/collections
+        elif isinstance(value, (list, tuple)):
+            for item in value:
+                self._process_value(item, nodes, edges)

anywidget_graph/converters/gql.py

@@ -0,0 +1,15 @@
+"""Converter for ISO GQL query results.
+
+GQL (Graph Query Language) is the ISO standard graph query language.
+Its result format is similar to Cypher, so this module provides an
+alias to the CypherConverter.
+"""
+
+from __future__ import annotations
+
+from anywidget_graph.converters.cypher import CypherConverter
+
+# GQL uses the same result format as Cypher
+GQLConverter = CypherConverter
+
+__all__ = ["GQLConverter"]

anywidget_graph/converters/graphql.py

@@ -0,0 +1,208 @@
+"""Converter for GraphQL query results."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anywidget_graph.converters.base import GraphData
+
+
+class GraphQLConverter:
+    """Convert GraphQL JSON responses to graph data.
+
+    Handles various GraphQL schema patterns:
+    - Relay-style connections with nodes/edges
+    - Simple lists of objects with references
+    - Nested object structures
+
+    Parameters
+    ----------
+    id_field : str
+        Field name used for node IDs (default: "id").
+    label_field : str
+        Field name used for node labels (default: "name").
+    nodes_path : str | None
+        Dot-separated path to nodes list (e.g., "data.allPeople.nodes").
+        If None, auto-detection is used.
+    edges_path : str | None
+        Dot-separated path to edges list (e.g., "data.connections.edges").
+        If None, auto-detection is used.
+    source_field : str
+        Field name for edge source (default: "source").
+    target_field : str
+        Field name for edge target (default: "target").
+
+    Example
+    -------
+    >>> import requests
+    >>> response = requests.post(url, json={"query": query})
+    >>> result = response.json()
+    >>> converter = GraphQLConverter(
+    ...     nodes_path="data.characters.results",
+    ...     id_field="id",
+    ...     label_field="name",
+    ... )
+    >>> data = converter.convert(result)
+    """
+
+    def __init__(
+        self,
+        id_field: str = "id",
+        label_field: str = "name",
+        nodes_path: str | None = None,
+        edges_path: str | None = None,
+        source_field: str = "source",
+        target_field: str = "target",
+    ) -> None:
+        self.id_field = id_field
+        self.label_field = label_field
+        self.nodes_path = nodes_path
+        self.edges_path = edges_path
+        self.source_field = source_field
+        self.target_field = target_field
+
+    def convert(self, result: Any) -> GraphData:
+        """Convert GraphQL result to nodes and edges.
+
+        Parameters
+        ----------
+        result : Any
+            GraphQL JSON response.
+
+        Returns
+        -------
+        GraphData
+            Dictionary with 'nodes' and 'edges' lists.
+        """
+        # Unwrap data envelope if present
+        data = result.get("data", result) if isinstance(result, dict) else result
+
+        nodes: dict[str, dict[str, Any]] = {}
+        edges: list[dict[str, Any]] = []
+
+        # If explicit paths provided, use them
+        if self.nodes_path:
+            node_list = self._get_path(data, self.nodes_path) or []
+            for item in node_list:
+                if isinstance(item, dict):
+                    node = self._item_to_node(item)
+                    nodes[node["id"]] = node
+
+        if self.edges_path:
+            edge_list = self._get_path(data, self.edges_path) or []
+            for item in edge_list:
+                if isinstance(item, dict):
+                    edge = self._item_to_edge(item)
+                    if edge.get("source") and edge.get("target"):
+                        edges.append(edge)
+
+        # Otherwise, auto-detect structure
+        if not self.nodes_path and not self.edges_path:
+            self._auto_extract(data, nodes, edges, None)
+
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+    def _get_path(self, data: Any, path: str) -> Any:
+        """Navigate nested dict by dot-separated path."""
+        for key in path.split("."):
+            if isinstance(data, dict):
+                data = data.get(key)
+            elif isinstance(data, list) and key.isdigit():
+                idx = int(key)
+                data = data[idx] if idx < len(data) else None
+            else:
+                return None
+        return data
+
+    def _item_to_node(self, item: dict[str, Any]) -> dict[str, Any]:
+        """Convert a dict item to node format."""
+        node_id = str(item.get(self.id_field, id(item)))
+        label = item.get(self.label_field, "")
+
+        result: dict[str, Any] = {
+            "id": node_id,
+            "label": str(label) if label else node_id,
+        }
+
+        # Add scalar properties (skip nested objects and lists)
+        for key, value in item.items():
+            if key not in (self.id_field,) and not isinstance(value, (dict, list)):
+                result[key] = value
+
+        return result
+
+    def _item_to_edge(self, item: dict[str, Any]) -> dict[str, Any]:
+        """Convert a dict item to edge format."""
+        source = item.get(self.source_field, item.get("from", ""))
+        target = item.get(self.target_field, item.get("to", ""))
+
+        # Handle nested node references
+        if isinstance(source, dict):
+            source = source.get(self.id_field, "")
+        if isinstance(target, dict):
+            target = target.get(self.id_field, "")
+
+        return {
+            "source": str(source),
+            "target": str(target),
+            "label": str(item.get("label", item.get("type", item.get("__typename", "")))),
+        }
+
+    def _auto_extract(
+        self,
+        data: Any,
+        nodes: dict[str, dict[str, Any]],
+        edges: list[dict[str, Any]],
+        parent_id: str | None,
+    ) -> None:
+        """Auto-extract graph structure from nested data."""
+        if isinstance(data, dict):
+            # Check if this looks like a node (has ID field)
+            if self.id_field in data:
+                node = self._item_to_node(data)
+                nodes[node["id"]] = node
+
+                # Create edge from parent
+                if parent_id and parent_id != node["id"]:
+                    edges.append(
+                        {
+                            "source": parent_id,
+                            "target": node["id"],
+                            "label": "contains",
+                        }
+                    )
+
+                # Process nested references
+                for key, value in data.items():
+                    if isinstance(value, dict) and self.id_field in value:
+                        # Direct reference to another node
+                        ref_node = self._item_to_node(value)
+                        nodes[ref_node["id"]] = ref_node
+                        edges.append(
+                            {
+                                "source": node["id"],
+                                "target": ref_node["id"],
+                                "label": key,
+                            }
+                        )
+                    elif isinstance(value, list):
+                        # List of possible references
+                        for item in value:
+                            if isinstance(item, dict) and self.id_field in item:
+                                ref_node = self._item_to_node(item)
+                                nodes[ref_node["id"]] = ref_node
+                                edges.append(
+                                    {
+                                        "source": node["id"],
+                                        "target": ref_node["id"],
+                                        "label": key,
+                                    }
+                                )
+            else:
+                # Not a node, recurse into values
+                for value in data.values():
+                    self._auto_extract(value, nodes, edges, parent_id)
+
+        elif isinstance(data, list):
+            for item in data:
+                self._auto_extract(item, nodes, edges, parent_id)

anywidget_graph/converters/gremlin.py

@@ -0,0 +1,159 @@
+"""Converter for Gremlin/TinkerPop query results."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from anywidget_graph.converters.base import GraphData
+
+
+class GremlinConverter:
+    """Convert Gremlin traversal results to graph data.
+
+    Handles various TinkerPop result types:
+    - Vertex objects
+    - Edge objects
+    - Path objects from path() traversals
+    - ValueMap results from valueMap() traversals
+    - Dictionaries from elementMap() traversals
+
+    Example
+    -------
+    >>> from gremlin_python.driver import client
+    >>> gremlin_client = client.Client('ws://localhost:8182/gremlin', 'g')
+    >>> result = gremlin_client.submit("g.V().limit(10)").all().result()
+    >>> converter = GremlinConverter()
+    >>> data = converter.convert(result)
+    """
+
+    def convert(self, result: Any) -> GraphData:
+        """Convert Gremlin result to nodes and edges.
+
+        Parameters
+        ----------
+        result : Any
+            Query result from Gremlin server.
+
+        Returns
+        -------
+        GraphData
+            Dictionary with 'nodes' and 'edges' lists.
+        """
+        nodes: dict[str, dict[str, Any]] = {}
+        edges: list[dict[str, Any]] = []
+
+        items = list(result) if hasattr(result, "__iter__") else [result]
+
+        for item in items:
+            self._process_item(item, nodes, edges)
+
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+    def _process_item(
+        self,
+        item: Any,
+        nodes: dict[str, dict[str, Any]],
+        edges: list[dict[str, Any]],
+    ) -> None:
+        """Process a single result item."""
+        if item is None:
+            return
+
+        # Path object (has .objects attribute)
+        if hasattr(item, "objects"):
+            for obj in item.objects:
+                self._process_item(obj, nodes, edges)
+        # Vertex
+        elif self._is_vertex(item):
+            node_id = str(item.id)
+            if node_id not in nodes:
+                nodes[node_id] = self._vertex_to_dict(item)
+        # Edge
+        elif self._is_edge(item):
+            edges.append(self._edge_to_dict(item))
+        # Dict (from valueMap, elementMap, etc.)
+        elif isinstance(item, dict):
+            self._process_dict(item, nodes, edges)
+        # List/collection
+        elif isinstance(item, (list, tuple)):
+            for sub_item in item:
+                self._process_item(sub_item, nodes, edges)
+
+    def _is_vertex(self, obj: Any) -> bool:
+        """Check if object is a Gremlin Vertex."""
+        # Vertex has id and label but not outV/inV
+        return hasattr(obj, "id") and hasattr(obj, "label") and not hasattr(obj, "outV") and not hasattr(obj, "inV")
+
+    def _is_edge(self, obj: Any) -> bool:
+        """Check if object is a Gremlin Edge."""
+        # Edge has outV and inV
+        return hasattr(obj, "outV") and hasattr(obj, "inV")
+
+    def _vertex_to_dict(self, vertex: Any) -> dict[str, Any]:
+        """Convert Vertex to dict."""
+        result: dict[str, Any] = {
+            "id": str(vertex.id),
+            "label": str(vertex.label),
+        }
+        # Extract properties if available
+        if hasattr(vertex, "properties"):
+            props = vertex.properties
+            if callable(props):
+                props = props()
+            if hasattr(props, "__iter__"):
+                for prop in props:
+                    if hasattr(prop, "key") and hasattr(prop, "value"):
+                        result[prop.key] = prop.value
+        return result
+
+    def _edge_to_dict(self, edge: Any) -> dict[str, Any]:
+        """Convert Edge to dict."""
+        result: dict[str, Any] = {
+            "source": str(edge.outV.id if hasattr(edge.outV, "id") else edge.outV),
+            "target": str(edge.inV.id if hasattr(edge.inV, "id") else edge.inV),
+            "label": str(edge.label),
+        }
+        # Extract properties if available
+        if hasattr(edge, "properties"):
+            props = edge.properties
+            if callable(props):
+                props = props()
+            if isinstance(props, dict):
+                result.update(props)
+        return result
+
+    def _process_dict(
+        self,
+        item: dict[str, Any],
+        nodes: dict[str, dict[str, Any]],
+        edges: list[dict[str, Any]],
+    ) -> None:
+        """Process a dictionary result (from elementMap/valueMap)."""
+        # Check for edge indicators
+        if "IN" in item and "OUT" in item:
+            # This is an edge from elementMap()
+            edge = {
+                "source": str(item.get("OUT", {}).get("id", item.get("OUT", ""))),
+                "target": str(item.get("IN", {}).get("id", item.get("IN", ""))),
+                "label": str(item.get("label", "")),
+            }
+            # Add other properties
+            for key, value in item.items():
+                if key not in ("id", "label", "IN", "OUT"):
+                    edge[key] = self._flatten_value(value)
+            edges.append(edge)
+        elif "id" in item:
+            # This is a vertex
+            node_id = str(item["id"])
+            if node_id not in nodes:
+                node = {"id": node_id}
+                for key, value in item.items():
+                    if key != "id":
+                        node[key] = self._flatten_value(value)
+                nodes[node_id] = node
+
+    def _flatten_value(self, value: Any) -> Any:
+        """Flatten single-element lists (common in valueMap results)."""
+        if isinstance(value, list) and len(value) == 1:
+            return value[0]
+        return value