`scipy._lib._util:_transition_to_rng`

source: /scipy/_lib/_util.py :201

Signature

   def     _transition_to_rng (    old_name    ,  * ,     position_num    =  None   ,    end_version    =  None   ,    replace_doc    =  True     )

Summary

Example decorator to transition from old PRNG usage to new rng behavior

Extended Summary

Suppose the decorator is applied to a function that used to accept parameter old_name='random_state' either by keyword or as a positional argument at position_num=1. At the time of application, the name of the argument in the function signature is manually changed to the new name, rng. If positional use was allowed before, this is not changed.*

If the function is called with both random_state and rng, the decorator raises an error.
If random_state is provided as a keyword argument, the decorator passes random_state to the function's rng argument as a keyword. If end_version is specified, the decorator will emit a DeprecationWarning about the deprecation of keyword random_state.
If random_state is provided as a positional argument, the decorator passes random_state to the function's rng argument by position. If end_version is specified, the decorator will emit a FutureWarning 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.

Aliases

scipy.cluster.vq._transition_to_rng