Return the Python UndirectedGraph subclass from from_(unique_)edges

The core statics return the raw _core.UndirectedGraph, so results
lacked the subclass convenience wrappers (find_edges on lists, ...) and
failed isinstance checks against bic.graph.UndirectedGraph. Add a
constructor overload taking (number_of_nodes, uvs, unique) — an
__init__ overload constructs the derived Python class, unlike a static
— and build the subclass classmethods on it. from_edges also gains the
single-pass C++ construction instead of insert_edges.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: constantinpape

src/bindings/graph.cxx

@@ -1903,6 +1903,23 @@ void bind_graph(nb::module_ &m) {
             nb::arg("number_of_nodes") = 0,
             nb::arg("reserve_number_of_edges") = 0
         )
+        // Constructor equivalent of the from_edges / from_unique_edges
+        // statics. Unlike a def_static, an __init__ overload constructs an
+        // instance of the *derived* Python class, so the Python subclass in
+        // bioimage_cpp.graph can build itself from an edge array.
+        .def(
+            "__init__",
+            [](Graph *self, const std::uint64_t number_of_nodes, ConstUInt64Array uvs,
+               const bool unique) {
+                new (self) Graph(
+                    unique ? graph_from_unique_edges(number_of_nodes, uvs)
+                           : graph_from_edges(number_of_nodes, uvs)
+                );
+            },
+            nb::arg("number_of_nodes"),
+            nb::arg("uvs"),
+            nb::arg("unique")
+        )
         .def(
             "assign",
             &Graph::assign,

src/bioimage_cpp/graph/__init__.py

@@ -96,9 +96,19 @@ def edgesFromNodeList(self, nodes):
 
     @classmethod
     def from_edges(cls, number_of_nodes: int, uvs):
-        graph = cls(number_of_nodes)
-        graph.insert_edges(uvs)
-        return graph
+        return cls(int(number_of_nodes), _as_uv_array(uvs, "uvs"), False)
+
+    @classmethod
+    def from_unique_edges(cls, number_of_nodes: int, uvs):
+        """Bulk-construct from a pre-deduplicated ``(n, 2)`` edge array.
+
+        The caller asserts that no undirected ``(u, v)`` pair appears twice and
+        that ``u != v`` in every row; edges receive ids matching their position
+        in ``uvs``. This skips the per-edge dedup of :meth:`from_edges` and is
+        the fast path for e.g. the merged edge set of
+        :func:`bioimage_cpp.graph.distributed.merge_edges`.
+        """
+        return cls(int(number_of_nodes), _as_uv_array(uvs, "uvs"), True)
 
     @classmethod
     def deserialize(cls, serialization):

tests/graph/test_undirected_graph.py

@@ -155,3 +155,33 @@ def test_undirected_graph_freeze_is_callable_after_inserts_and_after_reads():
     np.testing.assert_array_equal(
         np.sort(graph.node_adjacency(0)[:, 0]), np.array([1, 2], dtype=np.uint64)
     )
+
+
+def test_from_edges_and_from_unique_edges_return_python_subclass():
+    uvs = np.array([[0, 1], [1, 2], [0, 2]], dtype=np.uint64)
+    core = bic._core.UndirectedGraph.from_unique_edges(3, uvs)
+
+    for graph in (
+        bic.graph.UndirectedGraph.from_unique_edges(3, uvs),
+        bic.graph.UndirectedGraph.from_edges(3, uvs),
+    ):
+        # The classmethods construct the Python subclass (the core statics
+        # return the raw _core type), so the convenience wrappers work.
+        assert isinstance(graph, bic.graph.UndirectedGraph)
+        assert graph.number_of_nodes == core.number_of_nodes
+        assert graph.number_of_edges == core.number_of_edges
+        np.testing.assert_array_equal(graph.uv_ids(), core.uv_ids())
+        np.testing.assert_array_equal(
+            graph.find_edges([[0, 1], [2, 0]]), np.array([0, 2], dtype=np.int64)
+        )
+
+
+def test_from_edges_deduplicates_but_from_unique_edges_requires_unique():
+    uvs_with_duplicate = np.array([[0, 1], [1, 0], [1, 2]], dtype=np.uint64)
+    graph = bic.graph.UndirectedGraph.from_edges(3, uvs_with_duplicate)
+    assert graph.number_of_edges == 2
+
+    with pytest.raises(ValueError):
+        bic.graph.UndirectedGraph.from_unique_edges(
+            3, np.array([[0, 0]], dtype=np.uint64)
+        )