Deprecate positional out argument in dpnp.minimum and dpnp.maximum

CHANGELOG.md

@@ -33,6 +33,7 @@ Also, that release drops support for Python 3.9, making Python 3.10 the minimum
 ### 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
 

dpnp/dpnp_iface_mathematical.py

@@ -46,6 +46,7 @@
 
 import builtins
 import warnings
+from functools import wraps
 
 import dpctl.tensor as dpt
 import dpctl.tensor._tensor_elementwise_impl as ti
@@ -3202,6 +3203,14 @@ def interp(x, xp, fp, left=None, right=None, period=None):
 
     Default: ``"K"``.
 
+Warning
+-------
+Passing the output array ``out`` positionally is deprecated.
+For example, ``dpnp.maximum(a, b, c)`` will emit a ``DeprecationWarning``.
+
+Always pass the output with the keyword form, e.g.
+``dpnp.maximum(a, b, out=c)``.
+
 Returns
 -------
 out : dpnp.ndarray
@@ -3255,14 +3264,31 @@ def interp(x, xp, fp, left=None, right=None, period=None):
 
 """
 
-maximum = DPNPBinaryFunc(
+_maximum_impl = DPNPBinaryFunc(
     "maximum",
     ti._maximum_result_type,
     ti._maximum,
     _MAXIMUM_DOCSTRING,
 )
 
 
+@wraps(_maximum_impl)
+def maximum(*args, **kwargs):
+    """
+    Wrapper around `_maximum_impl` that emits a DeprecationWarning
+    when `out` is passed positionally.
+
+    """
+    if len(args) >= 3 and "out" not in kwargs:
+        warnings.warn(
+            "Positional `out` argument to `dpnp.maximum` is deprecated. "
+            "Please use the keyword form, e.g. `dpnp.maximum(a, b, out=c)`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    return _maximum_impl(*args, **kwargs)
+
+
 _MINIMUM_DOCSTRING = """
 Computes the minimum value for each element :math:`x1_i` of the input array `x1`
 relative to the respective element :math:`x2_i` of the input array `x2`.
@@ -3297,6 +3323,14 @@ def interp(x, xp, fp, left=None, right=None, period=None):
     An array containing the element-wise minima. The data type of
     the returned array is determined by the Type Promotion Rules.
 
+Warning
+-------
+Passing the output array ``out`` positionally is deprecated.
+For example, ``dpnp.minimum(a, b, c)`` will emit a ``DeprecationWarning``.
+
+Always pass the output with the keyword form, e.g.
+``dpnp.minimum(a, b, out=c)``.
+
 Limitations
 -----------
 Parameters `where` and `subok` are supported with their default values.
@@ -3343,14 +3377,31 @@ def interp(x, xp, fp, left=None, right=None, period=None):
 array(-inf)
 """
 
-minimum = DPNPBinaryFunc(
+_minimum_impl = DPNPBinaryFunc(
     "minimum",
     ti._minimum_result_type,
     ti._minimum,
     _MINIMUM_DOCSTRING,
 )
 
 
+@wraps(_minimum_impl)
+def minimum(*args, **kwargs):
+    """
+    Wrapper around `_minimum_impl` that emits a DeprecationWarning
+    when `out` is passed positionally.
+
+    """
+    if len(args) >= 3 and "out" not in kwargs:
+        warnings.warn(
+            "Positional `out` argument to `dpnp.minimum` is deprecated. "
+            "Please use the keyword form, e.g. `dpnp.minimum(a, b, out=c)`.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+    return _minimum_impl(*args, **kwargs)
+
+
 def modf(x1, **kwargs):
     """
     Return the fractional and integral parts of an array, element-wise.

dpnp/tests/test_mathematical.py

@@ -2910,3 +2910,13 @@ def test_elemenwise_outer_scalar():
     expected = dpnp.add.outer(x, y)
     result = dpnp.add.outer(x, s)
     assert dpnp.allclose(result, expected)
+
+
+@pytest.mark.parametrize("func", ["minimum", "maximum"])
+def test_minimum_maximum_out_deprecated(func):
+    a = dpnp.array([1, 3, 2])
+    b = dpnp.array([2, 2, 2])
+    out = dpnp.empty_like(a)
+
+    with pytest.warns(DeprecationWarning, match="deprecated"):
+        _ = getattr(dpnp, func)(a, b, out)