Deprecate networkx.utils.empty_generator. (#4599)

* Deprecate networkx.utils.empty_generator.

empty_generator was only used in all_simple_paths.

* Add PR to release notes.

* Modify empty_generator to warn on creation.

Co-authored-by: Stefan van der Walt <stefanv@berkeley.edu>

Co-authored-by: Stefan van der Walt <stefanv@berkeley.edu>

5 files changed, 21 insertions, 5 deletions

diff --git a/doc/developer/deprecations.rst b/doc/developer/deprecations.rst
index c3e67c3d..b44fe296 100644
--- a/doc/developer/deprecations.rst
+++ b/doc/developer/deprecations.rst
@@ -53,6 +53,7 @@ Version 3.0
 * In ``utils/misc.py`` remove ``is_list_of_ints``.
 * In ``utils/misc.py`` remove ``consume``.
 * In ``utils/misc.py`` remove ``default_opener``.
+* In ``utils/misc.py`` remove ``empty_generator``.
 * Remove ``utils/contextmanagers.py`` and related tests.
 * In ``drawing/nx_agraph.py`` remove ``display_pygraphviz`` and related tests.
 * In ``algorithms/chordal.py`` replace ``chordal_graph_cliques`` with ``_chordal_graph_cliques``.
diff --git a/doc/release/release_dev.rst b/doc/release/release_dev.rst
index 637dede3..6efd94b7 100644
--- a/doc/release/release_dev.rst
+++ b/doc/release/release_dev.rst
@@ -92,6 +92,8 @@ Deprecations
   Deprecate ``iterable``.
 - [`#4545 <https://github.com/networkx/networkx/pull/4545>`_]
   Deprecate ``generate_unique_node``.
+- [`#4599 <https://github.com/networkx/networkx/pull/4599>`_]
+  Deprecate ``empty_generator``.
 
 Contributors to this release
 ----------------------------
diff --git a/networkx/algorithms/simple_paths.py b/networkx/algorithms/simple_paths.py
index b762f820..4b1f60ac 100644
--- a/networkx/algorithms/simple_paths.py
+++ b/networkx/algorithms/simple_paths.py
@@ -4,7 +4,6 @@ from itertools import count
 import networkx as nx
 from networkx.utils import not_implemented_for
 from networkx.utils import pairwise
-from networkx.utils import empty_generator
 from networkx.algorithms.shortest_paths.weighted import _weight_function
 
 __all__ = [
@@ -228,17 +227,21 @@ def all_simple_paths(G, source, target, cutoff=None):
         except TypeError as e:
             raise nx.NodeNotFound(f"target node {target} not in graph") from e
     if source in targets:
-        return empty_generator()
+        return _empty_generator()
     if cutoff is None:
         cutoff = len(G) - 1
     if cutoff < 1:
-        return empty_generator()
+        return _empty_generator()
     if G.is_multigraph():
         return _all_simple_paths_multigraph(G, source, targets, cutoff)
     else:
         return _all_simple_paths_graph(G, source, targets, cutoff)
 
 
+def _empty_generator():
+    yield from ()
+
+
 def _all_simple_paths_graph(G, source, targets, cutoff):
     visited = dict.fromkeys([source])
     stack = [iter(G[source])]
diff --git a/networkx/conftest.py b/networkx/conftest.py
index 27725d40..1d266e10 100644
--- a/networkx/conftest.py
+++ b/networkx/conftest.py
@@ -44,6 +44,9 @@ def set_warnings():
         "ignore", category=DeprecationWarning, message="default_opener is deprecated"
     )
     warnings.filterwarnings(
+        "ignore", category=DeprecationWarning, message="empty_generator is deprecated"
+    )
+    warnings.filterwarnings(
         "ignore", category=DeprecationWarning, message="make_str is deprecated"
     )
     warnings.filterwarnings(
diff --git a/networkx/utils/misc.py b/networkx/utils/misc.py
index 56b1d182..4caffbe1 100644
--- a/networkx/utils/misc.py
+++ b/networkx/utils/misc.py
@@ -60,8 +60,15 @@ def iterable(obj):
 
 
 def empty_generator():
-    """ Return a generator with no members """
-    yield from ()
+    """Return a generator with no members.
+
+    .. deprecated:: 2.6
+    """
+    warnings.warn(
+        "empty_generator is deprecated and will be removed in v3.0.",
+        DeprecationWarning,
+    )
+    return (i for i in ())
 
 
 def flatten(obj, result=None):