# Licensed under a 3-clause BSD style license - see LICENSE.rst
"""
This module provides tools to seed a numpy RandomState instance.
"""

import numbers

import numpy as np

__all__ = ['check_random_state']


def check_random_state(seed):
    """
    Turn seed into a `numpy.random.mtrand.RandomState` instance.

    Parameters
    ----------
    seed : `None`, int, or `numpy.random.mtrand.RandomState`
        If ``seed`` is `None`, return the
        `~numpy.random.mtrand.RandomState` singleton used by
        ``numpy.random``.  If ``seed`` is an `int`, return a new
        `~numpy.random.mtrand.RandomState` instance seeded with
        ``seed``.  If ``seed`` is already a
        `~numpy.random.mtrand.RandomState`, return it.  Otherwise raise
        ``ValueError``.

    Returns
    -------
    random_state : `numpy.random.mtrand.RandomState`
        RandomState object.

    Notes
    -----
    This routine is from scikit-learn.  See
    https://scikit-learn.org/stable/developers/utilities.html#validation-tools.
    """

    if seed is None or seed is np.random:
        return np.random.mtrand._rand
    if isinstance(seed, (numbers.Integral, np.integer)):
        return np.random.RandomState(seed)
    if isinstance(seed, np.random.RandomState):
        return seed

    raise ValueError('{0!r} cannot be used to seed a numpy.random.RandomState'
                     ' instance'.format(seed))
