Merge branch 'master' into refactor_submodule_exports

Author: vlad-perevezentsev

CHANGELOG.md

@@ -33,11 +33,13 @@ Also, that release drops support for Python 3.9, making Python 3.10 the minimum
 * Added the missing positional-only and keyword-only parameter markers to bring the ufunc signatures into alignment with NumPy [#2660](https://github.com/IntelPython/dpnp/pull/2660)
 * Redesigned `dpnp.modf` function to be a part of `ufunc` and `vm` pybind11 extensions [#2654](https://github.com/IntelPython/dpnp/pull/2654)
 * Refactored `dpnp.fft` and `dpnp.random` submodules by removing wildcard imports and defining explicit public exports [#2649](https://github.com/IntelPython/dpnp/pull/2649)
+* Added support for the `out` keyword to accept a tuple, bringing ufunc signatures into alignment with those in NumPy [#2664](https://github.com/IntelPython/dpnp/pull/2664)
 * Unified public API definitions in `dpnp.linalg` and `dpnp.scipy` submodules [#2663](https://github.com/IntelPython/dpnp/pull/2663)
 
 ### Deprecated
 
 * `dpnp.asfarray` is deprecated. Use `dpnp.asarray` with an appropriate dtype instead [#2650](https://github.com/IntelPython/dpnp/pull/2650)
+* Passing the output array ``out`` positionally to `dpnp.minimum` and `dpnp.maximum` is deprecated. Pass the output with the keyword form, e.g. ``dpnp.minimum(a, b, out=c)`` [#2659](https://github.com/IntelPython/dpnp/pull/2659)
 
 ### Removed
 

doc/conf.py

@@ -12,6 +12,7 @@
 
 from dpnp.dpnp_algo.dpnp_elementwise_common import (
     DPNPBinaryFunc,
+    DPNPBinaryFuncOutKw,
     DPNPUnaryFunc,
     DPNPUnaryTwoOutputsFunc,
 )
@@ -210,7 +211,13 @@
 # -- Options for todo extension ----------------------------------------------
 def _can_document_member(member, *args, **kwargs):
     if isinstance(
-        member, (DPNPBinaryFunc, DPNPUnaryFunc, DPNPUnaryTwoOutputsFunc)
+        member,
+        (
+            DPNPBinaryFunc,
+            DPNPBinaryFuncOutKw,
+            DPNPUnaryFunc,
+            DPNPUnaryTwoOutputsFunc,
+        ),
     ):
         return True
     return orig(member, *args, **kwargs)

dpnp/dpnp_algo/dpnp_elementwise_common.py

@@ -26,6 +26,9 @@
 # THE POSSIBILITY OF SUCH DAMAGE.
 # *****************************************************************************
 
+import warnings
+from functools import wraps
+
 import dpctl.tensor as dpt
 import dpctl.tensor._copy_utils as dtc
 import dpctl.tensor._tensor_impl as dti
@@ -48,6 +51,7 @@
     "DPNPI0",
     "DPNPAngle",
     "DPNPBinaryFunc",
+    "DPNPBinaryFuncOutKw",
     "DPNPFix",
     "DPNPImag",
     "DPNPReal",
@@ -199,13 +203,25 @@ def __call__(
         if dtype is not None:
             x_usm = dpt.astype(x_usm, dtype, copy=False)
 
+        out = self._unpack_out_kw(out)
         out_usm = None if out is None else dpnp.get_usm_ndarray(out)
-        res_usm = super().__call__(x_usm, out=out_usm, order=order)
 
+        res_usm = super().__call__(x_usm, out=out_usm, order=order)
         if out is not None and isinstance(out, dpnp_array):
             return out
         return dpnp_array._create_from_usm_ndarray(res_usm)
 
+    def _unpack_out_kw(self, out):
+        """Unpack `out` keyword if passed as a tuple."""
+
+        if isinstance(out, tuple):
+            if len(out) != self.nout:
+                raise ValueError(
+                    "'out' tuple must have exactly one entry per ufunc output"
+                )
+            return out[0]
+        return out
+
 
 class DPNPUnaryTwoOutputsFunc(UnaryElementwiseFunc):
     """
@@ -361,7 +377,7 @@ def __call__(
         orig_out, out = list(out), list(out)
         res_dts = [res1_dt, res2_dt]
 
-        for i in range(2):
+        for i in range(self.nout):
             if out[i] is None:
                 continue
 
@@ -419,7 +435,7 @@ def __call__(
             dep_evs = copy_ev
 
         # Allocate a buffer for the output arrays if needed
-        for i in range(2):
+        for i in range(self.nout):
             if out[i] is None:
                 res_dt = res_dts[i]
                 if order == "K":
@@ -438,7 +454,7 @@ def __call__(
         )
         _manager.add_event_pair(ht_unary_ev, unary_ev)
 
-        for i in range(2):
+        for i in range(self.nout):
             orig_res, res = orig_out[i], out[i]
             if not (orig_res is None or orig_res is res):
                 # Copy the out data from temporary buffer to original memory
@@ -606,6 +622,13 @@ def __call__(
 
         x1_usm = dpnp.get_usm_ndarray_or_scalar(x1)
         x2_usm = dpnp.get_usm_ndarray_or_scalar(x2)
+
+        if isinstance(out, tuple):
+            if len(out) != self.nout:
+                raise ValueError(
+                    "'out' tuple must have exactly one entry per ufunc output"
+                )
+            out = out[0]
         out_usm = None if out is None else dpnp.get_usm_ndarray(out)
 
         if (
@@ -756,6 +779,22 @@ def outer(
         )
 
 
+class DPNPBinaryFuncOutKw(DPNPBinaryFunc):
+    """DPNPBinaryFunc that deprecates positional `out` argument."""
+
+    @wraps(DPNPBinaryFunc.__call__)
+    def __call__(self, *args, **kwargs):
+        if len(args) > self.nin:
+            warnings.warn(
+                "Passing more than 2 positional arguments is deprecated. "
+                "If you meant to use the third argument as an output, "
+                "use the `out` keyword argument instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+        return super().__call__(*args, **kwargs)
+
+
 class DPNPAngle(DPNPUnaryFunc):
     """Class that implements dpnp.angle unary element-wise functions."""
 
@@ -806,15 +845,22 @@ def __call__(self, x, /, out=None, *, order="K"):
             pass  # pass to raise error in main implementation
         elif dpnp.issubdtype(x.dtype, dpnp.inexact):
             pass  # for inexact types, pass to calculate in the backend
-        elif out is not None and not dpnp.is_supported_array_type(out):
+        elif not (
+            out is None
+            or isinstance(out, tuple)
+            or dpnp.is_supported_array_type(out)
+        ):
             pass  # pass to raise error in main implementation
-        elif out is not None and out.dtype != x.dtype:
+        elif not (
+            out is None or isinstance(out, tuple) or out.dtype == x.dtype
+        ):
             # passing will raise an error but with incorrect needed dtype
             raise ValueError(
                 f"Output array of type {x.dtype} is needed, got {out.dtype}"
             )
         else:
             # for exact types, return the input
+            out = self._unpack_out_kw(out)
             if out is None:
                 return dpnp.copy(x, order=order)
 
@@ -919,6 +965,7 @@ def __init__(
     def __call__(self, x, /, decimals=0, out=None, *, dtype=None):
         if decimals != 0:
             x_usm = dpnp.get_usm_ndarray(x)
+            out = self._unpack_out_kw(out)
             out_usm = None if out is None else dpnp.get_usm_ndarray(out)
 
             if dpnp.issubdtype(x_usm.dtype, dpnp.integer):

dpnp/dpnp_iface_bitwise.py

@@ -144,9 +144,11 @@ def binary_repr(num, width=None):
     First input array, expected to have an integer or boolean data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
     Second input array, also expected to have an integer or boolean data type.
-out : {None, dpnp.ndarray, usm_ndarray}, optional
+out : {None, dpnp.ndarray, usm_ndarray, tuple of ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
+    A tuple (possible only as a keyword argument) must have length equal to the
+    number of outputs.
 
     Default: ``None``.
 order : {None, "C", "F", "A", "K"}, optional
@@ -233,9 +235,11 @@ def binary_repr(num, width=None):
 ----------
 x : {dpnp.ndarray, usm_ndarray}
     Input array, expected to have an integer data type.
-out : {None, dpnp.ndarray, usm_ndarray}, optional
+out : {None, dpnp.ndarray, usm_ndarray, tuple of ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
+    A tuple (possible only as a keyword argument) must have length equal to the
+    number of outputs.
 
     Default: ``None``.
 order : {None, "C", "F", "A", "K"}, optional
@@ -290,9 +294,11 @@ def binary_repr(num, width=None):
     First input array, expected to have an integer or boolean data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
     Second input array, also expected to have an integer or boolean data type.
-out : {None, dpnp.ndarray, usm_ndarray}, optional
+out : {None, dpnp.ndarray, usm_ndarray, tuple of ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
+    A tuple (possible only as a keyword argument) must have length equal to the
+    number of outputs.
 
     Default: ``None``.
 order : {None, "C", "F", "A", "K"}, optional
@@ -374,9 +380,11 @@ def binary_repr(num, width=None):
     First input array, expected to have an integer or boolean data type.
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
     Second input array, also expected to have an integer or boolean data type.
-out : {None, dpnp.ndarray, usm_ndarray}, optional
+out : {None, dpnp.ndarray, usm_ndarray, tuple of ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
+    A tuple (possible only as a keyword argument) must have length equal to the
+    number of outputs.
 
     Default: ``None``.
 order : {None, "C", "F", "A", "K"}, optional
@@ -460,9 +468,11 @@ def binary_repr(num, width=None):
 ----------
 x : {dpnp.ndarray, usm_ndarray}
     Input array, expected to have an integer or boolean data type.
-out : {None, dpnp.ndarray, usm_ndarray}, optional
+out : {None, dpnp.ndarray, usm_ndarray, tuple of ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
+    A tuple (possible only as a keyword argument) must have length equal to the
+    number of outputs.
 
     Default: ``None``.
 order : {None, "C", "F", "A", "K"}, optional
@@ -544,9 +554,11 @@ def binary_repr(num, width=None):
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
     Second input array, also expected to have an integer data type.
     Each element must be greater than or equal to ``0``.
-out : {None, dpnp.ndarray, usm_ndarray}, optional
+out : {None, dpnp.ndarray, usm_ndarray, tuple of ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
+    A tuple (possible only as a keyword argument) must have length equal to the
+    number of outputs.
 
     Default: ``None``.
 order : {None, "C", "F", "A", "K"}, optional
@@ -627,9 +639,11 @@ def binary_repr(num, width=None):
 x2 : {dpnp.ndarray, usm_ndarray, scalar}
     Second input array, also expected to have an integer data type.
     Each element must be greater than or equal to ``0``.
-out : {None, dpnp.ndarray, usm_ndarray}, optional
+out : {None, dpnp.ndarray, usm_ndarray, tuple of ndarray}, optional
     Output array to populate.
     Array must have the correct shape and the expected data type.
+    A tuple (possible only as a keyword argument) must have length equal to the
+    number of outputs.
 
     Default: ``None``.
 order : {None, "C", "F", "A", "K"}, optional