networkx: complete the astar and generic modules in shortest_paths

stubs/networkx/@tests/stubtest_allowlist.txt

@@ -4,7 +4,6 @@
 networkx\.(algorithms\.)?(boundary\.)?edge_boundary
 networkx\.(algorithms\.)?(bridges\.)?local_bridges
 networkx\.(algorithms\.)?(clique\.)?node_clique_number
-networkx\.(algorithms\.)?(shortest_paths\.)?(generic\.)?shortest_path
 networkx\.(convert_matrix\.)?from_numpy_array
 networkx\.(convert_matrix\.)?from_pandas_adjacency
 networkx\.(convert_matrix\.)?from_pandas_edgelist

stubs/networkx/networkx/algorithms/shortest_paths/astar.pyi

@@ -1,7 +1,6 @@
-from _typeshed import Incomplete, SupportsGetItem
 from collections.abc import Callable
-from typing import Any
 
+from networkx.algorithms.shortest_paths.weighted import _WeightFunc
 from networkx.classes.graph import Graph, _Node
 from networkx.utils.backends import _dispatchable
 
@@ -12,18 +11,18 @@ def astar_path(
     G: Graph[_Node],
     source: _Node,
     target: _Node,
-    heuristic: Callable[..., Incomplete] | None = None,
-    weight: str | Callable[[Any, Any, SupportsGetItem[str, Any]], float | None] | None = "weight",
+    heuristic: Callable[[_Node, _Node], float] | None = None,
+    weight: str | _WeightFunc[_Node] | None = "weight",
     *,
     cutoff: float | None = None,
-): ...
+) -> list[_Node]: ...
 @_dispatchable
 def astar_path_length(
     G: Graph[_Node],
     source: _Node,
     target: _Node,
-    heuristic: Callable[..., Incomplete] | None = None,
-    weight: str | Callable[[Any, Any, SupportsGetItem[str, Any]], float | None] | None = "weight",
+    heuristic: Callable[[_Node, _Node], float] | None = None,
+    weight: str | _WeightFunc[_Node] | None = "weight",
     *,
     cutoff: float | None = None,
-): ...
+) -> float: ...

stubs/networkx/networkx/algorithms/shortest_paths/generic.pyi

@@ -1,7 +1,7 @@
-from _typeshed import Incomplete
-from collections.abc import Callable, Generator
+from collections.abc import Generator
 from typing import overload
 
+from networkx.algorithms.shortest_paths.weighted import _WeightFunc
 from networkx.classes.graph import Graph, _Node
 from networkx.utils.backends import _dispatchable
 
@@ -17,55 +17,129 @@ __all__ = [
 
 @_dispatchable
 def has_path(G: Graph[_Node], source: _Node, target: _Node) -> bool: ...
-@overload
+@overload  # both source and target are specified => (s -> t)
 def shortest_path(
     G: Graph[_Node],
-    source: _Node | None = None,
-    target: _Node | None = None,
-    weight: str | Callable[..., Incomplete] | None = None,
+    source: _Node,
+    target: _Node,
+    weight: str | _WeightFunc[_Node] | None = None,
     method: str | None = "dijkstra",
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
 ) -> list[_Node]: ...
-@overload
+@overload  # only source is specified => {t1: (s -> t), t2: (s -> t), ...}
 def shortest_path(
     G: Graph[_Node],
-    source: _Node | None = None,
-    target: _Node | None = None,
-    weight: str | Callable[..., Incomplete] | None = None,
+    source: _Node,
+    target: None = None,
+    weight: str | _WeightFunc[_Node] | None = None,
     method: str | None = "dijkstra",
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
 ) -> dict[_Node, list[_Node]]: ...
-@overload
+@overload  # only target is specified (positional) => {s1: (s1 -> t), s2: (s2 -> t), ...}
 def shortest_path(
     G: Graph[_Node],
-    source: _Node | None = None,
-    target: _Node | None = None,
-    weight: str | Callable[..., Incomplete] | None = None,
+    source: None,
+    target: _Node,
+    weight: str | _WeightFunc[_Node] | None = None,
     method: str | None = "dijkstra",
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
 ) -> dict[_Node, list[_Node]]: ...
-@_dispatchable
+@overload  # only target is specified (keyword) => {s1: (s1 -> t), s2: (s2 -> t), ...}
+def shortest_path(
+    G: Graph[_Node],
+    source: None = None,
+    *,
+    target: _Node,
+    weight: str | _WeightFunc[_Node] | None = None,
+    method: str | None = "dijkstra",
+    backend: str | None = None,
+    **backend_kwargs,
+) -> dict[_Node, list[_Node]]: ...
+@overload
+def shortest_path(  # source and target are not specified => generator of (t, {s1: (s1 -> t), s2: (s2 -> t), ...})
+    G: Graph[_Node],
+    source: None = None,
+    target: None = None,
+    weight: str | _WeightFunc[_Node] | None = None,
+    method: str | None = "dijkstra",
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
+) -> Generator[tuple[_Node, dict[str, list[_Node]]]]: ...
+@overload  # both source and target are specified => len(s -> t)
 def shortest_path_length(
     G: Graph[_Node],
-    source: _Node | None = None,
-    target: _Node | None = None,
-    weight: str | Callable[..., Incomplete] | None = None,
+    source: _Node,
+    target: _Node,
+    weight: str | _WeightFunc[_Node] | None = None,
     method: str | None = "dijkstra",
-): ...
-@_dispatchable
-def average_shortest_path_length(
-    G: Graph[_Node], weight: str | Callable[..., Incomplete] | None = None, method: str | None = None
-): ...
-@_dispatchable
-def all_shortest_paths(
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
+) -> float: ...
+@overload  # only source is specified => {t1: len(s -> t1), t2: len(s -> t2), ...}
+def shortest_path_length(
     G: Graph[_Node],
     source: _Node,
+    target: None = None,
+    weight: str | _WeightFunc[_Node] | None = None,
+    method: str | None = "dijkstra",
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
+) -> dict[_Node, float]: ...
+@overload  # only target is specified (positional) => {s1: len(s1 -> t), s2: len(s2 -> t), ...}
+def shortest_path_length(
+    G: Graph[_Node],
+    source: None,
+    target: _Node,
+    weight: str | _WeightFunc[_Node] | None = None,
+    method: str | None = "dijkstra",
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
+) -> dict[_Node, float]: ...
+@overload  # only target is specified (keyword) => {s1: len(s1 -> t), s2: len(s2 -> t), ...}
+def shortest_path_length(
+    G: Graph[_Node],
+    source: None = None,
+    *,
     target: _Node,
-    weight: str | Callable[..., Incomplete] | None = None,
+    weight: str | _WeightFunc[_Node] | None = None,
+    method: str | None = "dijkstra",
+    backend: str | None = None,
+    **backend_kwargs,
+) -> dict[_Node, float]: ...
+@overload
+def shortest_path_length(  # source and target are not specified => generator of (t, {s1: len(s1 -> t), s2: len(s2 -> t), ...})
+    G: Graph[_Node],
+    source: None = None,
+    target: None = None,
+    weight: str | _WeightFunc[_Node] | None = None,
     method: str | None = "dijkstra",
-) -> Generator[list[_Node], None, None]: ...
+    *,
+    backend: str | None = None,
+    **backend_kwargs,
+) -> Generator[tuple[_Node, dict[_Node, float]]]: ...
+@_dispatchable
+def average_shortest_path_length(
+    G: Graph[_Node], weight: str | _WeightFunc[_Node] | None = None, method: str | None = None
+) -> float: ...
+@_dispatchable
+def all_shortest_paths(
+    G: Graph[_Node], source: _Node, target: _Node, weight: str | _WeightFunc[_Node] | None = None, method: str | None = "dijkstra"
+) -> Generator[list[_Node]]: ...
 @_dispatchable
 def single_source_all_shortest_paths(
-    G, source, weight=None, method="dijkstra"
-) -> Generator[tuple[Incomplete, list[list[Incomplete]]]]: ...
+    G: Graph[_Node], source: _Node, weight: str | _WeightFunc[_Node] | None = None, method: str | None = "dijkstra"
+) -> Generator[tuple[_Node, list[list[_Node]]]]: ...
 @_dispatchable
 def all_pairs_all_shortest_paths(
-    G, weight=None, method="dijkstra"
-) -> Generator[tuple[Incomplete, dict[Incomplete, Incomplete]]]: ...
+    G: Graph[_Node], weight: str | _WeightFunc[_Node] | None = None, method: str | None = "dijkstra"
+) -> Generator[tuple[_Node, dict[_Node, list[list[_Node]]]]]: ...