Deprecate dict to numpy helpers (#5427)

* Convert to private fns and add deprecated public wrappers.

* Modify existing tests to use private fns.

* Add test that dep warnings are raised.

* Add dep note.

* Add release note.

* Add importorskip(numpy).

2 files changed, 55 insertions, 15 deletions

diff --git a/networkx/utils/misc.py b/networkx/utils/misc.py
index d08ed437..d98e6c35 100644
--- a/networkx/utils/misc.py
+++ b/networkx/utils/misc.py
@@ -227,14 +227,31 @@ def dict_to_numpy_array(d, mapping=None):
     """Convert a dictionary of dictionaries to a numpy array
     with optional mapping."""
     try:
-        return dict_to_numpy_array2(d, mapping)
+        return _dict_to_numpy_array2(d, mapping)
     except (AttributeError, TypeError):
         # AttributeError is when no mapping was provided and v.keys() fails.
         # TypeError is when a mapping was provided and d[k1][k2] fails.
-        return dict_to_numpy_array1(d, mapping)
+        return _dict_to_numpy_array1(d, mapping)
 
 
 def dict_to_numpy_array2(d, mapping=None):
+    """Convert a dict of dicts to a 2d numpy array with optional mapping.
+
+    .. deprecated:: 2.8
+
+       dict_to_numpy_array2 is deprecated and will be removed in networkx 3.0.
+       Use `dict_to_numpy_array` instead.
+    """
+    msg = (
+        "dict_to_numpy_array2 is deprecated and will be removed in networkx 3.0.\n"
+        "Use dict_to_numpy_array instead."
+    )
+    warnings.warn(msg, DeprecationWarning, stacklevel=2)
+
+    return _dict_to_numpy_array2(d, mapping)
+
+
+def _dict_to_numpy_array2(d, mapping=None):
     """Convert a dictionary of dictionaries to a 2d numpy array
     with optional mapping.
 
@@ -256,10 +273,24 @@ def dict_to_numpy_array2(d, mapping=None):
 
 
 def dict_to_numpy_array1(d, mapping=None):
-    """Convert a dictionary of numbers to a 1d numpy array
-    with optional mapping.
+    """Convert a dict of numbers to a 1d numpy array with optional mapping.
+
+    .. deprecated:: 2.8
 
+       dict_to_numpy_array1 is deprecated and will be removed in networkx 3.0.
+       Use dict_to_numpy_array instead.
     """
+    msg = (
+        "dict_to_numpy_array1 is deprecated and will be removed in networkx 3.0.\n"
+        "Use dict_to_numpy_array instead."
+    )
+    warnings.warn(msg, DeprecationWarning, stacklevel=2)
+
+    return _dict_to_numpy_array1(d, mapping)
+
+
+def _dict_to_numpy_array1(d, mapping=None):
+    """Convert a dictionary of numbers to a 1d numpy array with optional mapping."""
     if mapping is None:
         s = set(d.keys())
         mapping = dict(zip(s, range(len(s))))
diff --git a/networkx/utils/tests/test_misc.py b/networkx/utils/tests/test_misc.py
index 062800a0..bd82afcb 100644
--- a/networkx/utils/tests/test_misc.py
+++ b/networkx/utils/tests/test_misc.py
@@ -9,8 +9,6 @@ from networkx.utils import (
     create_random_state,
     discrete_sequence,
     dict_to_numpy_array,
-    dict_to_numpy_array1,
-    dict_to_numpy_array2,
     flatten,
     is_string_like,
     iterable,
@@ -22,6 +20,7 @@ from networkx.utils import (
     PythonRandomInterface,
     to_tuple,
 )
+from networkx.utils.misc import _dict_to_numpy_array1, _dict_to_numpy_array2
 
 nested_depth = (
     1,
@@ -129,24 +128,24 @@ class TestNumpyArray:
         assert type(B[0]) == int
         pytest.raises(nx.NetworkXError, make_list_of_ints, c)
 
-    def test_dict_to_numpy_array1(self):
+    def test__dict_to_numpy_array1(self):
         d = {"a": 1, "b": 2}
-        a = dict_to_numpy_array1(d, mapping={"a": 0, "b": 1})
+        a = _dict_to_numpy_array1(d, mapping={"a": 0, "b": 1})
         np.testing.assert_allclose(a, np.array([1, 2]))
-        a = dict_to_numpy_array1(d, mapping={"b": 0, "a": 1})
+        a = _dict_to_numpy_array1(d, mapping={"b": 0, "a": 1})
         np.testing.assert_allclose(a, np.array([2, 1]))
 
-        a = dict_to_numpy_array1(d)
+        a = _dict_to_numpy_array1(d)
         np.testing.assert_allclose(a.sum(), 3)
 
-    def test_dict_to_numpy_array2(self):
+    def test__dict_to_numpy_array2(self):
         d = {"a": {"a": 1, "b": 2}, "b": {"a": 10, "b": 20}}
 
         mapping = {"a": 1, "b": 0}
-        a = dict_to_numpy_array2(d, mapping=mapping)
+        a = _dict_to_numpy_array2(d, mapping=mapping)
         np.testing.assert_allclose(a, np.array([[20, 10], [2, 1]]))
 
-        a = dict_to_numpy_array2(d)
+        a = _dict_to_numpy_array2(d)
         np.testing.assert_allclose(a.sum(), 33)
 
     def test_dict_to_numpy_array_a(self):
@@ -160,7 +159,7 @@ class TestNumpyArray:
         a = dict_to_numpy_array(d, mapping=mapping)
         np.testing.assert_allclose(a, np.array([[20, 10], [2, 1]]))
 
-        a = dict_to_numpy_array2(d)
+        a = _dict_to_numpy_array2(d)
         np.testing.assert_allclose(a.sum(), 33)
 
     def test_dict_to_numpy_array_b(self):
@@ -170,7 +169,7 @@ class TestNumpyArray:
         a = dict_to_numpy_array(d, mapping=mapping)
         np.testing.assert_allclose(a, np.array([1, 2]))
 
-        a = dict_to_numpy_array1(d)
+        a = _dict_to_numpy_array1(d)
         np.testing.assert_allclose(a.sum(), 3)
 
 
@@ -310,3 +309,13 @@ def test_arbitrary_element_raises(iterator):
     """Value error is raised when input is an iterator."""
     with pytest.raises(ValueError, match="from an iterator"):
         arbitrary_element(iterator)
+
+
+def test_dict_to_numpy_array_deprecations():
+    np = pytest.importorskip("numpy")
+    d = {"a": 1}
+    with pytest.deprecated_call():
+        nx.utils.dict_to_numpy_array1(d)
+    d2 = {"a": {"b": 2}}
+    with pytest.deprecated_call():
+        nx.utils.dict_to_numpy_array2(d2)