Deprecate `random_state` decorator (#5055)

* Reorganize aliases and deprecate random_state.

* Rm internal uses of random_state.

* Update tests.

Rm tests or rename to use np_random_state.

* Update reference guide.

* Update deprecations.rst.

* Remove preserve_random_state from refguide.

* Add deprecation to release notes.

7 files changed, 39 insertions, 34 deletions

diff --git a/doc/developer/deprecations.rst b/doc/developer/deprecations.rst
index b4c27e96..b66e9a8a 100644
--- a/doc/developer/deprecations.rst
+++ b/doc/developer/deprecations.rst
@@ -90,3 +90,4 @@ Version 3.0
 * In ``algorithms/similarity.py`` replace ``simrank_similarity`` with ``simrank_similarity_numpy``.
 * In ``algorithms/assortativity/mixing.py`` remove ``numeric_mixing_matrix``.
 * In ``algorithms/assortativity/connectivity.py`` remove ``k_nearest_neighbors``.
+* In ``utils/decorators.py`` remove ``random_state``.
diff --git a/doc/reference/utils.rst b/doc/reference/utils.rst
index 81fd80e6..7a223fbd 100644
--- a/doc/reference/utils.rst
+++ b/doc/reference/utils.rst
@@ -56,8 +56,8 @@ Decorators
    open_file
    not_implemented_for
    nodes_or_number
-   preserve_random_state
-   random_state
+   np_random_state
+   py_random_state
    argmap
 
 Cuthill-Mckee Ordering
diff --git a/doc/release/release_dev.rst b/doc/release/release_dev.rst
index f0cc0d1c..37644b00 100644
--- a/doc/release/release_dev.rst
+++ b/doc/release/release_dev.rst
@@ -42,6 +42,9 @@ API Changes
 Deprecations
 ------------
 
+- [`#5055 <https://github.com/networkx/networkx/pull/5055>`_]
+  Deprecate the ``random_state`` alias in favor of ``np_random_state``
+
 
 Merged PRs
 ----------
diff --git a/networkx/drawing/layout.py b/networkx/drawing/layout.py
index 558baff5..8a6e4ace 100644
--- a/networkx/drawing/layout.py
+++ b/networkx/drawing/layout.py
@@ -16,7 +16,7 @@ Warning: Most layout routines have only been tested in 2-dimensions.
 
 """
 import networkx as nx
-from networkx.utils import random_state
+from networkx.utils import np_random_state
 
 __all__ = [
     "bipartite_layout",
@@ -56,7 +56,7 @@ def _process_params(G, center, dim):
     return G, center
 
 
-@random_state(3)
+@np_random_state(3)
 def random_layout(G, center=None, dim=2, seed=None):
     """Position nodes uniformly at random in the unit square.
 
@@ -342,7 +342,7 @@ def bipartite_layout(
     return pos
 
 
-@random_state(10)
+@np_random_state(10)
 def spring_layout(
     G,
     k=None,
@@ -499,7 +499,7 @@ def spring_layout(
 fruchterman_reingold_layout = spring_layout
 
 
-@random_state(7)
+@np_random_state(7)
 def _fruchterman_reingold(
     A, k=None, pos=None, fixed=None, iterations=50, threshold=1e-4, dim=2, seed=None
 ):
@@ -562,7 +562,7 @@ def _fruchterman_reingold(
     return pos
 
 
-@random_state(7)
+@np_random_state(7)
 def _sparse_fruchterman_reingold(
     A, k=None, pos=None, fixed=None, iterations=50, threshold=1e-4, dim=2, seed=None
 ):
diff --git a/networkx/linalg/algebraicconnectivity.py b/networkx/linalg/algebraicconnectivity.py
index 14dbfc8f..748d7307 100644
--- a/networkx/linalg/algebraicconnectivity.py
+++ b/networkx/linalg/algebraicconnectivity.py
@@ -5,7 +5,7 @@ from functools import partial
 import networkx as nx
 from networkx.utils import not_implemented_for
 from networkx.utils import reverse_cuthill_mckee_ordering
-from networkx.utils import random_state
+from networkx.utils import np_random_state
 
 __all__ = ["algebraic_connectivity", "fiedler_vector", "spectral_ordering"]
 
@@ -321,7 +321,7 @@ def _get_fiedler_func(method):
     return find_fiedler
 
 
-@random_state(5)
+@np_random_state(5)
 @not_implemented_for("directed")
 def algebraic_connectivity(
     G, weight="weight", normalized=False, tol=1e-8, method="tracemin_pcg", seed=None
@@ -403,7 +403,7 @@ def algebraic_connectivity(
     return sigma
 
 
-@random_state(5)
+@np_random_state(5)
 @not_implemented_for("directed")
 def fiedler_vector(
     G, weight="weight", normalized=False, tol=1e-8, method="tracemin_pcg", seed=None
@@ -488,7 +488,7 @@ def fiedler_vector(
     return fiedler
 
 
-@random_state(5)
+@np_random_state(5)
 def spectral_ordering(
     G, weight="weight", normalized=False, tol=1e-8, method="tracemin_pcg", seed=None
 ):
diff --git a/networkx/utils/decorators.py b/networkx/utils/decorators.py
index a9dc032a..cab7ad54 100644
--- a/networkx/utils/decorators.py
+++ b/networkx/utils/decorators.py
@@ -2,7 +2,6 @@ from collections import defaultdict
 from os.path import splitext
 from contextlib import contextmanager
 from pathlib import Path
-import warnings
 
 import networkx as nx
 from networkx.utils import create_random_state, create_py_random_state
@@ -285,6 +284,8 @@ def preserve_random_state(func):
     -----
     If numpy.random is not importable, the state is not saved or restored.
     """
+    import warnings
+
     msg = "preserve_random_state is deprecated and will be removed in 3.0."
     warnings.warn(msg, DeprecationWarning)
 
@@ -310,7 +311,7 @@ def preserve_random_state(func):
         return func
 
 
-def random_state(random_state_argument):
+def np_random_state(random_state_argument):
     """Decorator to generate a `numpy.random.RandomState` instance.
 
     The decorator processes the argument indicated by `random_state_argument`
@@ -354,7 +355,25 @@ def random_state(random_state_argument):
     return argmap(create_random_state, random_state_argument)
 
 
-np_random_state = random_state
+def random_state(random_state_argument):
+    """Decorator to generate a `numpy.random.RandomState` instance.
+
+    .. deprecated:: 2.7
+
+       This function is a deprecated alias for `np_random_state` and will be
+       removed in version 3.0. Use np_random_state instead.
+    """
+    import warnings
+
+    warnings.warn(
+        (
+            "`random_state` is a deprecated alias for `np_random_state`\n"
+            "and will be removed in version 3.0. Use `np_random_state` instead."
+        ),
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return np_random_state(random_state_argument)
 
 
 def py_random_state(random_state_argument):
diff --git a/networkx/utils/tests/test_decorators.py b/networkx/utils/tests/test_decorators.py
index 64fc3e28..eee48fd4 100644
--- a/networkx/utils/tests/test_decorators.py
+++ b/networkx/utils/tests/test_decorators.py
@@ -222,11 +222,6 @@ class TestRandomState:
         global np
         np = pytest.importorskip("numpy")
 
-    @random_state(1)
-    def instantiate_random_state(self, random_state):
-        assert isinstance(random_state, np.random.RandomState)
-        return random_state.random_sample()
-
     @np_random_state(1)
     def instantiate_np_random_state(self, random_state):
         assert isinstance(random_state, np.random.RandomState)
@@ -243,8 +238,6 @@ class TestRandomState:
         np.random.seed(42)
         rv = np.random.random_sample()
         np.random.seed(42)
-        assert rv == self.instantiate_random_state(None)
-        np.random.seed(42)
         assert rv == self.instantiate_np_random_state(None)
 
         random.seed(42)
@@ -256,8 +249,6 @@ class TestRandomState:
         np.random.seed(42)
         rv = np.random.random_sample()
         np.random.seed(42)
-        assert rv == self.instantiate_random_state(np.random)
-        np.random.seed(42)
         assert rv == self.instantiate_np_random_state(np.random)
         np.random.seed(42)
         assert rv == self.instantiate_py_random_state(np.random)
@@ -270,10 +261,6 @@ class TestRandomState:
 
         np.random.seed(42)
         seed = 1
-        rval = self.instantiate_random_state(seed)
-        rval_expected = np.random.RandomState(seed).rand()
-        assert rval, rval_expected
-
         rval = self.instantiate_np_random_state(seed)
         rval_expected = np.random.RandomState(seed).rand()
         assert rval, rval_expected
@@ -294,10 +281,6 @@ class TestRandomState:
         np.random.seed(42)
         seed = 1
         rng = np.random.RandomState(seed)
-        rval = self.instantiate_random_state(rng)
-        rval_expected = np.random.RandomState(seed).rand()
-        assert rval, rval_expected
-
         rval = self.instantiate_np_random_state(seed)
         rval_expected = np.random.RandomState(seed).rand()
         assert rval, rval_expected
@@ -314,14 +297,13 @@ class TestRandomState:
         rv = self.instantiate_py_random_state(rng)
         assert rv, random.Random(seed).random()
 
-        pytest.raises(ValueError, self.instantiate_random_state, rng)
         pytest.raises(ValueError, self.instantiate_np_random_state, rng)
 
 
 def test_random_state_string_arg_index():
     with pytest.raises(nx.NetworkXError):
 
-        @random_state("a")
+        @np_random_state("a")
         def make_random_state(rs):
             pass
 
@@ -341,7 +323,7 @@ def test_py_random_state_string_arg_index():
 def test_random_state_invalid_arg_index():
     with pytest.raises(nx.NetworkXError):
 
-        @random_state(2)
+        @np_random_state(2)
         def make_random_state(rs):
             pass