DEPR: add visible deprecation warnings to obsolete special wrappers

unyt/_deprecation.py

@@ -0,0 +1,22 @@
+import warnings
+from typing import Optional
+
+
+def warn_deprecated(
+    name,
+    /,
+    *,
+    stacklevel: int = 3,
+    replacement: Optional[str] = None,
+    since_version: str,
+) -> None:
+    msg = (
+        f"{name} is deprecated and will be removed in a future version\n"
+        f"Instead, {replacement}\n"
+        f"(deprecated since unyt v{since_version})"
+    )
+    warnings.warn(
+        msg,
+        category=DeprecationWarning,
+        stacklevel=stacklevel,
+    )

unyt/array.py

@@ -134,6 +134,8 @@
     default_unit_registry,
 )
 
+from ._deprecation import warn_deprecated
+
 NULL_UNIT = Unit()
 POWER_MAPPING = {multiply: lambda x: x, divide: lambda x: 2 - x}
 
@@ -2216,6 +2218,10 @@ def uconcatenate(arrs, axis=0):
     unyt_array([1, 2, 3, 2, 3, 4], 'cm')
 
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.uconcatenate", replacement="use numpy.concatenate", since_version="2.10"
+    # )
     v = np.concatenate(arrs, axis=axis)
     v = _validate_numpy_wrapper_units(v, arrs)
     return v
@@ -2228,6 +2234,10 @@ def ucross(arr1, arr2, registry=None, axisa=-1, axisb=-1, axisc=-1, axis=None):
     See the documentation of numpy.cross for full
     details.
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.ucross", replacement="use numpy.cross", since_version="2.10"
+    # )
     v = np.cross(arr1, arr2, axisa=axisa, axisb=axisb, axisc=axisc, axis=axis)
     units = arr1.units * arr2.units
     arr = unyt_array(v, units, registry=registry)
@@ -2250,6 +2260,10 @@ def uintersect1d(arr1, arr2, assume_unique=False):
     unyt_array([2, 3], 'cm')
 
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.uintersect1d", replacement="use numpy.intersect1d", since_version="2.10"
+    # )
     v = np.intersect1d(arr1, arr2, assume_unique=assume_unique)
     v = _validate_numpy_wrapper_units(v, [arr1, arr2])
     return v
@@ -2271,6 +2285,10 @@ def uunion1d(arr1, arr2):
     unyt_array([1, 2, 3, 4], 'cm')
 
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.uunion1d", replacement="use numpy.union1d", since_version="2.10"
+    # )
     v = np.union1d(arr1, arr2)
     v = _validate_numpy_wrapper_units(v, [arr1, arr2])
     return v
@@ -2290,6 +2308,10 @@ def unorm(data, ord=None, axis=None, keepdims=False):
     >>> print(unorm(data))
     3.7416573867739413 km
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.unorm", replacement="use numpy.norm", since_version="2.10"
+    # )
     norm = np.linalg.norm(data, ord=ord, axis=axis, keepdims=keepdims)
     if norm.shape == ():
         return unyt_quantity(norm, data.units)
@@ -2310,6 +2332,7 @@ def udot(op1, op2):
     [[2. 2.]
      [2. 2.]] km*s
     """
+    warn_deprecated("unyt.udot", replacement="use numpy.dot", since_version="2.10")
     dot = np.dot(op1.d, op2.d)
     units = op1.units * op2.units
     if dot.shape == ():
@@ -2331,6 +2354,10 @@ def uvstack(arrs):
     [[1 2 3]
      [2 3 4]] km
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.uvstack", replacement="use numpy.vstack", since_version="2.10"
+    # )
     v = np.vstack(arrs)
     v = _validate_numpy_wrapper_units(v, arrs)
     return v
@@ -2355,6 +2382,10 @@ def uhstack(arrs):
      [2 3]
      [3 4]] km
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.uhstack", replacement="use numpy.hstack", since_version="2.10"
+    # )
     v = np.hstack(arrs)
     v = _validate_numpy_wrapper_units(v, arrs)
     return v
@@ -2379,6 +2410,10 @@ def ustack(arrs, axis=0):
     [[1 2 3]
      [2 3 4]] km
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.ustack", replacement="use numpy.stack", since_version="2.10"
+    # )
     v = np.stack(arrs, axis=axis)
     v = _validate_numpy_wrapper_units(v, arrs)
     return v
@@ -2581,6 +2616,10 @@ def allclose_units(actual, desired, rtol=1e-7, atol=0, **kwargs):
     >>> allclose_units(actual, desired)
     True
     """
+    # TODO: see https://github.com/yt-project/unyt/issues/289
+    # warn_deprecated(
+    #    "unyt.allclose_units", replacement="use numpy.allclose", since_version="2.10"
+    # )
     # Create a copy to ensure this function does not alter input arrays
     act = unyt_array(actual)
     des = unyt_array(desired)

unyt/tests/test_unyt_array.py

@@ -2064,7 +2064,8 @@ def test_numpy_wrappers():
     assert_array_equal(unorm(a3, axis=1), unyt_array(arr_norm_answer, "cm"))
     assert_array_equal(np.linalg.norm(a3, axis=1), arr_norm_answer)
 
-    assert_array_equal(udot(a1, a1), unyt_quantity(dot_answer, "cm**2"))
+    with pytest.warns(DeprecationWarning):
+        assert_array_equal(udot(a1, a1), unyt_quantity(dot_answer, "cm**2"))
 
     assert_array_equal(np.array(catenate_answer), uconcatenate((a1.v, a2.v)))
     with pytest.raises(RuntimeError):