Replace DeprecationWarning with FutureWarning (#11112)

jsignell · web-flow · commit e993e1c9be44 · 2026-02-05T15:29:07.000Z
When deprecating functionality, xarray has sometimes used ``FutureWarning`` and sometimes used ``DeprecationWarning``. ``DeprecationWarning`` is not intended to be visible to end-users so this PR switches to using ``FutureWarning`` everywhere
diff --git a/doc/contribute/contributing.rst b/doc/contribute/contributing.rst
@@ -576,7 +576,7 @@ a user passes ``old_arg``, we would instead catch it:
             emit_user_level_warning(
                 "`old_arg` has been deprecated, and in the future will raise an error."
                 "Please use `new_arg` from now on.",
-                DeprecationWarning,
+                FutureWarning,
             )
 
             # Still do what the user intended here
diff --git a/doc/get-help/faq.rst b/doc/get-help/faq.rst
@@ -423,7 +423,7 @@ How stable is Xarray's API?
 
 Xarray tries very hard to maintain backwards compatibility in our :ref:`api` between released versions.
 Whilst we do occasionally make breaking changes in order to improve the library,
-we `signpost changes <https://docs.xarray.dev/en/stable/contributing.html#backwards-compatibility>`_ with ``DeprecationWarnings`` for many releases in advance.
+we `signpost changes <https://docs.xarray.dev/en/stable/contributing.html#backwards-compatibility>`_ with ``FutureWarnings`` for many releases in advance.
 (An exception is bugs - whose behaviour we try to fix as soon as we notice them.)
 Our `test-driven development practices <https://docs.xarray.dev/en/stable/contributing.html#test-driven-development-code-writing>`_ helps to ensure any accidental regressions are caught.
 This philosophy applies to everything in the `public API <https://docs.xarray.dev/en/stable/getting-started-guide/faq.html#what-parts-of-xarray-are-considered-public-api>`_.
diff --git a/doc/whats-new.rst b/doc/whats-new.rst
@@ -23,6 +23,11 @@ New Features
 Breaking Changes
 ~~~~~~~~~~~~~~~~
 
+- When deprecating functionality, xarray has sometimes used ``FutureWarning``
+  and sometimes used ``DeprecationWarning``. ``DeprecationWarning`` is
+  not intended to be visible to end-users so this version of xarray
+  switches to using ``FutureWarning`` everywhere (:pull:`11112`).
+  By `Julia Signell <https://github.com/jsignell>`_.
 
 Deprecations
 ~~~~~~~~~~~~
diff --git a/properties/test_index_manipulation.py b/properties/test_index_manipulation.py
@@ -195,9 +195,9 @@ def drop_dims(self, data):
             )
         )
         note(f"> drop_dims: {dims}")
-        # TODO: dropping a multi-index dimension raises a DeprecationWarning
+        # TODO: dropping a multi-index dimension raises a FutureWarning
         with warnings.catch_warnings():
-            warnings.simplefilter("ignore", category=DeprecationWarning)
+            warnings.simplefilter("ignore", category=FutureWarning)
             self.dataset = self.dataset.drop_dims(dims)
 
         for dim in dims:
diff --git a/xarray/backends/pydap_.py b/xarray/backends/pydap_.py
@@ -123,7 +123,7 @@ def open(
             emit_user_level_warning(
                 "`output_grid` is deprecated and will be removed in a future version"
                 " of xarray. Will be set to `None`, the new default. ",
-                DeprecationWarning,
+                FutureWarning,
             )
             output_grid = False  # new default behavior
 
diff --git a/xarray/coding/cftime_offsets.py b/xarray/coding/cftime_offsets.py
@@ -1126,7 +1126,7 @@ def cftime_range(
     """
     emit_user_level_warning(
         "cftime_range() is deprecated, please use xarray.date_range(..., use_cftime=True) instead.",
-        DeprecationWarning,
+        FutureWarning,
     )
 
     return date_range(
diff --git a/xarray/computation/rolling.py b/xarray/computation/rolling.py
@@ -707,7 +707,7 @@ def _array_reduce(
                 f"Reductions are applied along the rolling dimension(s) "
                 f"'{self.dim}'. Passing the 'dim' kwarg to reduction "
                 f"operations has no effect.",
-                DeprecationWarning,
+                FutureWarning,
                 stacklevel=3,
             )
             del kwargs["dim"]
diff --git a/xarray/conventions.py b/xarray/conventions.py
@@ -223,7 +223,7 @@ def decode_cf_variable(
                     "Example usage:\n"
                     "    time_coder = xr.coders.CFDatetimeCoder(use_cftime=True)\n"
                     "    ds = xr.open_dataset(decode_times=time_coder)\n",
-                    DeprecationWarning,
+                    FutureWarning,
                 )
             decode_times = CFDatetimeCoder(use_cftime=use_cftime)
         elif use_cftime is not None:
diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py
@@ -1479,7 +1479,7 @@ def chunk(
             utils.emit_user_level_warning(
                 "Supplying chunks as dimension-order tuples is deprecated. "
                 "It will raise an error in the future. Instead use a dict with dimension names as keys.",
-                category=DeprecationWarning,
+                category=FutureWarning,
             )
             if len(chunks) != len(self.dims):
                 raise ValueError(
diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py
@@ -2561,7 +2561,7 @@ def chunk(
             warnings.warn(
                 "None value for 'chunks' is deprecated. "
                 "It will raise an error in the future. Use instead '{}'",
-                category=DeprecationWarning,
+                category=FutureWarning,
                 stacklevel=2,
             )
             chunks = {}
@@ -2571,7 +2571,7 @@ def chunk(
                 utils.emit_user_level_warning(
                     "Supplying chunks as dimension-order tuples is deprecated. "
                     "It will raise an error in the future. Instead use a dict with dimensions as keys.",
-                    category=DeprecationWarning,
+                    category=FutureWarning,
                 )
             chunks_mapping = dict.fromkeys(self.dims, chunks)
         else:
@@ -5899,7 +5899,7 @@ def drop_vars(
             emit_user_level_warning(
                 f"Deleting a single level of a MultiIndex is deprecated. Previously, this deleted all levels of a MultiIndex. "
                 f"Please also drop the following variables: {other_names!r} to avoid an error in the future.",
-                DeprecationWarning,
+                FutureWarning,
             )
 
         assert_no_index_corrupted(self.xindexes, names_set)
@@ -5990,7 +5990,7 @@ def drop(
         if is_dict_like(labels) and not isinstance(labels, dict):
             emit_user_level_warning(
                 "dropping coordinates using `drop` is deprecated; use drop_vars.",
-                DeprecationWarning,
+                FutureWarning,
             )
             return self.drop_vars(labels, errors=errors)
 
@@ -6002,7 +6002,7 @@ def drop(
         if dim is None and (is_scalar(labels) or isinstance(labels, Iterable)):
             emit_user_level_warning(
                 "dropping variables using `drop` is deprecated; use drop_vars.",
-                DeprecationWarning,
+                FutureWarning,
             )
             # for mypy
             if is_scalar(labels):
@@ -6012,14 +6012,14 @@ def drop(
             warnings.warn(
                 "dropping labels using list-like labels is deprecated; using "
                 "dict-like arguments with `drop_sel`, e.g. `ds.drop_sel(dim=[labels]).",
-                DeprecationWarning,
+                FutureWarning,
                 stacklevel=2,
             )
             return self.drop_sel({dim: labels}, errors=errors, **labels_kwargs)
 
         emit_user_level_warning(
             "dropping labels using `drop` is deprecated; use `drop_sel` instead.",
-            DeprecationWarning,
+            FutureWarning,
         )
         return self.drop_sel(labels, errors=errors)
 
@@ -9425,7 +9425,7 @@ def argmin(self, dim: Hashable | None = None, **kwargs) -> Self:
                 "dim changes to return a dict of indices of each dimension, for "
                 "consistency it will be an error to call Dataset.argmin() with no argument,"
                 "since we don't return a dict of Datasets.",
-                DeprecationWarning,
+                FutureWarning,
                 stacklevel=2,
             )
         if (
@@ -9518,7 +9518,7 @@ def argmax(self, dim: Hashable | None = None, **kwargs) -> Self:
                 "dim changes to return a dict of indices of each dimension, for "
                 "consistency it will be an error to call Dataset.argmin() with no argument,"
                 "since we don't return a dict of Datasets.",
-                DeprecationWarning,
+                FutureWarning,
                 stacklevel=2,
             )
         if (
diff --git a/xarray/core/groupby.py b/xarray/core/groupby.py
@@ -344,7 +344,7 @@ def __post_init__(self) -> None:
         if self.eagerly_compute_group is not None:
             emit_user_level_warning(
                 "Passing `eagerly_compute_group` is now deprecated. It has no effect.",
-                DeprecationWarning,
+                FutureWarning,
             )
 
         if not isinstance(self.group, _DummyGroup) and is_chunked_array(
diff --git a/xarray/core/indexes.py b/xarray/core/indexes.py
@@ -532,7 +532,7 @@ def safe_cast_to_index(array: Any) -> pd.Index:
                         " Casting to `float64` for you, but in the future please"
                         " manually cast to either `float32` and `float64`."
                     ),
-                    category=DeprecationWarning,
+                    category=FutureWarning,
                 )
                 kwargs["dtype"] = "float64"
 
diff --git a/xarray/core/treenode.py b/xarray/core/treenode.py
@@ -310,7 +310,7 @@ def iter_lineage(self) -> tuple[Self, ...]:
         warn(
             "`iter_lineage` has been deprecated, and in the future will raise an error."
             "Please use `parents` from now on.",
-            DeprecationWarning,
+            FutureWarning,
             stacklevel=2,
         )
         return (self, *self.parents)
@@ -323,7 +323,7 @@ def lineage(self) -> tuple[Self, ...]:
         warn(
             "`lineage` has been deprecated, and in the future will raise an error."
             "Please use `parents` from now on.",
-            DeprecationWarning,
+            FutureWarning,
             stacklevel=2,
         )
         return self.iter_lineage()
@@ -342,7 +342,7 @@ def ancestors(self) -> tuple[Self, ...]:
         warn(
             "`ancestors` has been deprecated, and in the future will raise an error."
             "Please use `parents`. Example: `tuple(reversed(node.parents))`",
-            DeprecationWarning,
+            FutureWarning,
             stacklevel=2,
         )
         return (*reversed(self.parents), self)
diff --git a/xarray/core/variable.py b/xarray/core/variable.py
@@ -2491,7 +2491,7 @@ def _unravel_argminmax(
                 "change to return a dict of indices of each dimension. To get a "
                 "single, flat index, please use np.argmin(da.data) or "
                 "np.argmax(da.data) instead of da.argmin() or da.argmax().",
-                DeprecationWarning,
+                FutureWarning,
                 stacklevel=3,
             )
 
diff --git a/xarray/plot/dataarray_plot.py b/xarray/plot/dataarray_plot.py
@@ -925,7 +925,7 @@ def newplotfunc(
             if len(args) > 4:
                 raise ValueError(msg)
             else:
-                warnings.warn(msg, DeprecationWarning, stacklevel=2)
+                warnings.warn(msg, FutureWarning, stacklevel=2)
             del msg
         del args
 
@@ -938,7 +938,7 @@ def newplotfunc(
                     "Convert numbers to string for a discrete hue "
                     "and use add_legend or add_colorbar to control which guide to display."
                 ),
-                DeprecationWarning,
+                FutureWarning,
                 stacklevel=2,
             )
 
@@ -1459,7 +1459,7 @@ def newplotfunc(
             if len(args) > 2:
                 raise ValueError(msg)
             else:
-                warnings.warn(msg, DeprecationWarning, stacklevel=2)
+                warnings.warn(msg, FutureWarning, stacklevel=2)
             del msg
         del args
 
diff --git a/xarray/plot/dataset_plot.py b/xarray/plot/dataset_plot.py
@@ -212,7 +212,7 @@ def newplotfunc(
             if len(args) > 5:
                 raise ValueError(msg)
             else:
-                warnings.warn(msg, DeprecationWarning, stacklevel=2)
+                warnings.warn(msg, FutureWarning, stacklevel=2)
             del msg
         del args
 
diff --git a/xarray/plot/facetgrid.py b/xarray/plot/facetgrid.py
@@ -284,7 +284,7 @@ def axes(self) -> np.ndarray:
                 "self.axes is deprecated since 2022.11 in order to align with "
                 "matplotlibs plt.subplots, use self.axs instead."
             ),
-            DeprecationWarning,
+            FutureWarning,
             stacklevel=2,
         )
         return self.axs
@@ -296,7 +296,7 @@ def axes(self, axs: np.ndarray) -> None:
                 "self.axes is deprecated since 2022.11 in order to align with "
                 "matplotlibs plt.subplots, use self.axs instead."
             ),
-            DeprecationWarning,
+            FutureWarning,
             stacklevel=2,
         )
         self.axs = axs
diff --git a/xarray/tests/__init__.py b/xarray/tests/__init__.py
@@ -97,7 +97,7 @@ def _importorskip(
     warnings.filterwarnings(
         "ignore",
         message="'cgi' is deprecated and slated for removal in Python 3.13",
-        category=DeprecationWarning,
+        category=FutureWarning,
     )
     has_pydap, requires_pydap = _importorskip("pydap.client")
 has_netCDF4, requires_netCDF4 = _importorskip("netCDF4")
@@ -125,7 +125,7 @@ def _importorskip(
         warnings.filterwarnings(
             "ignore",
             message="The current Dask DataFrame implementation is deprecated.",
-            category=DeprecationWarning,
+            category=FutureWarning,
         )
         has_dask_expr, requires_dask_expr = _importorskip("dask_expr")
 has_bottleneck, requires_bottleneck = _importorskip("bottleneck")
@@ -160,7 +160,7 @@ def _importorskip(
     warnings.filterwarnings(
         "ignore",
         message="is_categorical_dtype is deprecated and will be removed in a future version.",
-        category=DeprecationWarning,
+        category=FutureWarning,
     )
     # seaborn uses the deprecated `pandas.is_categorical_dtype`
     has_seaborn, requires_seaborn = _importorskip("seaborn")
diff --git a/xarray/tests/test_backends.py b/xarray/tests/test_backends.py
@@ -6514,7 +6514,7 @@ def create_dap2_datasets(self, **kwargs):
             yield actual, expected
 
     def output_grid_deprecation_warning_dap2dataset(self):
-        with pytest.warns(DeprecationWarning, match="`output_grid` is deprecated"):
+        with pytest.warns(FutureWarning, match="`output_grid` is deprecated"):
             with self.create_dap2_datasets(output_grid=True) as (actual, expected):
                 assert_equal(actual, expected)
 
diff --git a/xarray/tests/test_cftime_offsets.py b/xarray/tests/test_cftime_offsets.py
@@ -1248,7 +1248,7 @@ def test_cftime_range(
     if isinstance(end, tuple):
         end = date_type(*end)
 
-    with pytest.warns(DeprecationWarning):
+    with pytest.warns(FutureWarning):
         result = cftime_range(
             start=start,
             end=end,
diff --git a/xarray/tests/test_dataarray.py b/xarray/tests/test_dataarray.py
diff --git a/xarray/tests/test_dataset.py b/xarray/tests/test_dataset.py
diff --git a/xarray/tests/test_groupby.py b/xarray/tests/test_groupby.py
diff --git a/xarray/tests/test_plot.py b/xarray/tests/test_plot.py
diff --git a/xarray/tests/test_rolling.py b/xarray/tests/test_rolling.py
diff --git a/xarray/tests/test_treenode.py b/xarray/tests/test_treenode.py
diff --git a/xarray/util/deprecation_helpers.py b/xarray/util/deprecation_helpers.py

Original file line number	Diff line number	Diff line change
@@ -576,7 +576,7 @@ a user passes ``old_arg``, we would instead catch it:
`576`	`576`	`emit_user_level_warning(`
`577`	`577`	"`old_arg` has been deprecated, and in the future will raise an error."
`578`	`578`	"Please use `new_arg` from now on.",
`579`		`- DeprecationWarning,`
	`579`	`+ FutureWarning,`
`580`	`580`	`)`
`581`	`581`
`582`	`582`	`# Still do what the user intended here`
Original file line number	Diff line number	Diff line change
`@@ -195,9 +195,9 @@ def drop_dims(self, data):`
`195`	`195`	`)`
`196`	`196`	`)`
`197`	`197`	`note(f"> drop_dims: {dims}")`
`198`		`- # TODO: dropping a multi-index dimension raises a DeprecationWarning`
	`198`	`+ # TODO: dropping a multi-index dimension raises a FutureWarning`
`199`	`199`	`with warnings.catch_warnings():`
`200`		`- warnings.simplefilter("ignore", category=DeprecationWarning)`
	`200`	`+ warnings.simplefilter("ignore", category=FutureWarning)`
`201`	`201`	`self.dataset = self.dataset.drop_dims(dims)`
`202`	`202`
`203`	`203`	`for dim in dims:`
Original file line number	Diff line number	Diff line change
`@@ -123,7 +123,7 @@ def open(`
`123`	`123`	`emit_user_level_warning(`
`124`	`124`	"`output_grid` is deprecated and will be removed in a future version"
`125`	`125`	" of xarray. Will be set to `None`, the new default. ",
`126`		`- DeprecationWarning,`
	`126`	`+ FutureWarning,`
`127`	`127`	`)`
`128`	`128`	`output_grid = False # new default behavior`
`129`	`129`
Original file line number	Diff line number	Diff line change
`@@ -1126,7 +1126,7 @@ def cftime_range(`
`1126`	`1126`	`"""`
`1127`	`1127`	`emit_user_level_warning(`
`1128`	`1128`	`"cftime_range() is deprecated, please use xarray.date_range(..., use_cftime=True) instead.",`
`1129`		`- DeprecationWarning,`
	`1129`	`+ FutureWarning,`
`1130`	`1130`	`)`
`1131`	`1131`
`1132`	`1132`	`return date_range(`
Original file line number	Diff line number	Diff line change
`@@ -707,7 +707,7 @@ def _array_reduce(`
`707`	`707`	`f"Reductions are applied along the rolling dimension(s) "`
`708`	`708`	`f"'{self.dim}'. Passing the 'dim' kwarg to reduction "`
`709`	`709`	`f"operations has no effect.",`
`710`		`- DeprecationWarning,`
	`710`	`+ FutureWarning,`
`711`	`711`	`stacklevel=3,`
`712`	`712`	`)`
`713`	`713`	`del kwargs["dim"]`
Original file line number	Diff line number	Diff line change
`@@ -223,7 +223,7 @@ def decode_cf_variable(`
`223`	`223`	`"Example usage:\n"`
`224`	`224`	`" time_coder = xr.coders.CFDatetimeCoder(use_cftime=True)\n"`
`225`	`225`	`" ds = xr.open_dataset(decode_times=time_coder)\n",`
`226`		`- DeprecationWarning,`
	`226`	`+ FutureWarning,`
`227`	`227`	`)`
`228`	`228`	`decode_times = CFDatetimeCoder(use_cftime=use_cftime)`
`229`	`229`	`elif use_cftime is not None:`
Original file line number	Diff line number	Diff line change
`@@ -1479,7 +1479,7 @@ def chunk(`
`1479`	`1479`	`utils.emit_user_level_warning(`
`1480`	`1480`	`"Supplying chunks as dimension-order tuples is deprecated. "`
`1481`	`1481`	`"It will raise an error in the future. Instead use a dict with dimension names as keys.",`
`1482`		`- category=DeprecationWarning,`
	`1482`	`+ category=FutureWarning,`
`1483`	`1483`	`)`
`1484`	`1484`	`if len(chunks) != len(self.dims):`
`1485`	`1485`	`raise ValueError(`