Add to_dict() method for StrictMultiDiGraph and corresponding tests for serialization

Author: networmix

docs/reference/api-full.md

@@ -10,7 +10,7 @@ For a curated, example-driven API guide, see **[api.md](api.md)**.
 > - **[CLI Reference](cli.md)** - Command-line interface
 > - **[DSL Reference](dsl.md)** - YAML syntax guide
 
-**Generated from source code on:** June 13, 2025 at 17:50 UTC
+**Generated from source code on:** June 13, 2025 at 18:47 UTC
 
 **Modules auto-discovered:** 39
 
@@ -1138,6 +1138,8 @@ Inherits from:
   - Returns a SubGraph view of the subgraph induced on `nodes`.
 - `successors(self, n)`
   - Returns an iterator over successor nodes of n.
+- `to_dict(self) -> 'Dict[str, Any]'`
+  - Convert the graph to a dictionary representation suitable for JSON serialization.
 - `to_directed(self, as_view=False)`
   - Returns a directed representation of the graph.
 - `to_directed_class(self)`

ngraph/lib/graph.py

@@ -298,3 +298,17 @@ def update_edge_attr(self, key: EdgeID, **attr: Any) -> None:
         if key not in self._edges:
             raise ValueError(f"Edge with id='{key}' not found.")
         self._edges[key][3].update(attr)
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert the graph to a dictionary representation suitable for JSON serialization.
+
+        Returns a node-link format dictionary with graph attributes, nodes, and edges.
+        The format is compatible with visualization libraries like D3.js.
+
+        Returns:
+            Dict[str, Any]: Dictionary containing 'graph', 'nodes', and 'links' keys.
+        """
+        # Import here to avoid circular import
+        from ngraph.lib.io import graph_to_node_link
+
+        return graph_to_node_link(self)

tests/lib/test_graph.py

@@ -380,3 +380,110 @@ def test_networkx_algorithm():
     )
     # Expect two equally short paths: A->B->C (10+4=14) and A->BB->C (10+4=14)
     assert sorted(all_sp) == sorted([["A", "B", "C"], ["A", "BB", "C"]])
+
+
+def test_to_dict():
+    """Test that to_dict() returns proper node-link format for JSON serialization."""
+    g = StrictMultiDiGraph()
+
+    # Test empty graph
+    result = g.to_dict()
+    assert result == {"graph": {}, "nodes": [], "links": []}
+
+    # Add nodes with attributes
+    g.add_node("A", type="router", location="rack1")
+    g.add_node("B", type="switch", location="rack2")
+    g.add_node("C", type="server")
+
+    # Add edges with attributes
+    e1 = g.add_edge("A", "B", capacity=100, cost=5)
+    e2 = g.add_edge("B", "C", capacity=50, cost=2)
+    e3 = g.add_edge("A", "C", capacity=25)  # No cost attribute
+
+    result = g.to_dict()
+
+    # Verify structure
+    assert "graph" in result
+    assert "nodes" in result
+    assert "links" in result
+
+    # Verify graph attributes (should be empty for this test)
+    assert result["graph"] == {}
+
+    # Verify nodes
+    assert len(result["nodes"]) == 3
+    node_ids = [node["id"] for node in result["nodes"]]
+    assert set(node_ids) == {"A", "B", "C"}
+
+    # Find specific nodes and verify their attributes
+    node_a = next(n for n in result["nodes"] if n["id"] == "A")
+    assert node_a["attr"] == {"type": "router", "location": "rack1"}
+
+    node_b = next(n for n in result["nodes"] if n["id"] == "B")
+    assert node_b["attr"] == {"type": "switch", "location": "rack2"}
+
+    node_c = next(n for n in result["nodes"] if n["id"] == "C")
+    assert node_c["attr"] == {"type": "server"}
+
+    # Verify edges
+    assert len(result["links"]) == 3
+
+    # Create a mapping from node ID to index for edge verification
+    node_indices = {node["id"]: i for i, node in enumerate(result["nodes"])}
+
+    # Find specific edges by their keys and verify attributes
+    edge_by_key = {link["key"]: link for link in result["links"]}
+
+    assert e1 in edge_by_key
+    e1_link = edge_by_key[e1]
+    assert e1_link["source"] == node_indices["A"]
+    assert e1_link["target"] == node_indices["B"]
+    assert e1_link["attr"] == {"capacity": 100, "cost": 5}
+
+    assert e2 in edge_by_key
+    e2_link = edge_by_key[e2]
+    assert e2_link["source"] == node_indices["B"]
+    assert e2_link["target"] == node_indices["C"]
+    assert e2_link["attr"] == {"capacity": 50, "cost": 2}
+
+    assert e3 in edge_by_key
+    e3_link = edge_by_key[e3]
+    assert e3_link["source"] == node_indices["A"]
+    assert e3_link["target"] == node_indices["C"]
+    assert e3_link["attr"] == {"capacity": 25}
+
+
+def test_to_dict_with_graph_attributes():
+    """Test to_dict() with graph-level attributes."""
+    g = StrictMultiDiGraph(name="test_network", version="1.0")
+    g.add_node("A")
+    g.add_node("B")
+    g.add_edge("A", "B")
+
+    result = g.to_dict()
+
+    # Verify graph attributes are included
+    assert result["graph"]["name"] == "test_network"
+    assert result["graph"]["version"] == "1.0"
+    assert len(result["nodes"]) == 2
+    assert len(result["links"]) == 1
+
+
+def test_to_dict_json_serializable():
+    """Test that to_dict() output is JSON serializable."""
+    import json
+
+    g = StrictMultiDiGraph()
+    g.add_node("A", value=42, active=True)
+    g.add_node("B", value=3.14, tags=["tag1", "tag2"])
+    g.add_edge("A", "B", weight=1.5, metadata={"created": "2025-06-13"})
+
+    result = g.to_dict()
+
+    # Should be able to serialize to JSON without errors
+    json_str = json.dumps(result)
+
+    # Should be able to round-trip
+    parsed = json.loads(json_str)
+    assert parsed["nodes"][0]["attr"]["value"] in [42, 3.14]  # Could be in any order
+    assert len(parsed["links"]) == 1

tests/test_results_serialisation.py

@@ -340,3 +340,64 @@ def test_results_complex_nested_structures():
         )
     except TypeError:
         pass  # Expected - nested objects in dict don't get auto-converted
+
+
+def test_results_strict_multi_di_graph_serialization():
+    """Test that Results.to_dict() properly converts StrictMultiDiGraph objects."""
+    from ngraph.lib.graph import StrictMultiDiGraph
+
+    res = Results()
+
+    # Create a test graph
+    graph = StrictMultiDiGraph()
+    graph.add_node("A", type="router", location="datacenter1")
+    graph.add_node("B", type="switch", location="datacenter2")
+    edge_id = graph.add_edge("A", "B", capacity=100, cost=5)
+
+    # Store graph in results
+    res.put("build_graph", "graph", graph)
+    res.put("build_graph", "node_count", 2)
+
+    # Convert to dict
+    d = res.to_dict()
+
+    # Verify structure
+    assert "build_graph" in d
+    assert "graph" in d["build_graph"]
+    assert "node_count" in d["build_graph"]
+
+    # Verify the graph was converted to node-link format
+    graph_dict = d["build_graph"]["graph"]
+    assert isinstance(graph_dict, dict)
+    assert "nodes" in graph_dict
+    assert "links" in graph_dict
+    assert "graph" in graph_dict
+
+    # Verify nodes
+    assert len(graph_dict["nodes"]) == 2
+    node_ids = [node["id"] for node in graph_dict["nodes"]]
+    assert set(node_ids) == {"A", "B"}
+
+    # Find node A and verify its attributes
+    node_a = next(n for n in graph_dict["nodes"] if n["id"] == "A")
+    assert node_a["attr"]["type"] == "router"
+    assert node_a["attr"]["location"] == "datacenter1"
+
+    # Verify edges
+    assert len(graph_dict["links"]) == 1
+    edge = graph_dict["links"][0]
+    assert edge["key"] == edge_id
+    assert edge["attr"]["capacity"] == 100
+    assert edge["attr"]["cost"] == 5
+
+    # Verify scalar value is unchanged
+    assert d["build_graph"]["node_count"] == 2
+
+    # Verify the result is JSON serializable
+    json_str = json.dumps(d)
+
+    # Verify round-trip
+    parsed = json.loads(json_str)
+    assert parsed["build_graph"]["node_count"] == 2
+    assert len(parsed["build_graph"]["graph"]["nodes"]) == 2
+    assert len(parsed["build_graph"]["graph"]["links"]) == 1