Enhance docs and tests for pred/succ/anc/desc (#1405)

* Enhance docs and tests for pred/succ/anc/desc

* Use match pattern in predecessors/successors

Author: eumiro

src/digraph.rs

@@ -21,6 +21,7 @@ use std::io::prelude::*;
 use std::io::{BufReader, BufWriter};
 use std::str;
 
+use hashbrown::hash_set::Entry;
 use hashbrown::{HashMap, HashSet};
 
 use rustworkx_core::dictmap::*;
@@ -644,13 +645,18 @@ impl PyDiGraph {
     ///     >>> G.extend_from_edge_list([(0, 1), (1, 2), (1, 3), (1, 4)])
     ///     >>> G.successors(1)  # successors of the 'B' node
     ///     ['E', 'D', 'C']
+    ///     >>> G.successors(10) # successors of an non-existing node
+    ///     []
     ///
-    /// To filter the successors by the attributes of the connecting edge,
-    /// see :func:`~find_successors_by_edge`.
+    /// .. seealso ::
+    ///   To filter the successors by the attributes of the connecting edge,
+    ///   see :func:`~find_successors_by_edge`.
     ///
-    /// See also :func:`~predecessors` and :func:`~neighbors`.
+    ///   See also :func:`~predecessors` and :func:`~neighbors`.
     ///
-    /// For undirected graphs, see :func:`~PyGraph.neighbors`.
+    ///   For undirected graphs, see :func:`~PyGraph.neighbors`.
+    ///
+    ///   To go beyond the nearest successors, see :func:`~rustworkx.descendants`.
     ///
     /// :param int node: The index of the node to get the predecessors for
     ///
@@ -665,8 +671,12 @@ impl PyDiGraph {
         let mut successors: Vec<&PyObject> = Vec::new();
         let mut used_indices: HashSet<NodeIndex> = HashSet::new();
         for succ in children {
-            if used_indices.insert(succ) {
-                successors.push(self.graph.node_weight(succ).unwrap());
+            match used_indices.entry(succ) {
+                Entry::Vacant(used_indices_entry) => {
+                    used_indices_entry.insert();
+                    successors.push(self.graph.node_weight(succ).unwrap());
+                }
+                Entry::Occupied(_) => {}
             }
         }
         successors
@@ -684,13 +694,18 @@ impl PyDiGraph {
     ///     >>> G.extend_from_edge_list([(0, 3), (1, 3), (2, 3), (3, 4)])
     ///     >>> G.predecessors(3)  # predecessors of the 'D' node
     ///     ['C', 'B', 'A']
+    ///     >>> G.predecessors(10) # predecessors of an non-existing node
+    ///     []
     ///
-    /// To filter the predecessors by the attributes of the connecting edge,
-    /// see :func:`~find_predecessors_by_edge`.
+    /// .. seealso ::
+    ///   To filter the predecessors by the attributes of the connecting edge,
+    ///   see :func:`~find_predecessors_by_edge`.
     ///
-    /// See also :func:`~successors`.
+    ///   See also :func:`~successors`.
     ///
-    /// For undirected graphs, see :func:`~PyGraph.neighbors`.
+    ///   For undirected graphs, see :func:`~PyGraph.neighbors`.
+    ///
+    ///   To get beyond the nearest predecessors, see :func:`~rustworkx.ancestors`.
     ///
     /// :param int node: The index of the node to get the predecessors for
     ///
@@ -705,9 +720,12 @@ impl PyDiGraph {
         let mut predec: Vec<&PyObject> = Vec::new();
         let mut used_indices: HashSet<NodeIndex> = HashSet::new();
         for pred in parents {
-            if !used_indices.contains(&pred) {
-                predec.push(self.graph.node_weight(pred).unwrap());
-                used_indices.insert(pred);
+            match used_indices.entry(pred) {
+                Entry::Vacant(used_indices_entry) => {
+                    used_indices_entry.insert();
+                    predec.push(self.graph.node_weight(pred).unwrap());
+                }
+                Entry::Occupied(_) => {}
             }
         }
         predec

src/traversal/mod.rs

@@ -222,18 +222,33 @@ pub fn bfs_predecessors(
     }
 }
 
-/// Return the ancestors of a node in a graph.
+/// Retrieve all ancestors of a specified node in a directed graph.
 ///
-/// This differs from :meth:`PyDiGraph.predecessors` method  in that
-/// ``predecessors`` returns only nodes with a direct edge into the provided
-/// node. While this function returns all nodes that have a path into the
-/// provided node.
+/// This function differs from the :meth:`PyDiGraph.predecessors` method,
+/// which only returns nodes that have a direct edge leading to the specified
+/// node. In contrast, this function returns all nodes that have a path
+/// leading to the specified node, regardless of the number of edges in
+/// between.
 ///
-/// :param PyDiGraph graph: The graph to get the ancestors from.
-/// :param int node: The index of the graph node to get the ancestors for
+///     >>> G = rx.PyDiGraph()
+///     >>> G.add_nodes_from(range(5))
+///     NodeIndices[0, 1, 2, 3, 4]
+///     >>> G.add_edges_from_no_data([(0, 2), (1, 2), (2, 3), (3, 4)])
+///     [0, 1, 2, 3]
+///     >>> rx.ancestors(G, 3)
+///     {0, 1, 2}
 ///
-/// :returns: A set of node indices of ancestors of provided node.
-/// :rtype: set
+/// .. seealso ::
+///   See also :func:`~predecessors`.
+///
+/// :param PyDiGraph graph: The directed graph from which to retrieve ancestors.
+/// :param int node: The index of the node for which to find ancestors.
+///
+/// :returns: A set containing the indices of all ancestor nodes of the
+///          specified node.
+/// :rtype: set[int]
+///
+/// :raises IndexError: If the specified node is not present in the directed graph.
 #[pyfunction]
 #[pyo3(text_signature = "(graph, node, /)")]
 pub fn ancestors(graph: &digraph::PyDiGraph, node: usize) -> PyResult<HashSet<usize>> {
@@ -250,18 +265,33 @@ pub fn ancestors(graph: &digraph::PyDiGraph, node: usize) -> PyResult<HashSet<us
         .collect())
 }
 
-/// Return the descendants of a node in a graph.
+/// Retrieve all descendants of a specified node in a directed graph.
+///
+/// This function differs from the :meth:`PyDiGraph.successors` method,
+/// which only returns nodes that have a direct edge leading from the specified
+/// node. In contrast, this function returns all nodes that have a path
+/// leading from the specified node, regardless of the number of edges in
+/// between.
+///
+///     >>> G = rx.PyDiGraph()
+///     >>> G.add_nodes_from(range(5))
+///     NodeIndices[0, 1, 2, 3, 4]
+///     >>> G.add_edges_from_no_data([(0, 1), (1, 2), (2, 3), (2, 4)])
+///     [0, 1, 2, 3]
+///     >>> rx.descendants(G, 1)
+///     {2, 3, 4}
+///
+/// .. seealso ::
+///   See also :func:`~ancestors`.
 ///
-/// This differs from :meth:`PyDiGraph.successors` method in that
-/// ``successors``` returns only nodes with a direct edge out of the provided
-/// node. While this function returns all nodes that have a path from the
-/// provided node.
+/// :param PyDiGraph graph: The directed graph from which to retrieve descendants.
+/// :param int node: The index of the node for which to find descendants.
 ///
-/// :param PyDiGraph graph: The graph to get the descendants from
-/// :param int node: The index of the graph node to get the descendants for
+/// :returns: A set containing the indices of all descendant nodes of the
+///          specified node.
+/// :rtype: set[int]
 ///
-/// :returns: A set of node indices of descendants of provided node.
-/// :rtype: set
+/// :raises IndexError: If the specified node is not present in the directed graph.
 #[pyfunction]
 #[pyo3(text_signature = "(graph, node, /)")]
 pub fn descendants(graph: &digraph::PyDiGraph, node: usize) -> PyResult<HashSet<usize>> {

tests/digraph/test_pred_succ.py

@@ -55,6 +55,13 @@ def test_many_parents(self):
             res,
         )
 
+    def test_missing_node_has_no_predecessors(self):
+        G = rustworkx.PyDiGraph()
+        G.add_nodes_from(range(5))
+        G.add_edges_from_no_data([(0, 1), (2, 3)])
+        res = G.predecessors(10)
+        self.assertEqual([], res)
+
 
 class TestSuccessors(unittest.TestCase):
     def test_single_successor(self):
@@ -98,6 +105,13 @@ def test_many_children(self):
             res,
         )
 
+    def test_missing_node_has_no_successors(self):
+        G = rustworkx.PyDiGraph()
+        G.add_nodes_from(range(5))
+        G.add_edges_from_no_data([(0, 1), (2, 3)])
+        res = G.successors(10)
+        self.assertEqual([], res)
+
 
 class TestFindPredecessorsByEdge(unittest.TestCase):
     def test_single_predecessor(self):