anywidget-graph 0.3.0__tar.gz → 0.4.0__tar.gz

{anywidget_graph-0.3.0 → anywidget_graph-0.4.0}/.github/workflows/ci.yml

@@ -12,6 +12,9 @@ jobs:
     strategy:
       matrix:
         python-version: ["3.12", "3.13", "3.14"]
+    env:
+      # Without this, uv follows .python-version and every job runs 3.12
+      UV_PYTHON: ${{ matrix.python-version }}
 
     steps:
       - uses: actions/checkout@v4
@@ -22,6 +25,12 @@ jobs:
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}
 
+      # The suite parses the ESM bundle and runs the browser-side modules with Node
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
       - name: Install dependencies
         run: uv sync --dev
 

anywidget_graph-0.4.0/.github/workflows/grafeo-latest.yml

@@ -0,0 +1,47 @@
+name: Grafeo latest
+
+# Runs the suite against the newest grafeo on PyPI (pre-releases included),
+# so engine changes show up before users hit them. The lockfile pins the
+# version used by regular CI; this job deliberately ignores it.
+
+on:
+  schedule:
+    - cron: "17 5 * * 1" # Mondays 05:17 UTC
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.12", "3.14"]
+    env:
+      UV_PYTHON: ${{ matrix.python-version }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: uv sync --dev
+
+      - name: Upgrade grafeo to the newest release (pre-releases included)
+        run: uv pip install --upgrade --prerelease allow grafeo
+
+      - name: Show engine
+        run: uv run --no-sync python -c "import grafeo; print(grafeo.__version__, grafeo.build_info())"
+
+      # --no-sync keeps the upgraded grafeo instead of restoring the locked one
+      - name: Run tests
+        run: uv run --no-sync pytest -v

{anywidget_graph-0.3.0 → anywidget_graph-0.4.0}/CHANGELOG.md

@@ -1,5 +1,53 @@
 # Changelog
 
+## 0.4.0 2026-10-09
+
+### Features
+
+- **Linked lanes**: `lanes` shows several graphs side by side in one canvas, each with its own layout and title; edges between lanes (or marked `cross`) are drawn as soft curves on an overlay and light up with hover or selection
+- **Live append**: `append()` (or the `append_batch` state a host sets) adds nodes and edges without a re-layout; existing nodes keep their positions, new ones fade in and edges draw in, staggered by `append_stagger_ms` and kept under 1.5 s per batch (`append_animation="none"` turns it off)
+- **Lane widths, column lanes and action lanes**: a lane can be narrower or wider (`width`), stack its nodes in a column (`arrange: "column"`), or hold a clickable glyph instead of nodes (`action`, `glyph`, `caption`) that reports clicks in `lane_action`; the camera frames every lane and the lanes stretch to the canvas's shape
+- **Pulse**: `pulse_nodes` gives the listed nodes a soft pulse
+- **Host theme**: `theme` sets the background, panels, text, borders and accent from the host page
+- **Feature detection**: the widget sets `_features` when it renders
+- **Fill the host**: `fill=True` makes the widget take its host element's size (100% wide and high) and follow its resizes; `width` and `height` are then ignored
+
+### Improvements
+
+- **Grafeo 0.5.44**: the `grafeo` extra now requires `grafeo>=0.5.44,<0.7`, ready for the 0.6.0 release
+- **Browser engine 0.5.44**: WASM mode loads `@grafeo-db/wasm@0.5.44` (was 0.5.0) from jsDelivr; the version is set in one place (`GRAFEO_WASM_VERSION` in `ui/grafeo-embed.js`)
+- **Paths and lists render**: results with `RETURN p`, `collect(n)`, variable-length relationships or `nodes(p)` / `relationships(p)` now show their nodes and edges in all three Grafeo modes; nodes that are only referenced by a path or an edge are looked up
+- **Shared Grafeo result conversion** for the server and WASM modes (`ui/grafeo-result.js`)
+- Schema panel shows counts in Grafeo server and WASM modes
+- Grafeo server errors show the server's `detail` message instead of raw JSON
+- Unknown query languages in embedded mode (for example AQL) report Grafeo's error instead of a GQL syntax error
+- The ESM bundler renames every backend function automatically and no longer touches method calls with the same name
+- Weekly CI job runs the suite against the newest grafeo on PyPI, pre-releases included; the CI Python matrix now really runs 3.13 and 3.14
+
+### Bug Fixes
+
+- Fixed WASM mode: `@grafeo-db/wasm` is built for bundlers since 0.5.x and has no init function, so the esm.sh import failed; the binary is now instantiated directly (0.5.0 also panicked on every query in the browser)
+- Fixed Grafeo server and WASM results rendering nothing: nodes and edges were matched on `labels` / `type` / `start` instead of Grafeo's `_labels` / `_type` / `_source` / `_target`
+- Fixed Grafeo server schema request (`/databases/{name}/schema` does not exist, now `GET /db/{name}/schema`)
+- Fixed Grafeo schema parsing in WASM mode and in `GrafeoBackend.fetch_schema()` (labels are `{name, count}` objects)
+- Fixed a node property called `id` (or an edge property called `source` / `target`) replacing the engine identity, which left edges pointing at missing nodes and blanked the widget (the demo data has such properties)
+- Fixed duplicate edges from undirected matches in embedded mode
+- Fixed neighbor expansion on Grafeo: integer ids were compared as strings (`id(n) = "42"`) and never matched; node ids are now escaped in generated queries, and SPARQL / GraphQL sessions expand with Cypher
+- Fixed the widget going blank when an edge's endpoint is missing or a node id repeats (Graphology throws), for example when new results replace the demo data
+- Demo mode loads its statements one at a time and refreshes the schema panel afterwards
+- Fixed `Sigma: Container has no width` when the widget is mounted in a hidden or not yet sized container (a closed panel, a tab); it now renders once the container has a size
+
+## 0.3.1 2026-03-16
+
+### New Features
+
+- **Lasso selection**: Freeform lasso tool for selecting nodes by drawing around them
+
+### Bug Fixes
+
+- Fixed missing ICONS import causing zoom and lasso buttons to fail
+- Fixed `lassoSvg` referenced before declaration, crashing widget on load
+
 ## 0.3.0
 
 ### New Features

{anywidget_graph-0.3.0 → anywidget_graph-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: anywidget-graph
-Version: 0.3.0
+Version: 0.4.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
@@ -32,7 +32,7 @@ Requires-Dist: ruff>=0.15; extra == 'dev'
 Requires-Dist: ty>=0.0; extra == 'dev'
 Provides-Extra: embed
 Provides-Extra: grafeo
-Requires-Dist: grafeo>=0.5; extra == 'grafeo'
+Requires-Dist: grafeo<0.7,>=0.5.44; extra == 'grafeo'
 Provides-Extra: networkx
 Requires-Dist: networkx>=3.0; extra == 'networkx'
 Provides-Extra: pandas
@@ -224,6 +224,29 @@ graph.unpin_all()                   # Unpin everything
 graph.clear()                   # Remove all nodes, edges, pins, and selection
 ```
 
+### Linked lanes and live append
+
+Show two graphs side by side in one canvas, each laid out in its own lane, with curved edges between them, and grow them while a process runs:
+
+```python
+graph = Graph(
+    lanes=[{"id": "source", "title": "Source graph"}, {"id": "target", "title": "Target graph"}],
+    nodes=[{"id": "a", "lane": "source"}, {"id": "b", "lane": "source"}, {"id": "x", "lane": "target"}],
+    edges=[{"source": "a", "target": "b"}, {"source": "x", "target": "a", "cross": True}],
+)
+graph.append(nodes=[{"id": "y", "lane": "target"}], edges=[{"source": "y", "target": "b"}])
+graph.pulse_nodes = ["b"]       # a soft pulse on these nodes; [] stops it
+graph.theme = {"background": "#0d1416", "panel": "#121b1e", "text": "#dbe7e5", "muted": "#8ea3a3", "border": "#1e2b2f", "accent": "#5bb8a9"}
+```
+
+- `lanes`: lanes left to right; a node's `lane` picks one (a node without a known lane goes to the first). Edges between lanes (or marked `cross`) are drawn as soft curves above both lanes and light up when either end is hovered or selected. Without `lanes` the widget behaves as before.
+- `append(nodes, edges)`: adds items without a re-layout; existing nodes keep their positions, a new node is placed at the height of its neighbours in other lanes (or next to its neighbours in its lane). New items fade in and edges draw from source to target, `append_stagger_ms` (default 60) apart; a large batch is kept under 1.5 s. `append_animation="none"` turns the animation off.
+- Lane options: `width` is a lane's share of the standard width (default 1); `arrange: "column"` stacks the lane's nodes in the middle of its band (for a few roots, such as repositories, whose edges then fan out into the next lane); `action: True` makes a lane without nodes that shows a glyph button (`glyph`: a list of colours drawn as stacked bars, `caption`: text under it). The camera frames all lanes, and the lanes stretch to the canvas's shape.
+- `lane_action`: set to `{"lane": <id>, "seq": <n>}` when an action lane's glyph is clicked, so the host can respond (open a panel, switch a view).
+- `pulse_nodes`: ids that pulse softly.
+- `theme`: host colours (`background`, `panel`, `text`, `muted`, `border`, `accent`) that replace the widget's light and dark defaults.
+- `_features`: the widget sets the capabilities it supports when it renders, so a host can detect an older build.
+
 ## Styling
 
 ### Property-based coloring
@@ -263,6 +286,7 @@ graph = Graph(
     edges=edges,
     width=800,                  # Widget width (px)
     height=600,                 # Widget height (px)
+    fill=False,                 # Take the host's size and follow resizes (ignores width/height)
     background="#fafafa",       # Background color
     show_labels=True,           # Node labels
     show_edge_labels=False,     # Edge labels
@@ -280,10 +304,35 @@ graph = Graph(
 
 ### Grafeo (default)
 
+Grafeo runs in one of three modes, picked with `grafeo_connection_mode` or in the settings panel.
+
+**Embedded** (Python, the default): queries run in the notebook kernel. Requires the `grafeo` extra (`grafeo>=0.5.44,<0.7`).
+
 ```python
 import grafeo
 db = grafeo.GrafeoDB()
-graph = Graph(database_backend="grafeo", grafeo_db=db)
+graph = Graph(database_backend="grafeo", grafeo_db=db, query_language="gql")
+```
+
+**Server**: the browser talks to [grafeo-server](https://github.com/GrafeoDB/grafeo-server) over HTTP (`POST /query`, `GET /db/{name}/schema`). The server must allow the notebook's origin, for example `grafeo-server --cors-origins http://localhost:8888`.
+
+```python
+graph = Graph(database_backend="grafeo", grafeo_connection_mode="server", grafeo_server_url="http://localhost:7474")
+```
+
+**WASM**: the engine runs in the browser. `@grafeo-db/wasm` (0.5.44) is downloaded from jsDelivr when you click "Initialize WASM", so nothing extra is installed in Python.
+
+```python
+graph = Graph(database_backend="grafeo", grafeo_connection_mode="wasm", query_language="gql")
+```
+
+Query languages: GQL, Cypher, Gremlin, GraphQL and SPARQL. Nodes and edges are taken from every result column, including lists (`collect(n)`, variable-length relationships, `nodes(p)`) and paths (`RETURN p`); scalar columns are ignored. Run one statement per query: Grafeo rejects several `;`-separated statements in one call.
+
+Try it without any setup:
+
+```python
+from anywidget_graph.demo import demo_graph
+demo_graph()  # WASM mode with a small movie graph loaded
 ```
 
 ### Neo4j (browser-side)

{anywidget_graph-0.3.0 → anywidget_graph-0.4.0}/README.md

@@ -183,6 +183,29 @@ graph.unpin_all()                   # Unpin everything
 graph.clear()                   # Remove all nodes, edges, pins, and selection
 ```
 
+### Linked lanes and live append
+
+Show two graphs side by side in one canvas, each laid out in its own lane, with curved edges between them, and grow them while a process runs:
+
+```python
+graph = Graph(
+    lanes=[{"id": "source", "title": "Source graph"}, {"id": "target", "title": "Target graph"}],
+    nodes=[{"id": "a", "lane": "source"}, {"id": "b", "lane": "source"}, {"id": "x", "lane": "target"}],
+    edges=[{"source": "a", "target": "b"}, {"source": "x", "target": "a", "cross": True}],
+)
+graph.append(nodes=[{"id": "y", "lane": "target"}], edges=[{"source": "y", "target": "b"}])
+graph.pulse_nodes = ["b"]       # a soft pulse on these nodes; [] stops it
+graph.theme = {"background": "#0d1416", "panel": "#121b1e", "text": "#dbe7e5", "muted": "#8ea3a3", "border": "#1e2b2f", "accent": "#5bb8a9"}
+```
+
+- `lanes`: lanes left to right; a node's `lane` picks one (a node without a known lane goes to the first). Edges between lanes (or marked `cross`) are drawn as soft curves above both lanes and light up when either end is hovered or selected. Without `lanes` the widget behaves as before.
+- `append(nodes, edges)`: adds items without a re-layout; existing nodes keep their positions, a new node is placed at the height of its neighbours in other lanes (or next to its neighbours in its lane). New items fade in and edges draw from source to target, `append_stagger_ms` (default 60) apart; a large batch is kept under 1.5 s. `append_animation="none"` turns the animation off.
+- Lane options: `width` is a lane's share of the standard width (default 1); `arrange: "column"` stacks the lane's nodes in the middle of its band (for a few roots, such as repositories, whose edges then fan out into the next lane); `action: True` makes a lane without nodes that shows a glyph button (`glyph`: a list of colours drawn as stacked bars, `caption`: text under it). The camera frames all lanes, and the lanes stretch to the canvas's shape.
+- `lane_action`: set to `{"lane": <id>, "seq": <n>}` when an action lane's glyph is clicked, so the host can respond (open a panel, switch a view).
+- `pulse_nodes`: ids that pulse softly.
+- `theme`: host colours (`background`, `panel`, `text`, `muted`, `border`, `accent`) that replace the widget's light and dark defaults.
+- `_features`: the widget sets the capabilities it supports when it renders, so a host can detect an older build.
+
 ## Styling
 
 ### Property-based coloring
@@ -222,6 +245,7 @@ graph = Graph(
     edges=edges,
     width=800,                  # Widget width (px)
     height=600,                 # Widget height (px)
+    fill=False,                 # Take the host's size and follow resizes (ignores width/height)
     background="#fafafa",       # Background color
     show_labels=True,           # Node labels
     show_edge_labels=False,     # Edge labels
@@ -239,10 +263,35 @@ graph = Graph(
 
 ### Grafeo (default)
 
+Grafeo runs in one of three modes, picked with `grafeo_connection_mode` or in the settings panel.
+
+**Embedded** (Python, the default): queries run in the notebook kernel. Requires the `grafeo` extra (`grafeo>=0.5.44,<0.7`).
+
 ```python
 import grafeo
 db = grafeo.GrafeoDB()
-graph = Graph(database_backend="grafeo", grafeo_db=db)
+graph = Graph(database_backend="grafeo", grafeo_db=db, query_language="gql")
+```
+
+**Server**: the browser talks to [grafeo-server](https://github.com/GrafeoDB/grafeo-server) over HTTP (`POST /query`, `GET /db/{name}/schema`). The server must allow the notebook's origin, for example `grafeo-server --cors-origins http://localhost:8888`.
+
+```python
+graph = Graph(database_backend="grafeo", grafeo_connection_mode="server", grafeo_server_url="http://localhost:7474")
+```
+
+**WASM**: the engine runs in the browser. `@grafeo-db/wasm` (0.5.44) is downloaded from jsDelivr when you click "Initialize WASM", so nothing extra is installed in Python.
+
+```python
+graph = Graph(database_backend="grafeo", grafeo_connection_mode="wasm", query_language="gql")
+```
+
+Query languages: GQL, Cypher, Gremlin, GraphQL and SPARQL. Nodes and edges are taken from every result column, including lists (`collect(n)`, variable-length relationships, `nodes(p)`) and paths (`RETURN p`); scalar columns are ignored. Run one statement per query: Grafeo rejects several `;`-separated statements in one call.
+
+Try it without any setup:
+
+```python
+from anywidget_graph.demo import demo_graph
+demo_graph()  # WASM mode with a small movie graph loaded
 ```
 
 ### Neo4j (browser-side)

{anywidget_graph-0.3.0 → anywidget_graph-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "anywidget-graph"
-version = "0.3.0"
+version = "0.4.0"
 description = "Interactive graph visualization for Python notebooks using anywidget"
 readme = "README.md"
 license = "Apache-2.0"
@@ -35,10 +35,10 @@ dev = [
 ]
 networkx = ["networkx>=3.0"]
 pandas = ["pandas>=2.0"]
-grafeo = ["grafeo>=0.5"]
+grafeo = ["grafeo>=0.5.44,<0.7"]
 cosmosdb = ["gremlinpython>=3.7"]
-embed = []  # Marker extra — WASM loads from CDN on demand
-demo = []  # Marker extra — enables demo mode with pre-populated dataset
+embed = []  # Marker extra: WASM loads from CDN on demand
+demo = []  # Marker extra: enables demo mode with pre-populated dataset
 
 [project.urls]
 Homepage = "https://grafeo.dev/"
@@ -74,8 +74,9 @@ repos = [
     ]},
 ]
 
-[tool.uv]
-dev-dependencies = [
+[dependency-groups]
+dev = [
+    "anywidget-graph[grafeo]",  # Engine contract tests run against the pinned grafeo extra
     "pytest>=9.0.2",
     "ruff>=0.14.14",
 ]

{anywidget_graph-0.3.0 → anywidget_graph-0.4.0}/src/anywidget_graph/__init__.py

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

anywidget_graph-0.4.0/src/anywidget_graph/backends/grafeo.py

@@ -0,0 +1,274 @@
+"""Grafeo database backend (Python-side execution).
+
+Grafeo returns result rows as dicts. Entities are encoded as dicts with
+metadata keys, and that encoding is the contract this module depends on:
+
+- node: ``{"_id": int, "_labels": [str, ...], **properties}``
+- edge: ``{"_id": int, "_type": str, "_source": int, "_target": int, **properties}``
+- path: ``{"nodes": [int, ...], "edges": [int, ...]}`` (ids only)
+
+Entities can also sit inside lists (``collect(n)``, variable-length edge
+variables, ``nodes(p)``). Ids that are referenced but not returned as
+entities (path members, edge endpoints) are resolved with
+``db.get_node(id)`` / ``db.get_edge(id)``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, ClassVar
+
+from anywidget_graph.converters import (
+    get_node_id,
+    is_node,
+    is_relationship,
+    node_to_dict,
+    relationship_to_dict,
+)
+
+
+@dataclass(slots=True)
+class _GraphAccumulator:
+    """Nodes and edges collected from one result, plus ids still to resolve."""
+
+    nodes: dict[str, dict] = field(default_factory=dict)
+    edges: dict[Any, dict] = field(default_factory=dict)
+    grafeo_edge_keys: set[Any] = field(default_factory=set)
+    path_node_ids: set[int] = field(default_factory=set)
+    path_edge_ids: set[int] = field(default_factory=set)
+
+
+class GrafeoBackend:
+    """Backend for Grafeo database connections."""
+
+    _LANGUAGE_METHODS: ClassVar[dict[str, str]] = {
+        "cypher": "execute_cypher",
+        "gremlin": "execute_gremlin",
+        "graphql": "execute_graphql",
+        "sparql": "execute_sparql",
+        "sql": "execute_sql",
+    }
+
+    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, *, language: str = "cypher") -> tuple[list[dict], list[dict]]:
+        """Execute a query in the specified language and return (nodes, edges)."""
+        return self._process_result(self._run(query, language))
+
+    def _run(self, query: str, language: str) -> Any:
+        method_name = self._LANGUAGE_METHODS.get(language)
+        if method_name and hasattr(self._db, method_name):
+            return getattr(self._db, method_name)(query)
+        if method_name is None and language not in ("", "gql") and hasattr(self._db, "execute_language"):
+            # Lets the engine reject unsupported languages with a clear error
+            return self._db.execute_language(language, query)
+        return self._db.execute(query)
+
+    def fetch_schema(self) -> tuple[list[dict], list[dict]]:
+        """Fetch schema from Grafeo database.
+
+        ``db.schema()`` returns ``{"labels": [{"name", "count"}], "edge_types": [...]}``;
+        plain string entries are accepted as well.
+        """
+        if not hasattr(self._db, "schema"):
+            return [], []
+        schema = self._db.schema()
+        if not isinstance(schema, dict):
+            return [], []
+        node_types = [self._schema_entry(item, "label") for item in schema.get("labels") or []]
+        edge_types = [self._schema_entry(item, "type") for item in schema.get("edge_types") or []]
+        return node_types, edge_types
+
+    @staticmethod
+    def _schema_entry(item: Any, key: str) -> dict:
+        if isinstance(item, dict):
+            entry: dict = {key: str(item.get("name", "")), "properties": list(item.get("properties") or [])}
+            if isinstance(item.get("count"), int):
+                entry["count"] = item["count"]
+            return entry
+        return {key: str(item), "properties": []}
+
+    def _process_result(self, result: Any) -> tuple[list[dict], list[dict]]:
+        """Process query results into nodes and edges."""
+        acc = _GraphAccumulator()
+
+        records = list(result) if hasattr(result, "__iter__") else [result]
+        for record in records:
+            for _key, value in self._extract_items(record):
+                self._add_top_level(acc, value)
+
+        self._resolve_missing(acc)
+
+        edges = [
+            edge
+            for key, edge in acc.edges.items()
+            if key not in acc.grafeo_edge_keys or (edge["source"] in acc.nodes and edge["target"] in acc.nodes)
+        ]
+        return list(acc.nodes.values()), edges
+
+    def _add_top_level(self, acc: _GraphAccumulator, value: Any) -> None:
+        if self._add_grafeo_entity(acc, value):
+            return
+        # Values from other drivers or hand-built rows
+        if is_node(value):
+            node_id = get_node_id(value)
+            if node_id not in acc.nodes:
+                acc.nodes[node_id] = node_to_dict(value)
+        elif is_relationship(value):
+            acc.edges[("generic", len(acc.edges))] = relationship_to_dict(value)
+        else:
+            self._add_nested(acc, value)
+
+    def _add_value(self, acc: _GraphAccumulator, value: Any) -> None:
+        if not self._add_grafeo_entity(acc, value):
+            self._add_nested(acc, value)
+
+    def _add_nested(self, acc: _GraphAccumulator, value: Any) -> None:
+        """Search lists and plain maps for entities (collect, nodes(p), variable-length edges)."""
+        if isinstance(value, list | tuple):
+            for item in value:
+                self._add_value(acc, item)
+        elif isinstance(value, dict):
+            for item in value.values():
+                self._add_value(acc, item)
+
+    def _add_grafeo_entity(self, acc: _GraphAccumulator, value: Any) -> bool:
+        """Collect a Grafeo node, edge or path; return False for any other value."""
+        if self._is_grafeo_node(value):
+            node = self._grafeo_node_to_dict(value)
+            acc.nodes.setdefault(node["id"], node)
+            return True
+        if self._is_grafeo_relationship(value):
+            key = ("grafeo", value["_id"]) if "_id" in value else ("grafeo-anon", len(acc.edges))
+            if key not in acc.edges:
+                acc.edges[key] = self._grafeo_relationship_to_dict(value)
+                acc.grafeo_edge_keys.add(key)
+            return True
+        if self._is_grafeo_path(value):
+            for member, ids in ((value["nodes"], acc.path_node_ids), (value["edges"], acc.path_edge_ids)):
+                for item in member:
+                    if self._is_entity_id(item):
+                        ids.add(item)
+                    else:
+                        self._add_value(acc, item)
+            return True
+        return False
+
+    def _resolve_missing(self, acc: _GraphAccumulator) -> None:
+        """Look up path members and edge endpoints that were only returned as ids."""
+        get_edge = getattr(self._db, "get_edge", None)
+        if get_edge is not None:
+            for edge_id in sorted(acc.path_edge_ids):
+                if ("grafeo", edge_id) in acc.edges:
+                    continue
+                edge = get_edge(edge_id)
+                if edge is not None:
+                    self._add_grafeo_entity(acc, self._edge_object_to_raw(edge))
+
+        get_node = getattr(self._db, "get_node", None)
+        if get_node is None:
+            return
+        wanted = {str(node_id): node_id for node_id in acc.path_node_ids}
+        for key in acc.grafeo_edge_keys:
+            edge = acc.edges[key]
+            for endpoint in (edge["source"], edge["target"]):
+                if endpoint.isdigit():
+                    wanted.setdefault(endpoint, int(endpoint))
+        for node_key, node_id in sorted(wanted.items(), key=lambda item: item[1]):
+            if node_key in acc.nodes:
+                continue
+            node = get_node(node_id)
+            if node is not None:
+                self._add_grafeo_entity(acc, self._node_object_to_raw(node))
+
+    @staticmethod
+    def _is_entity_id(value: Any) -> bool:
+        return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+    @staticmethod
+    def _node_object_to_raw(node: Any) -> dict:
+        """Convert a ``grafeo.Node`` (from ``db.get_node``) to the row dict encoding."""
+        return {**node.properties(), "_id": node.id, "_labels": list(node.labels)}
+
+    @staticmethod
+    def _edge_object_to_raw(edge: Any) -> dict:
+        """Convert a ``grafeo.Edge`` (from ``db.get_edge``) to the row dict encoding."""
+        return {
+            **edge.properties(),
+            "_id": edge.id,
+            "_type": edge.edge_type,
+            "_source": edge.source_id,
+            "_target": edge.target_id,
+        }
+
+    @staticmethod
+    def _is_grafeo_node(obj: Any) -> bool:
+        """Check if a value is a Grafeo node dict (has ``_id`` and ``_labels``)."""
+        return isinstance(obj, dict) and "_id" in obj and "_labels" in obj
+
+    @staticmethod
+    def _is_grafeo_relationship(obj: Any) -> bool:
+        """Check if a value is a Grafeo relationship dict (has ``_source``, ``_target``, ``_type``)."""
+        return isinstance(obj, dict) and "_source" in obj and "_target" in obj and "_type" in obj
+
+    @staticmethod
+    def _is_grafeo_path(obj: Any) -> bool:
+        """Check if a value is a Grafeo path (``nodes`` and ``edges`` lists, no ``_id``)."""
+        return (
+            isinstance(obj, dict)
+            and "_id" not in obj
+            and isinstance(obj.get("nodes"), list)
+            and isinstance(obj.get("edges"), list)
+        )
+
+    @staticmethod
+    def _grafeo_node_to_dict(node: dict) -> dict:
+        """Convert a Grafeo node dict to the widget node format.
+
+        Properties are applied before ``id`` and ``labels`` so that a user
+        property called ``id`` cannot replace the node identity that edges
+        refer to.
+        """
+        labels = list(node.get("_labels") or [])
+        props = {key: value for key, value in node.items() if not key.startswith("_")}
+        result: dict = {}
+        if labels:
+            result["label"] = labels[0]
+        result.update(props)
+        result["id"] = str(node["_id"])
+        if labels:
+            result["labels"] = labels
+        if "label" not in result and "name" in result:
+            result["label"] = result["name"]
+        return result
+
+    @staticmethod
+    def _grafeo_relationship_to_dict(rel: dict) -> dict:
+        """Convert a Grafeo relationship dict to the widget edge format.
+
+        ``source`` and ``target`` always come from the engine, never from
+        properties with the same name.
+        """
+        result: dict = {"label": str(rel["_type"])}
+        result.update({key: value for key, value in rel.items() if not key.startswith("_")})
+        result["source"] = str(rel["_source"])
+        result["target"] = str(rel["_target"])
+        return result
+
+    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-0.3.0 → anywidget_graph-0.4.0}/src/anywidget_graph/demo.py

@@ -18,7 +18,7 @@ import json
 
 from anywidget_graph.widget import Graph
 
-# Classic movie/actor graph dataset — small enough to load instantly,
+# Classic movie/actor graph dataset, small enough to load instantly,
 # rich enough to demonstrate labels, relationships, and properties.
 DEMO_NODES = [
     {"id": "m1", "label": "The Matrix", "labels": ["Movie"], "year": 1999, "color": "#6366f1"},