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.

2 files changed, 24 insertions, 23 deletions

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