fix: patching to match mkl_fft, lint, and review

Author: jharlow-intel

.pylintrc

@@ -0,0 +1,5 @@
+[MASTER]
+extension-pkg-allow-list=numpy,mkl_random.mklrand
+
+[TYPECHECK]
+generated-members=RandomState,min,max

mkl_random/__init__.py

@@ -93,9 +93,19 @@
     test = PytestTester(__name__)
     del PytestTester
 
-from ._patch import monkey_patch, use_in_numpy, restore, is_patched, patched_names, mkl_random
 from mkl_random import interfaces
 
+from ._patch import (
+    is_patched,
+    mkl_random,
+    monkey_patch,
+    patch_numpy_random,
+    patched_names,
+    restore,
+    restore_numpy_random,
+    use_in_numpy,
+)
+
 __all__ = [
     "MKLRandomState",
     "RandomState",

mkl_random/_patch.py

@@ -0,0 +1,348 @@
+# Copyright (c) 2019, 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.
+
+"""Define functions for patching NumPy with MKL-based NumPy interface."""
+
+from contextlib import ContextDecorator
+from threading import Lock, local
+
+import numpy as _np
+
+from . import mklrand as _mr
+
+
+_DEFAULT_NAMES = (
+    # Legacy seeding / state
+    "seed",
+    "get_state",
+    "set_state",
+    "RandomState",
+    # Common global sampling helpers
+    "random",
+    "random_sample",
+    "sample",
+    "rand",
+    "randn",
+    "bytes",
+    # Integers
+    "randint",
+    # Common distributions (only patched if present on both sides)
+    "standard_normal",
+    "normal",
+    "uniform",
+    "exponential",
+    "gamma",
+    "beta",
+    "chisquare",
+    "f",
+    "lognormal",
+    "laplace",
+    "logistic",
+    "multivariate_normal",
+    "poisson",
+    "power",
+    "rayleigh",
+    "triangular",
+    "vonmises",
+    "wald",
+    "weibull",
+    "zipf",
+    # Permutations / choices
+    "choice",
+    "permutation",
+    "shuffle",
+)
+
+
+class _GlobalPatch:
+    def __init__(self):
+        self._lock = Lock()
+        self._patch_count = 0
+        self._restore_dict = {}
+        self._patched_functions = tuple(_DEFAULT_NAMES)
+        self._numpy_module = None
+        self._requested_names = None
+        self._active_names = ()
+        self._patched = ()
+        self._tls = local()
+
+    def _normalize_names(self, names):
+        if names is None:
+            names = _DEFAULT_NAMES
+        return tuple(names)
+
+    def _validate_module(self, numpy_module):
+        if not hasattr(numpy_module, "random"):
+            raise TypeError(
+                "Expected a numpy-like module with a `.random` attribute."
+            )
+
+    def _register_func(self, name, func):
+        if name not in self._patched_functions:
+            raise ValueError(f"{name} not an mkl_random function.")
+        np_random = self._numpy_module.random
+        if name not in self._restore_dict:
+            self._restore_dict[name] = getattr(np_random, name)
+        setattr(np_random, name, func)
+
+    def _restore_func(self, name, verbose=False):
+        if name not in self._patched_functions:
+            raise ValueError(f"{name} not an mkl_random function.")
+        try:
+            val = self._restore_dict[name]
+        except KeyError:
+            if verbose:
+                print(f"failed to restore {name}")
+            return
+        else:
+            if verbose:
+                print(f"found and restoring {name}...")
+            np_random = self._numpy_module.random
+            setattr(np_random, name, val)
+
+    def _initialize_patch(self, numpy_module, names, strict):
+        self._validate_module(numpy_module)
+        np_random = numpy_module.random
+        missing = []
+        patchable = []
+        for name in names:
+            if name not in self._patched_functions:
+                missing.append(name)
+                continue
+            if not hasattr(np_random, name) or not hasattr(_mr, name):
+                missing.append(name)
+                continue
+            patchable.append(name)
+
+        if strict and missing:
+            raise AttributeError(
+                "Could not patch these names (missing on numpy.random or "
+                "mkl_random.mklrand): "
+                + ", ".join([str(x) for x in missing])
+            )
+
+        self._numpy_module = numpy_module
+        self._requested_names = names
+        self._active_names = tuple(patchable)
+        self._patched = tuple(patchable)
+
+    def do_patch(
+        self,
+        numpy_module=None,
+        names=None,
+        strict=False,
+        verbose=False,
+    ):
+        if numpy_module is None:
+            numpy_module = _np
+        names = self._normalize_names(names)
+        strict = bool(strict)
+
+        with self._lock:
+            local_count = getattr(self._tls, "local_count", 0)
+            if self._patch_count == 0:
+                self._initialize_patch(numpy_module, names, strict)
+                if verbose:
+                    print(
+                        "Now patching NumPy random submodule with mkl_random "
+                        "NumPy interface."
+                    )
+                    print(
+                        "Please direct bug reports to "
+                        "https://github.com/IntelPython/mkl_random"
+                    )
+                for name in self._active_names:
+                    self._register_func(name, getattr(_mr, name))
+            else:
+                if self._numpy_module is not numpy_module:
+                    raise RuntimeError(
+                        "Already patched a different numpy module; "
+                        "call restore() first."
+                    )
+                if names != self._requested_names:
+                    raise RuntimeError(
+                        "Already patched with a different names set; "
+                        "call restore() first."
+                    )
+            self._patch_count += 1
+            self._tls.local_count = local_count + 1
+
+    def do_restore(self, verbose=False):
+        with self._lock:
+            local_count = getattr(self._tls, "local_count", 0)
+            if local_count <= 0:
+                if verbose:
+                    print(
+                        "Warning: restore_numpy_random called more times than "
+                        "patch_numpy_random in this thread."
+                    )
+                return
+
+            self._tls.local_count = local_count - 1
+            self._patch_count -= 1
+            if self._patch_count == 0:
+                if verbose:
+                    print("Now restoring original NumPy random submodule.")
+                for name in tuple(self._restore_dict):
+                    self._restore_func(name, verbose=verbose)
+                self._restore_dict.clear()
+                self._numpy_module = None
+                self._requested_names = None
+                self._active_names = ()
+                self._patched = ()
+
+    def is_patched(self):
+        with self._lock:
+            return self._patch_count > 0
+
+    def patched_names(self):
+        with self._lock:
+            return list(self._patched)
+
+
+_patch = _GlobalPatch()
+
+
+def patch_numpy_random(
+    numpy_module=None,
+    names=None,
+    strict=False,
+    verbose=False,
+):
+    """
+    Patch NumPy's random submodule with mkl_random's NumPy interface.
+
+    Parameters
+    ----------
+    numpy_module : module, optional
+        NumPy-like module to patch. Defaults to imported NumPy.
+    names : iterable[str], optional
+        Attributes under `numpy_module.random` to patch.
+    strict : bool, optional
+        Raise if any requested symbol cannot be patched.
+    verbose : bool, optional
+        Print messages when starting the patching process.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import mkl_random
+    >>> mkl_random.is_patched()
+    False
+    >>> mkl_random.patch_numpy_random(np)
+    >>> mkl_random.is_patched()
+    True
+    >>> mkl_random.restore()
+    >>> mkl_random.is_patched()
+    False
+    """
+    _patch.do_patch(
+        numpy_module=numpy_module,
+        names=names,
+        strict=bool(strict),
+        verbose=bool(verbose),
+    )
+
+
+def restore_numpy_random(verbose=False):
+    """
+    Restore NumPy's random submodule to its original implementations.
+
+    Parameters
+    ----------
+    verbose : bool, optional
+        Print message when starting restoration process.
+    """
+    _patch.do_restore(verbose=bool(verbose))
+
+
+def monkey_patch(numpy_module=None, names=None, strict=False, verbose=False):
+    """Backward-compatible alias for patch_numpy_random()."""
+    patch_numpy_random(
+        numpy_module=numpy_module,
+        names=names,
+        strict=strict,
+        verbose=verbose,
+    )
+
+
+def use_in_numpy(numpy_module=None, names=None, strict=False, verbose=False):
+    """Backward-compatible alias for patch_numpy_random()."""
+    patch_numpy_random(
+        numpy_module=numpy_module,
+        names=names,
+        strict=strict,
+        verbose=verbose,
+    )
+
+
+def restore(verbose=False):
+    """Backward-compatible alias for restore_numpy_random()."""
+    restore_numpy_random(verbose=verbose)
+
+
+def is_patched():
+    """
+    Returns whether NumPy has been patched with mkl_random.
+    """
+    return _patch.is_patched()
+
+
+def patched_names():
+    """
+    Returns the names actually patched in `numpy.random`.
+    """
+    return _patch.patched_names()
+
+
+class mkl_random(ContextDecorator):
+    """
+    Context manager and decorator to temporarily patch NumPy random submodule
+    with MKL-based implementations.
+
+    Examples
+    --------
+    >>> import numpy as np
+    >>> import mkl_random
+    >>> with mkl_random.mkl_random(np):
+    ...     x = np.random.normal(size=10)
+    """
+
+    def __init__(self, numpy_module=None, names=None, strict=False):
+        self._numpy_module = numpy_module
+        self._names = names
+        self._strict = strict
+
+    def __enter__(self):
+        patch_numpy_random(
+            numpy_module=self._numpy_module,
+            names=self._names,
+            strict=self._strict,
+        )
+        return self
+
+    def __exit__(self, *exc):
+        restore_numpy_random()
+        return False