Deprecate the create argument of nonisomorphic_trees (networkx#7316)

* Add deprecation warning and docstring warning.

* Add deprecated_call to tests.

* Add warnings filter to test conf.

* Add note to deprecation docs.

doc/developer/deprecations.rst

@@ -70,3 +70,5 @@ Version 3.5
   to return a dict. See #6527
 * Change ``shortest_path`` in ``algorithms/shortest_path/generic.py``
   to return a iterator. See #6527
+* Remove ``create`` keyword argument from ``nonisomorphic_trees`` in 
+  ``generators/nonisomorphic_trees``.

networkx/conftest.py

@@ -148,6 +148,9 @@ def set_warnings():
     warnings.filterwarnings(
         "ignore", category=DeprecationWarning, message="\n\nk_corona"
     )
+    warnings.filterwarnings(
+        "ignore", category=DeprecationWarning, message=r"\n\nThe 'create=matrix'"
+    )
 
 
 @pytest.fixture(autouse=True)

networkx/generators/nonisomorphic_trees.py

@@ -25,6 +25,15 @@ def nonisomorphic_trees(order, create="graph"):
        If ``"graph"`` is selected a list of ``Graph`` instances will be returned,
        if matrix is selected a list of adjacency matrices will be returned.
 
+       .. deprecated:: 3.3
+
+          The `create` argument is deprecated and will be removed in NetworkX
+          version 3.5. In the future, `nonisomorphic_trees` will yield graph
+          instances by default. To generate adjacency matrices, call
+          ``nx.to_numpy_array`` on the output, e.g.::
+
+             [nx.to_numpy_array(G) for G in nx.nonisomorphic_trees(N)]
+
     Yields
     ------
     list
@@ -45,6 +54,20 @@ def nonisomorphic_trees(order, create="graph"):
             if create == "graph":
                 yield _layout_to_graph(layout)
             elif create == "matrix":
+                import warnings
+
+                warnings.warn(
+                    (
+                        "\n\nThe 'create=matrix' argument of nonisomorphic_trees\n"
+                        "is deprecated and will be removed in version 3.5.\n"
+                        "Use ``nx.to_numpy_array`` to convert graphs to adjacency "
+                        "matrices, e.g.::\n\n"
+                        "   [nx.to_numpy_array(G) for G in nx.nonisomorphic_trees(N)]"
+                    ),
+                    category=DeprecationWarning,
+                    stacklevel=2,
+                )
+
                 yield _layout_to_matrix(layout)
             layout = _next_rooted_tree(layout)
 

networkx/generators/tests/test_nonisomorphic_trees.py

@@ -1,10 +1,8 @@
 """
-====================
-Generators - Non Isomorphic Trees
-====================
-
 Unit tests for WROM algorithm generator in generators/nonisomorphic_trees.py
 """
+import pytest
+
 import networkx as nx
 from networkx.utils import edges_equal
 
@@ -54,11 +52,16 @@ def f(x):
 
     def test_nonisomorphic_trees_matrix(self):
         trees_2 = [[[0, 1], [1, 0]]]
-        assert list(nx.nonisomorphic_trees(2, create="matrix")) == trees_2
+        with pytest.deprecated_call():
+            assert list(nx.nonisomorphic_trees(2, create="matrix")) == trees_2
+
         trees_3 = [[[0, 1, 1], [1, 0, 0], [1, 0, 0]]]
-        assert list(nx.nonisomorphic_trees(3, create="matrix")) == trees_3
+        with pytest.deprecated_call():
+            assert list(nx.nonisomorphic_trees(3, create="matrix")) == trees_3
+
         trees_4 = [
             [[0, 1, 0, 1], [1, 0, 1, 0], [0, 1, 0, 0], [1, 0, 0, 0]],
             [[0, 1, 1, 1], [1, 0, 0, 0], [1, 0, 0, 0], [1, 0, 0, 0]],
         ]
-        assert list(nx.nonisomorphic_trees(4, create="matrix")) == trees_4
+        with pytest.deprecated_call():
+            assert list(nx.nonisomorphic_trees(4, create="matrix")) == trees_4