Merge pull request #18395 from bashtage/random-typing

ENH: Initial typing of random

8 files changed, 810 insertions, 13 deletions

diff --git a/numpy/random/__init__.pyi b/numpy/random/__init__.pyi
index bd5ece536..b99c002ae 100644
--- a/numpy/random/__init__.pyi
+++ b/numpy/random/__init__.pyi
@@ -1,5 +1,14 @@
 from typing import Any, List
 
+from numpy.random._generator import Generator as Generator
+from numpy.random._generator import default_rng as default_rng
+from numpy.random._mt19937 import MT19937 as MT19937
+from numpy.random._pcg64 import PCG64 as PCG64
+from numpy.random._philox import Philox as Philox
+from numpy.random._sfc64 import SFC64 as SFC64
+from numpy.random.bit_generator import BitGenerator as BitGenerator
+from numpy.random.bit_generator import SeedSequence as SeedSequence
+
 __all__: List[str]
 
 beta: Any
@@ -52,12 +61,4 @@ vonmises: Any
 wald: Any
 weibull: Any
 zipf: Any
-Generator: Any
 RandomState: Any
-SeedSequence: Any
-MT19937: Any
-Philox: Any
-PCG64: Any
-SFC64: Any
-default_rng: Any
-BitGenerator: Any
diff --git a/numpy/random/_generator.pyi b/numpy/random/_generator.pyi
new file mode 100644
index 000000000..aadc4d0f8
--- /dev/null
+++ b/numpy/random/_generator.pyi
@@ -0,0 +1,534 @@
+import sys
+from typing import Any, Callable, Dict, Literal, Optional, Sequence, Tuple, Type, Union, overload
+
+from numpy import (
+    bool_,
+    double,
+    dtype,
+    float32,
+    float64,
+    int8,
+    int16,
+    int32,
+    int64,
+    int_,
+    ndarray,
+    single,
+    uint,
+    uint8,
+    uint16,
+    uint32,
+    uint64,
+)
+from numpy.random import BitGenerator, SeedSequence
+from numpy.typing import (
+    ArrayLike,
+    _ArrayLikeFloat_co,
+    _ArrayLikeInt_co,
+    _BoolCodes,
+    _DoubleCodes,
+    _DTypeLikeBool,
+    _DTypeLikeInt,
+    _DTypeLikeUInt,
+    _Float32Codes,
+    _Float64Codes,
+    _Int8Codes,
+    _Int16Codes,
+    _Int32Codes,
+    _Int64Codes,
+    _IntCodes,
+    _ShapeLike,
+    _SingleCodes,
+    _SupportsDType,
+    _UInt8Codes,
+    _UInt16Codes,
+    _UInt32Codes,
+    _UInt64Codes,
+    _UIntCodes,
+)
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+_DTypeLikeFloat32 = Union[
+    dtype[float32],
+    _SupportsDType[dtype[float32]],
+    Type[float32],
+    _Float32Codes,
+    _SingleCodes,
+]
+
+_DTypeLikeFloat64 = Union[
+    dtype[float64],
+    _SupportsDType[dtype[float64]],
+    Type[float],
+    Type[float64],
+    _Float64Codes,
+    _DoubleCodes,
+]
+
+class Generator:
+    # COMPLETE
+    def __init__(self, bit_generator: BitGenerator) -> None: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...
+    # Pickling support:
+    def __getstate__(self) -> Dict[str, Any]: ...
+    def __setstate__(self, state: Dict[str, Any]) -> None: ...
+    def __reduce__(self) -> Tuple[Callable[[str], BitGenerator], Tuple[str], Dict[str, Any]]: ...
+    @property
+    def bit_generator(self) -> BitGenerator: ...
+    def bytes(self, length: int) -> str: ...
+    @overload
+    def standard_normal(  # type: ignore[misc]
+        self,
+        size: None = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        out: None = ...,
+    ) -> float: ...
+    @overload
+    def standard_normal(  # type: ignore[misc]
+        self,
+        size: _ShapeLike = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        out: Optional[ndarray[Any, dtype[Union[float32, float64]]]] = ...,
+    ) -> ndarray[Any, dtype[Union[float32, float64]]]: ...
+    @overload
+    def permutation(self, x: int, axis: int = ...) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def permutation(self, x: ArrayLike, axis: int = ...) -> ndarray[Any, Any]: ...
+    @overload
+    def standard_cauchy(self, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def standard_cauchy(self, size: Optional[_ShapeLike] = ...) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def standard_exponential(  # type: ignore[misc]
+        self,
+        size: None = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        method: Literal["zig", "inv"] = ...,
+        out: None = ...,
+    ) -> float: ...
+    @overload
+    def standard_exponential(
+        self,
+        size: _ShapeLike = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        method: Literal["zig", "inv"] = ...,
+        out: Optional[ndarray[Any, dtype[Union[float32, float64]]]] = ...,
+    ) -> ndarray[Any, dtype[Union[float32, float64]]]: ...
+    @overload
+    def standard_exponential(
+        self,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        method: Literal["zig", "inv"] = ...,
+        out: ndarray[Any, dtype[Union[float32, float64]]] = ...,
+    ) -> ndarray[Any, dtype[Union[float32, float64]]]: ...
+    @overload
+    def random(  # type: ignore[misc]
+        self,
+        size: None = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        out: None = ...,
+    ) -> float: ...
+    @overload
+    def random(
+        self,
+        size: _ShapeLike = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        out: Optional[ndarray[Any, dtype[Union[float32, float64]]]] = ...,
+    ) -> ndarray[Any, dtype[Union[float32, float64]]]: ...
+    @overload
+    def beta(self, a: float, b: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def beta(
+        self, a: _ArrayLikeFloat_co, b: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def exponential(self, scale: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def exponential(
+        self, scale: _ArrayLikeFloat_co = ..., size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: int,
+        high: Optional[int] = ...,
+        size: None = ...,
+        dtype: _DTypeLikeBool = ...,
+        endpoint: bool = ...,
+    ) -> bool: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: int,
+        high: Optional[int] = ...,
+        size: None = ...,
+        dtype: Union[_DTypeLikeInt, _DTypeLikeUInt] = ...,
+        endpoint: bool = ...,
+    ) -> int: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[
+            dtype[bool_], Type[bool], Type[bool_], _BoolCodes, _SupportsDType[dtype[bool_]]
+        ] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[bool_]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[
+            dtype[int_], Type[int], Type[int_], _IntCodes, _SupportsDType[dtype[int_]]
+        ] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[int_]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[dtype[uint], Type[uint], _UIntCodes, _SupportsDType[dtype[uint]]] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[uint]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[dtype[int8], Type[int8], _Int8Codes, _SupportsDType[dtype[int8]]] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[int8]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[dtype[int16], Type[int16], _Int16Codes, _SupportsDType[dtype[int16]]] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[int16]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[dtype[int32], Type[int32], _Int32Codes, _SupportsDType[dtype[int32]]] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[Union[int32]]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Optional[
+            Union[dtype[int64], Type[int64], _Int64Codes, _SupportsDType[dtype[int64]]]
+        ] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[dtype[uint8], Type[uint8], _UInt8Codes, _SupportsDType[dtype[uint8]]] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[uint8]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[
+            dtype[uint16], Type[uint16], _UInt16Codes, _SupportsDType[dtype[uint16]]
+        ] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[Union[uint16]]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[
+            dtype[uint32], Type[uint32], _UInt32Codes, _SupportsDType[dtype[uint32]]
+        ] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[uint32]]: ...
+    @overload
+    def integers(  # type: ignore[misc]
+        self,
+        low: _ArrayLikeInt_co,
+        high: Optional[_ArrayLikeInt_co] = ...,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[
+            dtype[uint64], Type[uint64], _UInt64Codes, _SupportsDType[dtype[uint64]]
+        ] = ...,
+        endpoint: bool = ...,
+    ) -> ndarray[Any, dtype[uint64]]: ...
+    # TODO: Use a TypeVar _T here to get away from Any output?  Should be int->ndarray[Any,dtype[int64]], ArrayLike[_T] -> Union[_T, ndarray[Any,Any]]
+    def choice(
+        self,
+        a: ArrayLike,
+        size: Optional[_ShapeLike] = ...,
+        replace: bool = ...,
+        p: Optional[_ArrayLikeFloat_co] = ...,
+        axis: Optional[int] = ...,
+        shuffle: bool = ...,
+    ) -> Any: ...
+    @overload
+    def uniform(self, low: float = ..., high: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def uniform(
+        self,
+        low: _ArrayLikeFloat_co = ...,
+        high: _ArrayLikeFloat_co = ...,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def normal(self, loc: float = ..., scale: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def normal(
+        self,
+        loc: _ArrayLikeFloat_co = ...,
+        scale: _ArrayLikeFloat_co = ...,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def standard_gamma(  # type: ignore[misc]
+        self,
+        shape: float,
+        size: None = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        out: None = ...,
+    ) -> float: ...
+    @overload
+    def standard_gamma(
+        self,
+        shape: _ArrayLikeFloat_co,
+        size: Optional[_ShapeLike] = ...,
+        dtype: Union[_DTypeLikeFloat32, _DTypeLikeFloat64] = ...,
+        out: Optional[ndarray[Any, dtype[Union[float32, float64]]]] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def gamma(self, shape: float, scale: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def gamma(
+        self,
+        shape: _ArrayLikeFloat_co,
+        scale: _ArrayLikeFloat_co = ...,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def f(self, dfnum: float, dfden: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def f(
+        self, dfnum: _ArrayLikeFloat_co, dfden: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def noncentral_f(self, dfnum: float, dfden: float, nonc: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def noncentral_f(
+        self,
+        dfnum: _ArrayLikeFloat_co,
+        dfden: _ArrayLikeFloat_co,
+        nonc: _ArrayLikeFloat_co,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def chisquare(self, df: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def chisquare(
+        self, df: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def noncentral_chisquare(self, df: float, nonc: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def noncentral_chisquare(
+        self, df: _ArrayLikeFloat_co, nonc: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def standard_t(self, df: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def standard_t(
+        self, df: _ArrayLikeFloat_co, size: None = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def standard_t(
+        self, df: _ArrayLikeFloat_co, size: _ShapeLike = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def vonmises(self, mu: float, kappa: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def vonmises(
+        self, mu: _ArrayLikeFloat_co, kappa: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def pareto(self, a: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def pareto(
+        self, a: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def weibull(self, a: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def weibull(
+        self, a: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def power(self, a: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def power(
+        self, a: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def laplace(self, loc: float = ..., scale: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def laplace(
+        self,
+        loc: _ArrayLikeFloat_co = ...,
+        scale: _ArrayLikeFloat_co = ...,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def gumbel(self, loc: float = ..., scale: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def gumbel(
+        self,
+        loc: _ArrayLikeFloat_co = ...,
+        scale: _ArrayLikeFloat_co = ...,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def logistic(self, loc: float = ..., scale: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def logistic(
+        self,
+        loc: _ArrayLikeFloat_co = ...,
+        scale: _ArrayLikeFloat_co = ...,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def lognormal(self, mean: float = ..., sigma: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def lognormal(
+        self,
+        mean: _ArrayLikeFloat_co = ...,
+        sigma: _ArrayLikeFloat_co = ...,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def rayleigh(self, scale: float = ..., size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def rayleigh(
+        self, scale: _ArrayLikeFloat_co = ..., size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def wald(self, mean: float, scale: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def wald(
+        self, mean: _ArrayLikeFloat_co, scale: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    @overload
+    def triangular(self, left: float, mode: float, right: float, size: None = ...) -> float: ...  # type: ignore[misc]
+    @overload
+    def triangular(
+        self,
+        left: _ArrayLikeFloat_co,
+        mode: _ArrayLikeFloat_co,
+        right: _ArrayLikeFloat_co,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[float64]]: ...
+    # Complicated, discrete distributions:
+    @overload
+    def binomial(self, n: int, p: float, size: None = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def binomial(
+        self, n: _ArrayLikeInt_co, p: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def negative_binomial(self, n: float, p: float, size: None = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def negative_binomial(
+        self, n: _ArrayLikeFloat_co, p: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def poisson(self, lam: float = ..., size: None = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def poisson(
+        self, lam: _ArrayLikeFloat_co = ..., size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def zipf(self, a: float, size: None = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def zipf(
+        self, a: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def geometric(self, p: float, size: None = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def geometric(
+        self, p: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def hypergeometric(self, ngood: int, nbad: int, nsample: int, size: None = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def hypergeometric(
+        self,
+        ngood: _ArrayLikeInt_co,
+        nbad: _ArrayLikeInt_co,
+        nsample: _ArrayLikeInt_co,
+        size: Optional[_ShapeLike] = ...,
+    ) -> ndarray[Any, dtype[int64]]: ...
+    @overload
+    def logseries(self, p: float, size: None = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def logseries(
+        self, p: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[int64]]: ...
+    # Multivariate distributions:
+    def multivariate_normal(
+        self,
+        mean: _ArrayLikeFloat_co,
+        cov: _ArrayLikeFloat_co,
+        size: Optional[_ShapeLike] = ...,
+        check_valid: Literal["warn", "raise", "ignore"] = ...,
+        tol: float = ...,
+        *,
+        method: Literal["svd", "eigh", "cholesky"] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    def multinomial(
+        self, n: _ArrayLikeInt_co, pvals: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[int64]]: ...
+    def multivariate_hypergeometric(
+        self,
+        colors: _ArrayLikeInt_co,
+        nsample: int,
+        size: Optional[_ShapeLike] = ...,
+        method: Literal["marginals", "count"] = ...,
+    ) -> ndarray[Any, dtype[int64]]: ...
+    def dirichlet(
+        self, alpha: _ArrayLikeFloat_co, size: Optional[_ShapeLike] = ...
+    ) -> ndarray[Any, dtype[float64]]: ...
+    def permuted(
+        self, x: ArrayLike, *, axis: Optional[int] = ..., out: Optional[ndarray[Any, Any]] = ...
+    ) -> ndarray[Any, Any]: ...
+    def shuffle(self, x: ArrayLike, axis: int = ...) -> Sequence[Any]: ...
+
+def default_rng(seed: Union[None, _ArrayLikeInt_co, SeedSequence] = ...) -> Generator: ...
diff --git a/numpy/random/_generator.pyx b/numpy/random/_generator.pyx
index cc7991eb1..a7d98e2ed 100644
--- a/numpy/random/_generator.pyx
+++ b/numpy/random/_generator.pyx
@@ -579,13 +579,13 @@ cdef class Generator:
 
         Returns
         -------
-        out : str
+        out : bytes
             String of length `length`.
 
         Examples
         --------
         >>> np.random.default_rng().bytes(10)
-        ' eh\\x85\\x022SZ\\xbf\\xa4' #random
+        b'\xfeC\x9b\x86\x17\xf2\xa1\xafcp' # random
 
         """
         cdef Py_ssize_t n_uint32 = ((length - 1) // 4 + 1)
@@ -996,7 +996,7 @@ cdef class Generator:
         --------
         >>> rng = np.random.default_rng()
         >>> rng.standard_normal()
-        2.1923875335537315 #random
+        2.1923875335537315 # random
 
         >>> s = rng.standard_normal(8000)
         >>> s
@@ -1755,7 +1755,7 @@ cdef class Generator:
         statistic appear?
 
         >>> np.sum(s<t) / float(len(s))
-        0.0090699999999999999  #random
+        0.0090699999999999999  # random
 
         So the p-value is about 0.009, which says the null hypothesis has a
         probability of about 99% of being true.
@@ -3196,7 +3196,7 @@ cdef class Generator:
         How many trials succeeded after a single run?
 
         >>> (z == 1).sum() / 10000.
-        0.34889999999999999 #random
+        0.34889999999999999 # random
 
         """
         return disc(&random_geometric, &self._bitgen, size, self.lock, 1, 0,
diff --git a/numpy/random/_mt19937.pyi b/numpy/random/_mt19937.pyi
new file mode 100644
index 000000000..1b8bacdae
--- /dev/null
+++ b/numpy/random/_mt19937.pyi
@@ -0,0 +1,28 @@
+import sys
+from typing import Any, Union
+
+from numpy import dtype, ndarray, uint32
+from numpy.random.bit_generator import BitGenerator, SeedSequence
+from numpy.typing import _ArrayLikeInt_co
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+class _MT19937Internal(TypedDict):
+    key: ndarray[Any, dtype[uint32]]
+    pos: int
+
+class _MT19937State(TypedDict):
+    bit_generator: str
+    state: _MT19937Internal
+
+class MT19937(BitGenerator):
+    def __init__(self, seed: Union[None, _ArrayLikeInt_co, SeedSequence] = ...) -> None: ...
+    def _legacy_seeding(self, seed: _ArrayLikeInt_co) -> None: ...
+    def jumped(self, jumps: int = ...) -> MT19937: ...
+    @property
+    def state(self) -> _MT19937State: ...
+    @state.setter
+    def state(self, value: _MT19937State) -> None: ...
diff --git a/numpy/random/_pcg64.pyi b/numpy/random/_pcg64.pyi
new file mode 100644
index 000000000..a4f6e0760
--- /dev/null
+++ b/numpy/random/_pcg64.pyi
@@ -0,0 +1,34 @@
+import sys
+from typing import Union
+
+from numpy.random.bit_generator import BitGenerator, SeedSequence
+from numpy.typing import _ArrayLikeInt_co
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+class _PCG64Internal(TypedDict):
+    state: int
+    inc: int
+
+class _PCG64State(TypedDict):
+    bit_generator: str
+    state: _PCG64Internal
+    has_uint32: int
+    uinteger: int
+
+class PCG64(BitGenerator):
+    def __init__(self, seed: Union[None, _ArrayLikeInt_co, SeedSequence] = ...) -> None: ...
+    def jumped(self, jumps: int = ...) -> PCG64: ...
+    @property
+    def state(
+        self,
+    ) -> _PCG64State: ...
+    @state.setter
+    def state(
+        self,
+        value: _PCG64State,
+    ) -> None: ...
+    def advance(self, delta: int) -> PCG64: ...
diff --git a/numpy/random/_philox.pyi b/numpy/random/_philox.pyi
new file mode 100644
index 000000000..f6a5b9b9b
--- /dev/null
+++ b/numpy/random/_philox.pyi
@@ -0,0 +1,42 @@
+import sys
+from typing import Any, Union
+
+from numpy import dtype, ndarray, uint64
+from numpy.random.bit_generator import BitGenerator, SeedSequence
+from numpy.typing import _ArrayLikeInt_co
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+class _PhiloxInternal(TypedDict):
+    counter: ndarray[Any, dtype[uint64]]
+    key: ndarray[Any, dtype[uint64]]
+
+class _PhiloxState(TypedDict):
+    bit_generator: str
+    state: _PhiloxInternal
+    buffer: ndarray[Any, dtype[uint64]]
+    buffer_pos: int
+    has_uint32: int
+    uinteger: int
+
+class Philox(BitGenerator):
+    def __init__(
+        self,
+        seed: Union[None, _ArrayLikeInt_co, SeedSequence] = ...,
+        counter: Union[None, _ArrayLikeInt_co] = ...,
+        key: Union[None, _ArrayLikeInt_co] = ...,
+    ) -> None: ...
+    @property
+    def state(
+        self,
+    ) -> _PhiloxState: ...
+    @state.setter
+    def state(
+        self,
+        value: _PhiloxState,
+    ) -> None: ...
+    def jumped(self, jumps: int = ...) -> Philox: ...
+    def advance(self, delta: int) -> Philox: ...
diff --git a/numpy/random/_sfc64.pyi b/numpy/random/_sfc64.pyi
new file mode 100644
index 000000000..72a271c92
--- /dev/null
+++ b/numpy/random/_sfc64.pyi
@@ -0,0 +1,34 @@
+import sys
+from typing import Any, Union
+
+from numpy import dtype as dtype
+from numpy import ndarray as ndarray
+from numpy import uint64
+from numpy.random.bit_generator import BitGenerator, SeedSequence
+from numpy.typing import _ArrayLikeInt_co
+
+if sys.version_info >= (3, 8):
+    from typing import TypedDict
+else:
+    from typing_extensions import TypedDict
+
+class _SFC64Internal(TypedDict):
+    state: ndarray[Any, dtype[uint64]]
+
+class _SFC64State(TypedDict):
+    bit_generator: str
+    state: _SFC64Internal
+    has_uint32: int
+    uinteger: int
+
+class SFC64(BitGenerator):
+    def __init__(self, seed: Union[None, _ArrayLikeInt_co, SeedSequence] = ...) -> None: ...
+    @property
+    def state(
+        self,
+    ) -> _SFC64State: ...
+    @state.setter
+    def state(
+        self,
+        value: _SFC64State,
+    ) -> None: ...
diff --git a/numpy/random/bit_generator.pyi b/numpy/random/bit_generator.pyi
new file mode 100644
index 000000000..80a2e829b
--- /dev/null
+++ b/numpy/random/bit_generator.pyi
@@ -0,0 +1,124 @@
+import abc
+import sys
+from threading import Lock
+from typing import (
+    Any,
+    Callable,
+    Dict,
+    List,
+    Mapping,
+    NamedTuple,
+    Optional,
+    Sequence,
+    Tuple,
+    Type,
+    TypedDict,
+    TypeVar,
+    Union,
+    overload,
+)
+
+from numpy import dtype, ndarray, uint32, uint64, unsignedinteger
+from numpy.typing import DTypeLike, _ArrayLikeInt_co, _DTypeLikeUInt, _ShapeLike, _SupportsDType
+
+if sys.version_info >= (3, 8):
+    from typing import Literal
+else:
+    from typing_extensions import Literal
+
+_T = TypeVar("_T")
+
+_UIntType = TypeVar("_UIntType", uint64, uint32)
+_DTypeLike = Union[
+    Type[_UIntType],
+    dtype[_UIntType],
+    _SupportsDType[dtype[_UIntType]],
+]
+
+class _SeedSeqState(TypedDict):
+    entropy: Union[None, int, Sequence[int]]
+    spawn_key: Tuple[int, ...]
+    pool_size: int
+    n_children_spawned: int
+
+class _Interface(NamedTuple):
+    state_address: Any
+    state: Any
+    next_uint64: Any
+    next_uint32: Any
+    next_double: Any
+    bit_generator: Any
+
+class ISeedSequence(abc.ABC):
+    @overload
+    @abc.abstractmethod
+    def generate_state(
+        self, n_words: int, dtype: _DTypeLike[_UIntType] = ...
+    ) -> ndarray[Any, dtype[_UIntType]]: ...
+    @overload
+    @abc.abstractmethod
+    def generate_state(
+        self, n_words: int, dtype: _DTypeLikeUInt = ...
+    ) -> ndarray[Any, dtype[unsignedinteger[Any]]]: ...
+
+class ISpawnableSeedSequence(ISeedSequence):
+    @abc.abstractmethod
+    def spawn(self: _T, n_children: int) -> List[_T]: ...
+
+class SeedlessSeedSequence(ISpawnableSeedSequence):
+    @overload
+    def generate_state(
+        self, n_words: int, dtype: _DTypeLike[_UIntType] = ...
+    ) -> ndarray[Any, dtype[_UIntType]]: ...
+    @overload
+    def generate_state(
+        self, n_words: int, dtype: _DTypeLikeUInt = ...
+    ) -> ndarray[Any, dtype[unsignedinteger[Any]]]: ...
+    def spawn(self: _T, n_children: int) -> List[_T]: ...
+
+class SeedSequence(ISpawnableSeedSequence):
+    entropy: Union[None, int, Sequence[int]]
+    spawn_key: Tuple[int, ...]
+    pool_size: int
+    n_children_spawned: int
+    pool: ndarray[Any, dtype[uint32]]
+    def __init__(
+        self,
+        entropy: Union[None, int, Sequence[int]] = ...,
+        *,
+        spawn_key: Sequence[int] = ...,
+        pool_size: int = ...,
+        n_children_spawned: int = ...,
+    ) -> None: ...
+    def __repr__(self) -> str: ...
+    @property
+    def state(
+        self,
+    ) -> _SeedSeqState: ...
+    def generate_state(self, n_words: int, dtype: DTypeLike = ...) -> ndarray[Any, Any]: ...
+    def spawn(self, n_children: int) -> List[SeedSequence]: ...
+
+class BitGenerator(abc.ABC):
+    lock: Lock
+    def __init__(self, seed: Union[None, _ArrayLikeInt_co, SeedSequence] = ...) -> None: ...
+    def __getstate__(self) -> Dict[str, Any]: ...
+    def __setstate__(self, state: Dict[str, Any]) -> None: ...
+    def __reduce__(
+        self,
+    ) -> Tuple[Callable[[str], BitGenerator], Tuple[str], Tuple[Dict[str, Any]]]: ...
+    @abc.abstractmethod
+    @property
+    def state(self) -> Mapping[str, Any]: ...
+    @state.setter
+    def state(self, value: Mapping[str, Any]) -> None: ...
+    @overload
+    def random_raw(self, size: None = ..., output: Literal[True] = ...) -> int: ...  # type: ignore[misc]
+    @overload
+    def random_raw(self, size: _ShapeLike = ..., output: Literal[True] = ...) -> ndarray[Any, dtype[uint64]]: ...  # type: ignore[misc]
+    @overload
+    def random_raw(self, size: Optional[_ShapeLike] = ..., output: Literal[False] = ...) -> None: ...  # type: ignore[misc]
+    def _benchmark(self, cnt: int, method: str = ...) -> None: ...
+    @property
+    def ctypes(self) -> _Interface: ...
+    @property
+    def cffi(self) -> _Interface: ...