Make dim and spline deprecation warnings visible

doc/whats-new.rst

@@ -150,6 +150,10 @@ Breaking Changes
 
 Deprecations
 ~~~~~~~~~~~~
+- The deprecated ``dims=`` (or ``dimensions=``) argument renamed to ``dim=``
+  and ``interpolate_na(method="spline")`` now emit a ``FutureWarning`` instead
+  of a ``PendingDeprecationWarning``, so these warnings are visible by default
+  (:issue:`11721`).
 - Passing any argument after ``bins`` positionally to
   :py:meth:`Dataset.groupby_bins` and :py:meth:`DataArray.groupby_bins` is
   deprecated. It was meant to be deprecated in v2024.07.0, but the warning never

xarray/core/missing.py

@@ -521,7 +521,7 @@ def _get_interpolator(
             utils.emit_user_level_warning(
                 "The 1d SplineInterpolator class is performing an incorrect calculation and "
                 "is being deprecated. Please use `method=polynomial` for 1D Spline Interpolation.",
-                PendingDeprecationWarning,
+                FutureWarning,
             )
             if vectorizeable_only:
                 raise ValueError(f"{method} is not a vectorizeable interpolator. ")

xarray/tests/test_deprecation_helpers.py

@@ -1,6 +1,8 @@
+import warnings
+
 import pytest
 
-from xarray.util.deprecation_helpers import _deprecate_positional_args
+from xarray.util.deprecation_helpers import _deprecate_positional_args, deprecate_dims
 
 
 def test_deprecate_positional_args_warns_for_function():
@@ -138,3 +140,37 @@ class A5:
             @_deprecate_positional_args("v0.1")
             def __init__(self, a, *, b, c=3, **kwargs):
                 pass
+
+
+@pytest.mark.parametrize("old_name", ["dims", "dimensions"])
+def test_deprecate_dims_warns_and_forwards(old_name: str) -> None:
+    def func(*, dim: str, value: int) -> tuple[str, int]:
+        return dim, value
+
+    wrapped = (
+        deprecate_dims(func)
+        if old_name == "dims"
+        else deprecate_dims(func, old_name=old_name)
+    )
+    with pytest.warns(
+        FutureWarning, match=f"The `{old_name}` argument has been renamed to `dim`"
+    ):
+        result = wrapped(**{old_name: "x"}, value=42)
+    assert result == ("x", 42)
+
+
+@pytest.mark.parametrize("old_name", ["dims", "dimensions"])
+def test_deprecate_dims_canonical_dim_is_quiet(old_name: str) -> None:
+    def func(*, dim: str, value: int) -> tuple[str, int]:
+        return dim, value
+
+    wrapped = (
+        deprecate_dims(func)
+        if old_name == "dims"
+        else deprecate_dims(func, old_name=old_name)
+    )
+    with warnings.catch_warnings(record=True) as recorded:
+        warnings.simplefilter("always")
+        result = wrapped(dim="x", value=42)
+    assert result == ("x", 42)
+    assert not recorded

xarray/tests/test_interp.py

@@ -499,7 +499,15 @@ def test_errors(use_dask: bool) -> None:
         da = da.chunk()
 
     for method in ["spline"]:
-        with pytest.raises(ValueError), pytest.warns(PendingDeprecationWarning):
+        with (
+            pytest.raises(
+                ValueError, match="spline is not a vectorizeable interpolator"
+            ),
+            pytest.warns(
+                FutureWarning,
+                match="The 1d SplineInterpolator class is performing an incorrect calculation",
+            ),
+        ):
             da.interp(x=[0.5, 1.5], method=method)  # type: ignore[arg-type]
 
     # not sorted

xarray/tests/test_missing.py

@@ -143,7 +143,10 @@ def test_scipy_methods_function(method) -> None:
     # integration tests won't work.
     da, _ = make_interpolate_example_data((25, 25), 0.4, non_uniform=True)
     if method == "spline":
-        with pytest.warns(PendingDeprecationWarning):
+        with pytest.warns(
+            FutureWarning,
+            match="The 1d SplineInterpolator class is performing an incorrect calculation",
+        ):
             actual = da.interpolate_na(method=method, dim="time")
     else:
         actual = da.interpolate_na(method=method, dim="time")

xarray/util/deprecation_helpers.py

@@ -138,8 +138,7 @@ def wrapper(*args, **kwargs):
                 f"The `{old_name}` argument has been renamed to `dim`, and will be removed "
                 "in the future. This renaming is taking place throughout xarray over the "
                 "next few releases.",
-                # Upgrade to `FutureWarning` in the future, when the renaming is complete.
-                PendingDeprecationWarning,
+                FutureWarning,
             )
             kwargs["dim"] = kwargs.pop(old_name)
         return func(*args, **kwargs)