Implement mkl_random.interfaces and update mkl_random

.git-blame-ignore-revs

@@ -0,0 +1,4 @@
+# $ git config blame.ignoreRevsFile .git-blame-ignore-revs
+
+# Sporadic fixes in test_random.py
+e76aa3a5a4b889c0434f0103ec102a50b93ab1ca

CHANGELOG.md

@@ -6,9 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [dev] (MM/DD/YYYY)
 
+### Added
+* Added `mkl_random.interfaces` with `mkl_random.interfaces.numpy_random` interface, which aliases `mkl_random` functionality to more strictly adhere to NumPy's API (i.e., drops arguments and functions which are not part of standard NumPy) [gh-92](https://github.com/IntelPython/mkl_random/pull/92)
+
 ### Removed
 * Dropped support for Python 3.9 [gh-81](https://github.com/IntelPython/mkl_random/pull/81)
 
+### Deprecated
+* Deprecated `mkl_random.RandomState` in favor of `mkl_random.MKLRandomState`, delegating `mkl_random.RandomState` to the `mkl_random.interfaces.numpy_random` interface [gh-92](https://github.com/IntelPython/mkl_random/pull/92)
+
 ## [1.3.1] (12/02/2025)
 
 ### Added

mkl_random/__init__.py

@@ -1,4 +1,3 @@
-#!/usr/bin/env python
 # Copyright (c) 2017, Intel Corporation
 #
 # Redistribution and use in source and binary forms, with or without
@@ -28,7 +27,58 @@
 
 from . import _init_helper
 
-from .mklrand import *
+from .mklrand import (
+    MKLRandomState,
+    RandomState,
+    seed,
+    get_state,
+    set_state,
+    random_sample,
+    choice,
+    randint,
+    bytes,
+    uniform,
+    rand,
+    randn,
+    random_integers,
+    standard_normal,
+    normal,
+    beta,
+    exponential,
+    standard_exponential,
+    standard_gamma,
+    gamma,
+    f,
+    noncentral_f,
+    chisquare,
+    noncentral_chisquare,
+    standard_cauchy,
+    standard_t,
+    vonmises,
+    pareto,
+    weibull,
+    power,
+    laplace,
+    gumbel,
+    logistic,
+    lognormal,
+    rayleigh,
+    wald,
+    triangular,
+    binomial,
+    negative_binomial,
+    poisson,
+    zipf,
+    geometric,
+    hypergeometric,
+    logseries,
+    multivariate_normal,
+    multinormal_cholesky,
+    multinomial,
+    dirichlet,
+    shuffle,
+    permutation,
+)
 from ._version import __version__
 
 try:
@@ -42,4 +92,60 @@
     test = PytestTester(__name__)
     del PytestTester
 
+from mkl_random import interfaces
+
+__all__ = [
+    "MKLRandomState",
+    "RandomState",
+    "seed",
+    "get_state",
+    "set_state",
+    "random_sample",
+    "choice",
+    "randint",
+    "bytes",
+    "uniform",
+    "rand",
+    "randn",
+    "random_integers",
+    "standard_normal",
+    "normal",
+    "beta",
+    "exponential",
+    "standard_exponential",
+    "standard_gamma",
+    "gamma",
+    "f",
+    "noncentral_f",
+    "chisquare",
+    "noncentral_chisquare",
+    "standard_cauchy",
+    "standard_t",
+    "vonmises",
+    "pareto",
+    "weibull",
+    "power",
+    "laplace",
+    "gumbel",
+    "logistic",
+    "lognormal",
+    "rayleigh",
+    "wald",
+    "triangular",
+    "binomial",
+    "negative_binomial",
+    "poisson",
+    "zipf",
+    "geometric",
+    "hypergeometric",
+    "logseries",
+    "multivariate_normal",
+    "multinormal_cholesky",
+    "multinomial",
+    "dirichlet",
+    "shuffle",
+    "permutation",
+    "interfaces",
+]
+
 del _init_helper

mkl_random/interfaces/README.md

@@ -0,0 +1,18 @@
+# Interfaces
+The `mkl_random` package provides interfaces that serve as drop-in replacements for equivalent functions in NumPy.
+
+---
+
+## NumPy interface - `mkl_random.interfaces.numpy_random`
+
+This interface is a drop-in replacement for the legacy portion of the [`numpy.random`](https://numpy.org/devdocs/reference/random/legacy.html) module and includes **all** classes and functions available there:
+
+* random generator: `RandomState`.
+
+* seeding and state functions: `get_state`, `set_state`, and `seed`.
+
+* simple random data: `rand`, `randn`, `randint`, `random_integers`, `random_sample`, `choice` and `bytes`.
+
+* permutations: `shuffle` and `permutation`
+
+* distributions: `beta`, `binomial`, `chisquare`, `dirichlet`, `exponential`, `f`, `gamma`, `geometric`, `gumbel`, `hypergeometric`, `laplace`, `logistic`, `lognormal`, `logseries`, `multinomial`, `multivariate_normal`, `negative_binomial`, `noncentral_chisquare`, `noncentral_f`, `normal`, `pareto`, `poisson`, `power`, `rayleigh`, `standard_cauchy`, `standard_exponential`, `standard_gamma`, `standard_normal`, `standard_t`, `triangular`, `uniform`, `vonmises`, `wald`, `weibull`, and `zipf`.

mkl_random/interfaces/__init__.py

@@ -0,0 +1,29 @@
+# Copyright (c) 2017, Intel Corporation
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+#     * Redistributions of source code must retain the above copyright notice,
+#       this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above copyright
+#       notice, this list of conditions and the following disclaimer in the
+#       documentation and/or other materials provided with the distribution.
+#     * Neither the name of Intel Corporation nor the names of its contributors
+#       may be used to endorse or promote products derived from this software
+#       without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+from . import numpy_random
+
+# submodules
+__all__ = ["numpy_random"]