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

anywidget_graph/__init__.py

@@ -3,4 +3,4 @@
 from anywidget_graph.widget import Graph
 
 __all__ = ["Graph"]
-__version__ = "0.1.0"
+__version__ = "0.2.1"

anywidget_graph/backends/__init__.py

@@ -0,0 +1,71 @@
+"""Database backend abstractions for anywidget-graph."""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from anywidget_graph.backends.arango import ArangoBackend
+from anywidget_graph.backends.grafeo import GrafeoBackend
+from anywidget_graph.backends.ladybug import LadybugBackend
+from anywidget_graph.backends.neo4j import Neo4jBackend
+
+__all__ = [
+    # Protocol
+    "DatabaseBackend",
+    # Backends
+    "ArangoBackend",
+    "GrafeoBackend",
+    "LadybugBackend",
+    "Neo4jBackend",
+    # Registries
+    "BACKENDS",
+    "QUERY_LANGUAGES",
+]
+
+
+@runtime_checkable
+class DatabaseBackend(Protocol):
+    """Protocol defining the interface for database backends.
+
+    Implementations must provide:
+    - execute(query) -> (nodes, edges)
+    - fetch_schema() -> (node_types, edge_types)
+
+    Example
+    -------
+    >>> class MyBackend:
+    ...     def execute(self, query: str) -> tuple[list[dict], list[dict]]:
+    ...         # Execute query and return nodes/edges
+    ...         return [], []
+    ...
+    ...     def fetch_schema(self) -> tuple[list[dict], list[dict]]:
+    ...         return [], []
+    """
+
+    def execute(self, query: str) -> tuple[list[dict], list[dict]]:
+        """Execute a query and return (nodes, edges)."""
+        ...
+
+    def fetch_schema(self) -> tuple[list[dict], list[dict]]:
+        """Fetch schema and return (node_types, edge_types)."""
+        ...
+
+
+# Backend registry for UI
+BACKENDS = [
+    {"id": "neo4j", "name": "Neo4j", "side": "browser", "language": "cypher"},
+    {"id": "neo4j-python", "name": "Neo4j (Python)", "side": "python", "language": "cypher"},
+    {"id": "grafeo", "name": "Grafeo", "side": "python", "language": "cypher"},
+    {"id": "ladybug", "name": "LadybugDB", "side": "python", "language": "cypher"},
+    {"id": "arango", "name": "ArangoDB", "side": "python", "language": "aql"},
+]
+
+# Query language registry
+QUERY_LANGUAGES = [
+    {"id": "cypher", "name": "Cypher", "enabled": True},
+    {"id": "gql", "name": "GQL", "enabled": True},
+    {"id": "sparql", "name": "SPARQL", "enabled": True},
+    {"id": "gremlin", "name": "Gremlin", "enabled": True},
+    {"id": "graphql", "name": "GraphQL", "enabled": True},
+    {"id": "aql", "name": "AQL", "enabled": True},
+]

anywidget_graph/backends/arango.py

@@ -0,0 +1,201 @@
+"""ArangoDB database backend."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from anywidget_graph.converters.base import GraphData
+
+if TYPE_CHECKING:
+    from arango.database import StandardDatabase
+
+
+class ArangoConverter:
+    """Convert ArangoDB AQL results to graph data."""
+
+    def convert(self, result: Any) -> GraphData:
+        """Convert AQL cursor result to nodes and edges.
+
+        Parameters
+        ----------
+        result : Any
+            AQL query cursor/result.
+
+        Returns
+        -------
+        GraphData
+            Dictionary with 'nodes' and 'edges' lists.
+        """
+        nodes: dict[str, dict[str, Any]] = {}
+        edges: list[dict[str, Any]] = []
+
+        for doc in result:
+            if not isinstance(doc, dict):
+                continue
+
+            # Check if it's an edge document (_from and _to fields)
+            if "_from" in doc and "_to" in doc:
+                edge = self._edge_to_dict(doc)
+                edges.append(edge)
+            # Otherwise treat as vertex document
+            elif "_key" in doc or "_id" in doc:
+                node = self._vertex_to_dict(doc)
+                nodes[node["id"]] = node
+
+        return {"nodes": list(nodes.values()), "edges": edges}
+
+    def _vertex_to_dict(self, doc: dict[str, Any]) -> dict[str, Any]:
+        """Convert ArangoDB vertex document to node dict."""
+        # Extract ID from _key or _id
+        if "_key" in doc:
+            node_id = doc["_key"]
+        elif "_id" in doc:
+            node_id = doc["_id"].split("/")[-1]
+        else:
+            node_id = str(id(doc))
+
+        result: dict[str, Any] = {
+            "id": node_id,
+            "label": doc.get("name", doc.get("label", node_id)),
+        }
+
+        # Add non-system properties
+        for key, value in doc.items():
+            if not key.startswith("_") and key not in ("name", "label"):
+                result[key] = value
+
+        return result
+
+    def _edge_to_dict(self, doc: dict[str, Any]) -> dict[str, Any]:
+        """Convert ArangoDB edge document to edge dict."""
+        result: dict[str, Any] = {
+            "source": doc["_from"].split("/")[-1],
+            "target": doc["_to"].split("/")[-1],
+            "label": doc.get("label", doc.get("_key", "")),
+        }
+
+        # Add non-system properties
+        for key, value in doc.items():
+            if not key.startswith("_") and key not in ("label",):
+                result[key] = value
+
+        return result
+
+
+class ArangoBackend:
+    """Backend for ArangoDB multi-model database.
+
+    Parameters
+    ----------
+    db : StandardDatabase | None
+        Existing ArangoDB database connection.
+    host : str
+        ArangoDB host URL (default: "http://localhost:8529").
+    username : str
+        Username for authentication (default: "root").
+    password : str
+        Password for authentication (default: "").
+    database : str
+        Database name (default: "_system").
+
+    Example
+    -------
+    >>> from anywidget_graph.backends import ArangoBackend
+    >>> backend = ArangoBackend(
+    ...     host="http://localhost:8529",
+    ...     username="root",
+    ...     password="password",
+    ...     database="mydb",
+    ... )
+    >>> nodes, edges = backend.execute('''
+    ...     FOR v, e IN 1..2 OUTBOUND 'users/alice' GRAPH 'social'
+    ...     RETURN {vertex: v, edge: e}
+    ... ''')
+
+    Or with an existing connection:
+
+    >>> from arango import ArangoClient
+    >>> client = ArangoClient(hosts="http://localhost:8529")
+    >>> db = client.db("mydb", username="root", password="password")
+    >>> backend = ArangoBackend(db=db)
+    """
+
+    def __init__(
+        self,
+        db: StandardDatabase | None = None,
+        host: str = "http://localhost:8529",
+        username: str = "root",
+        password: str = "",
+        database: str = "_system",
+    ) -> None:
+        self._db = db
+        self._host = host
+        self._username = username
+        self._password = password
+        self._database = database
+        self._converter = ArangoConverter()
+
+    @property
+    def query_language(self) -> str:
+        """Return the default query language."""
+        return "aql"
+
+    @property
+    def db(self) -> StandardDatabase:
+        """Get or create the database connection."""
+        if self._db is None:
+            from arango import ArangoClient
+
+            client = ArangoClient(hosts=self._host)
+            self._db = client.db(
+                self._database,
+                username=self._username,
+                password=self._password,
+            )
+        return self._db
+
+    def execute(self, query: str) -> tuple[list[dict], list[dict]]:
+        """Execute AQL query and return (nodes, edges).
+
+        Parameters
+        ----------
+        query : str
+            AQL query to execute.
+
+        Returns
+        -------
+        tuple[list[dict], list[dict]]
+            Tuple of (nodes, edges) lists.
+        """
+        cursor = self.db.aql.execute(query)
+        data = self._converter.convert(cursor)
+        return data["nodes"], data["edges"]
+
+    def fetch_schema(self) -> tuple[list[dict], list[dict]]:
+        """Fetch ArangoDB schema (collections).
+
+        Returns
+        -------
+        tuple[list[dict], list[dict]]
+            Tuple of (node_collections, edge_collections).
+        """
+        node_types: list[dict[str, Any]] = []
+        edge_types: list[dict[str, Any]] = []
+
+        for coll in self.db.collections():
+            if coll["system"]:
+                continue
+
+            coll_obj = self.db.collection(coll["name"])
+            info: dict[str, Any] = {
+                "name": coll["name"],
+                "count": coll_obj.count(),
+            }
+
+            # Edge collections have type 3
+            if coll.get("type") == 3 or coll.get("type") == "edge":
+                edge_types.append(info)
+            else:
+                node_types.append(info)
+
+        return node_types, edge_types

anywidget_graph/backends/grafeo.py

@@ -0,0 +1,70 @@
+"""Grafeo database backend (Python-side execution)."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from anywidget_graph.converters import (
+    get_node_id,
+    is_node,
+    is_relationship,
+    node_to_dict,
+    relationship_to_dict,
+)
+
+if TYPE_CHECKING:
+    pass
+
+
+class GrafeoBackend:
+    """Backend for Grafeo database connections."""
+
+    def __init__(self, db: Any) -> None:
+        """Initialize with a GrafeoDB instance."""
+        self._db = db
+
+    @property
+    def db(self) -> Any:
+        """Get the underlying database instance."""
+        return self._db
+
+    def execute(self, query: str) -> tuple[list[dict], list[dict]]:
+        """Execute a Cypher query and return (nodes, edges)."""
+        result = self._db.execute(query)
+        return self._process_result(result)
+
+    def fetch_schema(self) -> tuple[list[dict], list[dict]]:
+        """Fetch schema from Grafeo database."""
+        # Grafeo schema fetching would be implemented here
+        # For now, return empty schema
+        return [], []
+
+    def _process_result(self, result: Any) -> tuple[list[dict], list[dict]]:
+        """Process query results into nodes and edges."""
+        nodes: dict[str, dict] = {}
+        edges: list[dict] = []
+
+        records = list(result) if hasattr(result, "__iter__") else [result]
+
+        for record in records:
+            items = self._extract_items(record)
+            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 list(nodes.values()), edges
+
+    def _extract_items(self, record: Any) -> list[tuple[str, Any]]:
+        """Extract key-value items from a record."""
+        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 []

anywidget_graph/backends/ladybug.py

@@ -0,0 +1,94 @@
+"""LadybugDB database backend."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from anywidget_graph.converters.cypher import CypherConverter
+
+if TYPE_CHECKING:
+    pass
+
+
+class LadybugBackend:
+    """Backend for LadybugDB embedded graph database.
+
+    LadybugDB is an embedded graph database that supports Cypher queries.
+
+    Parameters
+    ----------
+    db : Any
+        LadybugDB database instance.
+
+    Example
+    -------
+    >>> from ladybug import LadybugDB
+    >>> db = LadybugDB()
+    >>> db.execute("CREATE (a:Person {name: 'Alice'})-[:KNOWS]->(b:Person {name: 'Bob'})")
+    >>>
+    >>> from anywidget_graph.backends import LadybugBackend
+    >>> backend = LadybugBackend(db)
+    >>> nodes, edges = backend.execute("MATCH (n)-[r]->(m) RETURN n, r, m")
+    """
+
+    def __init__(self, db: Any) -> None:
+        self._db = db
+        self._converter = CypherConverter()
+
+    @property
+    def query_language(self) -> str:
+        """Return the default query language."""
+        return "cypher"
+
+    @property
+    def db(self) -> Any:
+        """Get the underlying database instance."""
+        return self._db
+
+    def execute(self, query: str) -> tuple[list[dict], list[dict]]:
+        """Execute Cypher query and return (nodes, edges).
+
+        Parameters
+        ----------
+        query : str
+            Cypher query to execute.
+
+        Returns
+        -------
+        tuple[list[dict], list[dict]]
+            Tuple of (nodes, edges) lists.
+        """
+        result = self._db.execute(query)
+        data = self._converter.convert(result)
+        return data["nodes"], data["edges"]
+
+    def fetch_schema(self) -> tuple[list[dict], list[dict]]:
+        """Fetch LadybugDB schema.
+
+        Returns
+        -------
+        tuple[list[dict], list[dict]]
+            Tuple of (node_types, edge_types).
+        """
+        node_types: list[dict[str, Any]] = []
+        edge_types: list[dict[str, Any]] = []
+
+        # Try to get labels if supported
+        try:
+            labels_result = self._db.execute("CALL db.labels()")
+            for record in labels_result:
+                label = record[0] if hasattr(record, "__getitem__") else str(record)
+                node_types.append({"label": label, "properties": []})
+        except Exception:
+            pass
+
+        # Try to get relationship types if supported
+        try:
+            types_result = self._db.execute("CALL db.relationshipTypes()")
+            for record in types_result:
+                rel_type = record[0] if hasattr(record, "__getitem__") else str(record)
+                edge_types.append({"type": rel_type, "properties": []})
+        except Exception:
+            pass
+
+        return node_types, edge_types

anywidget_graph/backends/neo4j.py

@@ -0,0 +1,143 @@
+"""Neo4j database backend using the Python driver."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from anywidget_graph.converters.cypher import CypherConverter
+
+if TYPE_CHECKING:
+    from neo4j import Driver
+
+
+class Neo4jBackend:
+    """Backend for Neo4j database using the Python driver.
+
+    This executes queries Python-side (not in browser).
+    Use for server-side notebooks or when browser connectivity is limited.
+
+    Parameters
+    ----------
+    driver : Driver | None
+        Existing Neo4j driver instance.
+    uri : str | None
+        Neo4j connection URI (e.g., "neo4j://localhost:7687").
+    auth : tuple[str, str] | None
+        Authentication tuple (username, password).
+    database : str
+        Database name to use (default: "neo4j").
+
+    Example
+    -------
+    >>> from anywidget_graph.backends import Neo4jBackend
+    >>> backend = Neo4jBackend(
+    ...     uri="neo4j://localhost:7687",
+    ...     auth=("neo4j", "password"),
+    ... )
+    >>> nodes, edges = backend.execute("MATCH (n)-[r]->(m) RETURN n, r, m LIMIT 10")
+
+    Or with an existing driver:
+
+    >>> from neo4j import GraphDatabase
+    >>> driver = GraphDatabase.driver(uri, auth=auth)
+    >>> backend = Neo4jBackend(driver=driver)
+    """
+
+    def __init__(
+        self,
+        driver: Driver | None = None,
+        uri: str | None = None,
+        auth: tuple[str, str] | None = None,
+        database: str = "neo4j",
+    ) -> None:
+        self._driver = driver
+        self._uri = uri
+        self._auth = auth
+        self._database = database
+        self._converter = CypherConverter()
+        self._owns_driver = driver is None  # Track if we created the driver
+
+    @property
+    def query_language(self) -> str:
+        """Return the default query language."""
+        return "cypher"
+
+    @property
+    def driver(self) -> Driver:
+        """Get or create the Neo4j driver."""
+        if self._driver is None:
+            if self._uri is None:
+                msg = "Either driver or uri must be provided"
+                raise ValueError(msg)
+            from neo4j import GraphDatabase
+
+            self._driver = GraphDatabase.driver(self._uri, auth=self._auth)
+        return self._driver
+
+    def execute(self, query: str) -> tuple[list[dict], list[dict]]:
+        """Execute Cypher query and return (nodes, edges).
+
+        Parameters
+        ----------
+        query : str
+            Cypher query to execute.
+
+        Returns
+        -------
+        tuple[list[dict], list[dict]]
+            Tuple of (nodes, edges) lists.
+        """
+        with self.driver.session(database=self._database) as session:
+            result = session.run(query)
+            records = list(result)  # Consume within session
+
+        data = self._converter.convert(records)
+        return data["nodes"], data["edges"]
+
+    def fetch_schema(self) -> tuple[list[dict], list[dict]]:
+        """Fetch Neo4j schema.
+
+        Returns
+        -------
+        tuple[list[dict], list[dict]]
+            Tuple of (node_types, edge_types) with label/type info and properties.
+        """
+        node_types: list[dict[str, Any]] = []
+        edge_types: list[dict[str, Any]] = []
+
+        with self.driver.session(database=self._database) as session:
+            # Get node labels
+            labels_result = session.run("CALL db.labels()")
+            for record in labels_result:
+                label = record[0]
+                # Get properties for this label
+                props_result = session.run(f"MATCH (n:`{label}`) UNWIND keys(n) AS key RETURN DISTINCT key LIMIT 20")
+                properties = [r[0] for r in props_result]
+                node_types.append({"label": label, "properties": properties})
+
+            # Get relationship types
+            rel_types_result = session.run("CALL db.relationshipTypes()")
+            for record in rel_types_result:
+                rel_type = record[0]
+                # Get properties for this type
+                props_result = session.run(
+                    f"MATCH ()-[r:`{rel_type}`]->() UNWIND keys(r) AS key RETURN DISTINCT key LIMIT 20"
+                )
+                properties = [r[0] for r in props_result]
+                edge_types.append({"type": rel_type, "properties": properties})
+
+        return node_types, edge_types
+
+    def close(self) -> None:
+        """Close the driver connection if we own it."""
+        if self._driver and self._owns_driver:
+            self._driver.close()
+            self._driver = None
+
+    def __enter__(self) -> Neo4jBackend:
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        """Context manager exit."""
+        self.close()

anywidget_graph/converters/__init__.py

@@ -0,0 +1,35 @@
+"""Data conversion utilities for graph data."""
+
+from __future__ import annotations
+
+from anywidget_graph.converters.base import GraphData, ResultConverter
+from anywidget_graph.converters.common import (
+    get_node_id,
+    is_node,
+    is_relationship,
+    node_to_dict,
+    relationship_to_dict,
+)
+from anywidget_graph.converters.cypher import CypherConverter
+from anywidget_graph.converters.gql import GQLConverter
+from anywidget_graph.converters.graphql import GraphQLConverter
+from anywidget_graph.converters.gremlin import GremlinConverter
+from anywidget_graph.converters.sparql import SPARQLConverter
+
+__all__ = [
+    # Base types
+    "GraphData",
+    "ResultConverter",
+    # Common utilities
+    "get_node_id",
+    "is_node",
+    "is_relationship",
+    "node_to_dict",
+    "relationship_to_dict",
+    # Converters
+    "CypherConverter",
+    "GQLConverter",
+    "GraphQLConverter",
+    "GremlinConverter",
+    "SPARQLConverter",
+]

anywidget_graph/converters/base.py

@@ -0,0 +1,77 @@
+"""Base types and protocols for result converters."""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, TypedDict
+
+
+class NodeDict(TypedDict, total=False):
+    """Standard node representation.
+
+    Required:
+        id: Unique identifier for the node.
+
+    Optional:
+        label: Display label for the node.
+        labels: List of type labels (e.g., Neo4j labels).
+        Additional properties are allowed.
+    """
+
+    id: str
+    label: str
+    labels: list[str]
+
+
+class EdgeDict(TypedDict, total=False):
+    """Standard edge representation.
+
+    Required:
+        source: ID of the source node.
+        target: ID of the target node.
+
+    Optional:
+        label: Display label/type for the edge.
+        Additional properties are allowed.
+    """
+
+    source: str
+    target: str
+    label: str
+
+
+class GraphData(TypedDict):
+    """Standard graph data format returned by converters."""
+
+    nodes: list[dict[str, Any]]
+    edges: list[dict[str, Any]]
+
+
+class ResultConverter(Protocol):
+    """Protocol for converting query results to graph data.
+
+    Implementations should handle the specific result format of their
+    query language and return a standardized GraphData structure.
+
+    Example
+    -------
+    >>> class MyConverter:
+    ...     def convert(self, result: Any) -> GraphData:
+    ...         nodes = [{"id": "1", "label": "Node"}]
+    ...         edges = [{"source": "1", "target": "2"}]
+    ...         return {"nodes": nodes, "edges": edges}
+    """
+
+    def convert(self, result: Any) -> GraphData:
+        """Convert raw query result to nodes and edges.
+
+        Parameters
+        ----------
+        result : Any
+            Raw query result from the database driver.
+
+        Returns
+        -------
+        GraphData
+            Dictionary with 'nodes' and 'edges' lists.
+        """
+        ...