Add initial_graph parameter to scale_free_graph and deprecate create_…

…using (#5697)

* Add initial_graph and deprecate create_using for scale_free_graph.

* Add test for initial_graph kwarg.

* doc and warningsfilter.

* Fix formatting.

* Update doc/developer/deprecations.rst

Co-authored-by: Jarrod Millman <jarrod.millman@gmail.com>

doc/developer/deprecations.rst

@@ -115,3 +115,8 @@ Version 3.0
 * In ``utils/misc.py`` remove ``dict_to_numpy_array1`` and ``dict_to_numpy_array2``.
 * In ``utils/misc.py`` remove ``to_tuple``.
 * In ``algorithms/matching.py``, remove parameter ``maxcardinality`` from ``min_weight_matching``.
+
+Version 3.2
+~~~~~~~~~~~
+* In ``generators/directed.py`` remove the ``create_using`` keyword argument
+  for the ``scale_free_graph`` function.

networkx/conftest.py

@@ -236,6 +236,10 @@ def set_warnings():
     )
     warnings.filterwarnings("ignore", category=DeprecationWarning, message="info")
     warnings.filterwarnings("ignore", category=DeprecationWarning, message="to_tuple")
+    # create_using for scale_free_graph
+    warnings.filterwarnings(
+        "ignore", category=DeprecationWarning, message="The create_using argument"
+    )
 
 
 @pytest.fixture(autouse=True)

networkx/generators/directed.py

@@ -189,6 +189,7 @@ def scale_free_graph(
     delta_out=0,
     create_using=None,
     seed=None,
+    initial_graph=None,
 ):
     """Returns a scale-free directed graph.
 
@@ -215,9 +216,22 @@ def scale_free_graph(
         The default is a MultiDiGraph 3-cycle.
         If a graph instance, use it without clearing first.
         If a graph constructor, call it to construct an empty graph.
+
+        .. deprecated:: 3.0
+
+           create_using is deprecated, use `initial_graph` instead.
+
     seed : integer, random_state, or None (default)
         Indicator of random number generation state.
         See :ref:`Randomness<randomness>`.
+    initial_graph : MultiDiGraph instance, optional
+        Build the scale-free graph starting from this initial MultiDiGraph,
+        if provided.
+
+
+    Returns
+    -------
+    MultiDiGraph
 
     Examples
     --------
@@ -245,14 +259,37 @@ def _choose_node(candidates, node_list, delta):
                 return seed.choice(node_list)
         return seed.choice(candidates)
 
-    if create_using is None or not hasattr(create_using, "_adj"):
-        # start with 3-cycle
-        G = nx.empty_graph(3, create_using, default=nx.MultiDiGraph)
-        G.add_edges_from([(0, 1), (1, 2), (2, 0)])
-    else:
+    if create_using is not None:
+        import warnings
+
+        warnings.warn(
+            "The create_using argument is deprecated and will be removed in the future.\n\n"
+            "To create a scale free graph from an existing MultiDiGraph, use\n"
+            "initial_graph instead.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
+    # TODO: Rm all this complicated logic when deprecation expires and replace
+    # with commented code:
+    #    if initial_graph is not None and hasattr(initial_graph, "_adj"):
+    #        G = initial_graph
+    #    else:
+    #        # Start with 3-cycle
+    #        G = nx.MultiDiGraph([(0, 1), (1, 2), (2, 0)])
+    if create_using is not None and hasattr(create_using, "_adj"):
+        if initial_graph is not None:
+            raise ValueError(
+                "Cannot set both create_using and initial_graph. Set create_using=None."
+            )
         G = create_using
+    else:
+        if initial_graph is not None and hasattr(initial_graph, "_adj"):
+            G = initial_graph
+        else:
+            G = nx.MultiDiGraph([(0, 1), (1, 2), (2, 0)])
     if not (G.is_directed() and G.is_multigraph()):
-        raise nx.NetworkXError("MultiDiGraph required in create_using")
+        raise nx.NetworkXError("MultiDiGraph required in initial_graph")
 
     if alpha <= 0:
         raise ValueError("alpha must be > 0.")

networkx/generators/tests/test_directed.py

@@ -58,6 +58,12 @@ def test_create_using_keyword_arguments(self):
         pytest.raises(ValueError, scale_free_graph, 100, gamma=-0.3)
 
 
+@pytest.mark.parametrize("ig", (nx.Graph(), nx.DiGraph([(0, 1)])))
+def test_scale_free_graph_initial_graph_kwarg(ig):
+    with pytest.raises(nx.NetworkXError):
+        scale_free_graph(100, initial_graph=ig)
+
+
 class TestRandomKOutGraph:
     """Unit tests for the
     :func:`~networkx.generators.directed.random_k_out_graph` function.