ing` about the changing
  interpretation of the argument.
- If `rng` is provided as a keyword argument, the decorator validates `rng` using
  `numpy.random.default_rng` before passing it to the function.
- If `end_version` is specified and neither `random_state` nor `rng` is provided
  by the user, the decorator checks whether `np.random.seed` has been used to set
  the global seed. If so, it emits a `FutureWarning`, noting that usage of
  `numpy.random.seed` will eventually have no effect. Either way, the decorator
  calls the function without explicitly passing the `rng` argument.

If `end_version` is specified, a user must pass `rng` as a keyword to avoid
warnings.

After the deprecation period, the decorator can be removed, and the function
can simply validate the `rng` argument by calling `np.random.default_rng(rng)`.

* A `FutureWarning` is emitted when the PRNG argument is used by
  position. It indicates that the "Hinsen principle" (same
  code yielding different results in two versions of the software)
  will be violated, unless positional use is deprecated. Specifically:

  - 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.

  We suggest that projects consider deprecating positional use of
  `random_state`/`rng` (i.e., change their function signatures to
  ``def my_func(..., *, rng=None)``); that might not make sense
  for all projects, so this SPEC does not make that
  recommendation, neither does this decorator enforce it.

Parameters
----------
old_name : str
    The old name of the PRNG argument (e.g. `seed` or `random_state`).
position_num : int, optional
    The (0-indexed) position of the old PRNG argument (if accepted by position).
    Maintainers are welcome to eliminate this argument and use, for example,
    `inspect`, if preferred.
end_version : str, optional
    The full version number of the library when the behavior described in
    `DeprecationWarning`s and `FutureWarning`s will take effect. If left
    unspecified, no warnings will be emitted by the decorator.
replace_doc : bool, default: True
    Whether the decorator should replace the documentation for parameter `rng` with
    `_rng_desc` (defined above), which documents both new `rng` keyword behavior
    and typical legacy `random_state`/`seed` behavior. If True, manually replace
    the first paragraph of the function's old `random_state`/`seed` documentation
    with the desired *final* `rng` documentation; this way, no changes to
    documentation are needed when the decorator is removed. Documentation of `rng`
    after the first blank line is preserved. Use False if the function's old
    `random_state`/`seed` behavior does not match that described by `_rng_desc`.

Ú