Add graph module, port contract_nodes and has_parallel_edges to core. (#1143)

* Port contract_nodes to core.

* Explicit implementations for just StableGraph and GraphMap.

* Simplify to just graph_ext.

* Rename integration tests to graph_ext.

* Add module docs for graph_ext.

* Avoid 'static requirement for GraphMap extensions.

* Improve docs.

* Remove dead code.

* Add release note.

* Update releasenotes/notes/graph-ext-3f008015c31c592e.yaml

---------

Co-authored-by: Matthew Treinish <[email protected]>
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

Author: 3 people

releasenotes/notes/graph-ext-3f008015c31c592e.yaml

@@ -0,0 +1,17 @@
+---
+features:
+  - |
+    Node contraction is now supported for ``petgraph`` types ``StableGraph``
+    and ``GraphMap`` in rustworkx-core. To use it, import one of the ``ContractNodes*`` traits
+    from ``graph_ext`` and call the ``contract_nodes`` method on your graph.
+  - |
+    All current ``petgraph`` data structures now support testing for parallel
+    edges in ``rustworkx-core``. To use this, import ``HasParallelEdgesDirected``
+    or ``HasParallelEdgesUndirected`` depending on your graph type, and call
+    the ``has_parallel_edges`` method on your graph.
+  - |
+    A new trait ``NodeRemovable`` has been added to ``graph_ext`` module in
+    ``rustworkx-core`` which provides a consistent interface for performing
+    node removal operations on ``petgraph`` types ``Graph``, ``StableGraph``,
+    ``GraphMap``, and ``MatrixGraph``. To use it, import ``NodeRemovable`` from
+    ``graph_ext``.

rustworkx-core/src/err.rs

@@ -0,0 +1,56 @@
+// Licensed under the Apache License, Version 2.0 (the "License"); you may
+// not use this file except in compliance with the License. You may obtain
+// a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+// License for the specific language governing permissions and limitations
+// under the License.
+
+//! This module contains common error types and trait impls.
+
+use std::error::Error;
+use std::fmt::{Debug, Display, Formatter};
+
+#[derive(Debug)]
+pub enum ContractError {
+    DAGWouldCycle,
+}
+
+impl Display for ContractError {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ContractError::DAGWouldCycle => fmt_dag_would_cycle(f),
+        }
+    }
+}
+
+impl Error for ContractError {}
+
+#[derive(Debug)]
+pub enum ContractSimpleError<E: Error> {
+    DAGWouldCycle,
+    MergeError(E),
+}
+
+impl<E: Error> Display for ContractSimpleError<E> {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ContractSimpleError::DAGWouldCycle => fmt_dag_would_cycle(f),
+            ContractSimpleError::MergeError(ref e) => fmt_merge_error(f, e),
+        }
+    }
+}
+
+impl<E: Error> Error for ContractSimpleError<E> {}
+
+fn fmt_dag_would_cycle(f: &mut Formatter<'_>) -> std::fmt::Result {
+    write!(f, "The operation would introduce a cycle.")
+}
+
+fn fmt_merge_error<E: Error>(f: &mut Formatter<'_>, inner: &E) -> std::fmt::Result {
+    write!(f, "The prov failed with: {:?}", inner)
+}