networkx: (almost) complete the traversal algorithms module (#14628)

stubs/networkx/networkx/algorithms/traversal/beamsearch.pyi

@@ -1,4 +1,3 @@
-from _typeshed import Incomplete
 from collections.abc import Callable, Generator
 
 from networkx.classes.graph import Graph, _Node
@@ -8,5 +7,5 @@ __all__ = ["bfs_beam_edges"]
 
 @_dispatchable
 def bfs_beam_edges(
-    G: Graph[_Node], source: _Node, value: Callable[..., Incomplete], width: int | None = None
-) -> Generator[Incomplete, Incomplete, Incomplete]: ...
+    G: Graph[_Node], source: _Node, value: Callable[[_Node], float], width: int | None = None
+) -> Generator[tuple[_Node, _Node]]: ...

stubs/networkx/networkx/algorithms/traversal/breadth_first_search.pyi

@@ -1,7 +1,7 @@
-from _typeshed import Incomplete
-from collections.abc import Callable, Generator
-from typing import Literal
+from collections.abc import Callable, Generator, Iterable, Iterator
+from typing import Final, Literal
 
+from networkx.classes.digraph import DiGraph
 from networkx.classes.graph import Graph, _Node
 from networkx.utils.backends import _dispatchable
 
@@ -17,34 +17,50 @@ __all__ = [
 ]
 
 @_dispatchable
-def generic_bfs_edges(G, source, neighbors=None, depth_limit=None) -> Generator[tuple[Incomplete, Incomplete]]: ...
+def generic_bfs_edges(
+    G: Graph[_Node], source: _Node, neighbors: Callable[[_Node], Iterable[_Node]] | None = None, depth_limit: int | None = None
+) -> Generator[tuple[_Node, _Node]]: ...
 @_dispatchable
 def bfs_edges(
     G: Graph[_Node],
     source: _Node,
     reverse: bool | None = False,
-    depth_limit=None,
-    sort_neighbors: Callable[..., Incomplete] | None = None,
-) -> Generator[Incomplete, Incomplete, None]: ...
+    depth_limit: int | None = None,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> Generator[tuple[_Node, _Node]]: ...
 @_dispatchable
 def bfs_tree(
     G: Graph[_Node],
     source: _Node,
     reverse: bool | None = False,
-    depth_limit=None,
-    sort_neighbors: Callable[..., Incomplete] | None = None,
-): ...
+    depth_limit: int | None = None,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> DiGraph[_Node]: ...
 @_dispatchable
 def bfs_predecessors(
-    G: Graph[_Node], source: _Node, depth_limit=None, sort_neighbors: Callable[..., Incomplete] | None = None
-) -> Generator[Incomplete, None, None]: ...
+    G: Graph[_Node],
+    source: _Node,
+    depth_limit: int | None = None,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> Generator[tuple[_Node, _Node]]: ...
 @_dispatchable
 def bfs_successors(
-    G: Graph[_Node], source: _Node, depth_limit=None, sort_neighbors: Callable[..., Incomplete] | None = None
-) -> Generator[Incomplete, None, None]: ...
+    G: Graph[_Node],
+    source: _Node,
+    depth_limit: int | None = None,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> Generator[tuple[_Node, list[_Node]]]: ...
 @_dispatchable
-def bfs_layers(G: Graph[_Node], sources) -> Generator[Incomplete, None, None]: ...
+def bfs_layers(G: Graph[_Node], sources: _Node | Iterable[_Node]) -> Generator[list[_Node]]: ...
+
+REVERSE_EDGE: Final = "reverse"
+TREE_EDGE: Final = "tree"
+FORWARD_EDGE: Final = "forward"
+LEVEL_EDGE: Final = "level"
+
 @_dispatchable
-def bfs_labeled_edges(G, sources) -> Generator[tuple[Incomplete, Incomplete, Literal["tree", "level", "forward", "reverse"]]]: ...
+def bfs_labeled_edges(
+    G: Graph[_Node], sources: _Node | Iterable[_Node]
+) -> Generator[tuple[_Node, _Node, Literal["tree", "level", "forward", "reverse"]]]: ...
 @_dispatchable
-def descendants_at_distance(G: Graph[_Node], source, distance): ...
+def descendants_at_distance(G: Graph[_Node], source: _Node, distance: int) -> set[_Node]: ...

stubs/networkx/networkx/algorithms/traversal/depth_first_search.pyi

@@ -1,6 +1,7 @@
-from _typeshed import Incomplete
-from collections.abc import Callable, Generator
+from collections.abc import Callable, Generator, Iterable, Iterator
+from typing import Literal
 
+from networkx.classes.digraph import DiGraph
 from networkx.classes.graph import Graph, _Node
 from networkx.utils.backends import _dispatchable
 
@@ -16,29 +17,57 @@ __all__ = [
 
 @_dispatchable
 def dfs_edges(
-    G: Graph[_Node], source: _Node | None = None, depth_limit=None, *, sort_neighbors: Callable[..., Incomplete] | None = None
-) -> Generator[tuple[_Node, _Node], None, None]: ...
+    G: Graph[_Node],
+    source: _Node | None = None,
+    depth_limit: int | None = None,
+    *,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> Generator[tuple[_Node, _Node]]: ...
 @_dispatchable
 def dfs_tree(
-    G: Graph[_Node], source: _Node | None = None, depth_limit=None, *, sort_neighbors: Callable[..., Incomplete] | None = None
-): ...
+    G: Graph[_Node],
+    source: _Node | None = None,
+    depth_limit: int | None = None,
+    *,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> DiGraph[_Node]: ...
 @_dispatchable
 def dfs_predecessors(
-    G: Graph[_Node], source: _Node | None = None, depth_limit=None, *, sort_neighbors: Callable[..., Incomplete] | None = None
-) -> dict[Incomplete, Incomplete]: ...
+    G: Graph[_Node],
+    source: _Node | None = None,
+    depth_limit: int | None = None,
+    *,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> dict[_Node, _Node]: ...
 @_dispatchable
 def dfs_successors(
-    G: Graph[_Node], source: _Node | None = None, depth_limit=None, *, sort_neighbors: Callable[..., Incomplete] | None = None
-) -> dict[Incomplete, list[Incomplete]]: ...
+    G: Graph[_Node],
+    source: _Node | None = None,
+    depth_limit: int | None = None,
+    *,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> dict[_Node, list[_Node]]: ...
 @_dispatchable
 def dfs_postorder_nodes(
-    G: Graph[_Node], source: _Node | None = None, depth_limit=None, *, sort_neighbors: Callable[..., Incomplete] | None = None
-): ...
+    G: Graph[_Node],
+    source: _Node | None = None,
+    depth_limit: int | None = None,
+    *,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> Generator[_Node]: ...
 @_dispatchable
 def dfs_preorder_nodes(
-    G: Graph[_Node], source: _Node | None = None, depth_limit=None, *, sort_neighbors: Callable[..., Incomplete] | None = None
-): ...
+    G: Graph[_Node],
+    source: _Node | None = None,
+    depth_limit: int | None = None,
+    *,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> Generator[_Node]: ...
 @_dispatchable
 def dfs_labeled_edges(
-    G: Graph[_Node], source: _Node | None = None, depth_limit=None, *, sort_neighbors: Callable[..., Incomplete] | None = None
-) -> None: ...
+    G: Graph[_Node],
+    source: _Node | None = None,
+    depth_limit: int | None = None,
+    *,
+    sort_neighbors: Callable[[Iterator[_Node]], Iterable[_Node]] | None = None,
+) -> Generator[tuple[_Node, _Node, Literal["forward", "nontree", "reverse", "reverse-depth_limit"]]]: ...

stubs/networkx/networkx/algorithms/traversal/edgebfs.pyi

@@ -1,6 +1,6 @@
 from _typeshed import Incomplete
-from collections.abc import Generator
-from typing import Final
+from collections.abc import Generator, Iterable
+from typing import Final, Literal
 
 from networkx.classes.graph import Graph, _Node
 from networkx.utils.backends import _dispatchable
@@ -11,4 +11,8 @@ FORWARD: Final = "forward"
 REVERSE: Final = "reverse"
 
 @_dispatchable
-def edge_bfs(G: Graph[_Node], source=None, orientation=None) -> Generator[Incomplete, None, None]: ...
+def edge_bfs(
+    G: Graph[_Node],
+    source: _Node | Iterable[_Node] | None = None,
+    orientation: Literal["original", "reverse", "ignore"] | None = None,
+) -> Generator[tuple[Incomplete, ...]]: ...

stubs/networkx/networkx/algorithms/traversal/edgedfs.pyi

@@ -1,6 +1,6 @@
 from _typeshed import Incomplete
-from collections.abc import Generator
-from typing import Final
+from collections.abc import Generator, Iterable
+from typing import Final, Literal
 
 from networkx.classes.graph import Graph, _Node
 from networkx.utils.backends import _dispatchable
@@ -11,4 +11,8 @@ FORWARD: Final = "forward"
 REVERSE: Final = "reverse"
 
 @_dispatchable
-def edge_dfs(G: Graph[_Node], source=None, orientation=None) -> Generator[Incomplete, None, None]: ...
+def edge_dfs(
+    G: Graph[_Node],
+    source: _Node | Iterable[_Node] | None = None,
+    orientation: Literal["original", "reverse", "ignore"] | None = None,
+) -> Generator[tuple[Incomplete, ...]]: ...