DOC: SPEC 7: update for NumPy 2.2.0 (#365)

numpy/numpy#27771 allows `default_rng` to accept instances of `RandomState` and convert them to a `Generator`. This updates the SPEC accordingly.

Author: mdhaber

.gitignore

@@ -1,3 +1,4 @@
 *~
 \#*
 **/__pycache__
+.idea

spec-0007/index.md

@@ -38,13 +38,14 @@ We are primarily concerned with API uniformity, but also encourage libraries to
 2. their use avoids relying on global state—which can make code execution harder to track, and may cause problems in parallel processing scenarios.
 
 [^no-RandomState]:
-    Note that `numpy.random.default_rng` does not accept instances of `RandomState`, so use of `RandomState` to control the seed is effectively deprecated, too.
-    That said, neither `np.random.seed` nor `np.random.RandomState` _themselves_ are deprecated, so they may still be used in some contexts (e.g. by developers for generating unit test data).
+    Note that in NumPy versions prior to 2.2.0, `numpy.random.default_rng` does not accept instances of `RandomState`.
+    In more recent versions, `numpy.random.default_rng` will convert `RandomState` instances to `Generator`s, which may not behave identically even with identical method calls.
+    That said, neither `np.random.seed` nor `np.random.RandomState` _themselves_ are deprecated, so they may still be used directly in some contexts (e.g. by developers for generating unit test data).
 
 ### Scope
 
 This is intended as a recommendation to all libraries that allow users to control the state of a NumPy random number generator.
-It is specifically targeted toward functions that currently accept `RandomState` instances via an argument other than `rng`, or allow `numpy.random.seed` to control the random state, but the ideas are more broadly applicable.
+It is specifically targeted toward functions that currently accept random number seeds using an argument other than `rng`, rely on the particular behavior of `RandomState` methods, or allow `numpy.random.seed` to control the random state, but the ideas are more broadly applicable.
 Random number generators other than those provided by NumPy could also be accommodated by an `rng` keyword, but that is beyond the scope of this SPEC.
 
 ### Concepts
@@ -124,7 +125,7 @@ def my_func(*, rng: RNGLike | SeedLike | None = None):
         Pseudorandom number generator state. When `rng` is None, a new
         `numpy.random.Generator` is created using entropy from the
         operating system. Types other than `numpy.random.Generator` are
-        passed to `numpy.random.default_rng` to instantiate a `Generator`.
+        passed to `numpy.random.default_rng` to instantiate a ``Generator``.
     """
     rng = np.random.default_rng(rng)
 

spec-0007/transition_to_rng.py

@@ -43,8 +43,11 @@ def _transition_to_rng(old_name, *, position_num=None, end_version=None):
       - If `None` is passed by position and `np.random.seed` has been used,
         the function will change from being seeded to being unseeded.
       - If an integer is passed by position, the random stream will change.
-      - If `np.random` or an instance of `RandomState` is passed by position,
-        an error will be raised.
+      - If an instance of `RandomState` is passed by position, either an
+        error will be raised (NumPy < 2.2.0), or it will be accepted
+        (NumPy >= 2.2.0) but the random numbers generated may be different
+        from those that would be produced by the original `RandomState`.
+      - If `np.random` is passed by position, an error will be raised.
 
       We suggest that projects consider deprecating positional use of
       `random_state`/`rng` (i.e., change their function signatures to