Use sentinel value to change default with warnings

Author: jsignell

xarray/backends/api.py

@@ -49,6 +49,13 @@
 from xarray.core.utils import is_remote_uri
 from xarray.namedarray.daskmanager import DaskManager
 from xarray.namedarray.parallelcompat import guess_chunkmanager
+from xarray.util.deprecation_helpers import (
+    _COMPAT_DEFAULT,
+    _COORDS_DEFAULT,
+    _DATA_VARS_DEFAULT,
+    _JOIN_DEFAULT,
+    CombineKwargDefault,
+)
 
 if TYPE_CHECKING:
     try:
@@ -1402,14 +1409,16 @@ def open_mfdataset(
         | Sequence[Index]
         | None
     ) = None,
-    compat: CompatOptions = "no_conflicts",
+    compat: CompatOptions | CombineKwargDefault = _COMPAT_DEFAULT,
     preprocess: Callable[[Dataset], Dataset] | None = None,
     engine: T_Engine | None = None,
-    data_vars: Literal["all", "minimal", "different"] | list[str] = "all",
-    coords="different",
+    data_vars: Literal["all", "minimal", "different"]
+    | list[str]
+    | CombineKwargDefault = _DATA_VARS_DEFAULT,
+    coords=_COORDS_DEFAULT,
     combine: Literal["by_coords", "nested"] = "by_coords",
     parallel: bool = False,
-    join: JoinOptions = "outer",
+    join: JoinOptions | CombineKwargDefault = _JOIN_DEFAULT,
     attrs_file: str | os.PathLike | None = None,
     combine_attrs: CombineAttrsOptions = "override",
     **kwargs,
@@ -1596,9 +1605,6 @@ def open_mfdataset(
 
     paths1d: list[str | ReadBuffer]
     if combine == "nested":
-        if isinstance(concat_dim, str | DataArray) or concat_dim is None:
-            concat_dim = [concat_dim]  # type: ignore[assignment]
-
         # This creates a flat list which is easier to iterate over, whilst
         # encoding the originally-supplied structure as "ids".
         # The "ids" are not used at all if combine='by_coords`.
@@ -1647,7 +1653,7 @@ def open_mfdataset(
             # along each dimension, using structure given by "ids"
             combined = _nested_combine(
                 datasets,
-                concat_dims=concat_dim,
+                concat_dim=concat_dim,
                 compat=compat,
                 data_vars=data_vars,
                 coords=coords,

xarray/core/alignment.py

@@ -2,6 +2,7 @@
 
 import functools
 import operator
+import warnings
 from collections import defaultdict
 from collections.abc import Callable, Hashable, Iterable, Mapping
 from contextlib import suppress
@@ -22,6 +23,7 @@
 from xarray.core.types import T_Alignable
 from xarray.core.utils import is_dict_like, is_full_slice
 from xarray.core.variable import Variable, as_compatible_data, calculate_dimensions
+from xarray.util.deprecation_helpers import CombineKwargDefault
 
 if TYPE_CHECKING:
     from xarray.core.dataarray import DataArray
@@ -418,12 +420,38 @@ def align_indexes(self) -> None:
                 else:
                     need_reindex = False
                 if need_reindex:
+                    if (
+                        isinstance(self.join, CombineKwargDefault)
+                        and self.join != "exact"
+                    ):
+                        warnings.warn(
+                            self.join.warning_message(
+                                "This change will result in the following ValueError:"
+                                "cannot be aligned with join='exact' because "
+                                "index/labels/sizes are not equal along "
+                                "these coordinates (dimensions): "
+                                + ", ".join(
+                                    f"{name!r} {dims!r}" for name, dims in key[0]
+                                ),
+                                recommend_set_options=False,
+                            ),
+                            category=FutureWarning,
+                            stacklevel=2,
+                        )
                     if self.join == "exact":
+                        new_default_warning = (
+                            " Failure might be related to new default (join='exact'). "
+                            "Previously the default was join='outer'. "
+                            "The recommendation is to set join explicitly for this case."
+                        )
                         raise ValueError(
                             "cannot align objects with join='exact' where "
                             "index/labels/sizes are not equal along "
                             "these coordinates (dimensions): "
                             + ", ".join(f"{name!r} {dims!r}" for name, dims in key[0])
+                            + new_default_warning
+                            if isinstance(self.join, CombineKwargDefault)
+                            else ""
                         )
                     joiner = self._get_index_joiner(index_cls)
                     joined_index = joiner(matching_indexes)
@@ -886,7 +914,7 @@ def align(
 
 def deep_align(
     objects: Iterable[Any],
-    join: JoinOptions = "inner",
+    join: JoinOptions | CombineKwargDefault = "inner",
     copy: bool = True,
     indexes=None,
     exclude: str | Iterable[Hashable] = frozenset(),

xarray/core/combine.py

@@ -12,6 +12,13 @@
 from xarray.core.dataset import Dataset
 from xarray.core.merge import merge
 from xarray.core.utils import iterate_nested
+from xarray.util.deprecation_helpers import (
+    _COMPAT_DEFAULT,
+    _COORDS_DEFAULT,
+    _DATA_VARS_DEFAULT,
+    _JOIN_DEFAULT,
+    CombineKwargDefault,
+)
 
 if TYPE_CHECKING:
     from xarray.core.types import (
@@ -202,9 +209,9 @@ def _combine_nd(
     concat_dims,
     data_vars,
     coords,
-    compat: CompatOptions,
+    compat: CompatOptions | CombineKwargDefault,
     fill_value,
-    join: JoinOptions,
+    join: JoinOptions | CombineKwargDefault,
     combine_attrs: CombineAttrsOptions,
 ):
     """
@@ -264,7 +271,7 @@ def _combine_all_along_first_dim(
     coords,
     compat: CompatOptions,
     fill_value,
-    join: JoinOptions,
+    join: JoinOptions | CombineKwargDefault,
     combine_attrs: CombineAttrsOptions,
 ):
     # Group into lines of datasets which must be combined along dim
@@ -295,7 +302,7 @@ def _combine_1d(
     data_vars,
     coords,
     fill_value,
-    join: JoinOptions,
+    join: JoinOptions | CombineKwargDefault,
     combine_attrs: CombineAttrsOptions,
 ):
     """
@@ -345,18 +352,21 @@ def _new_tile_id(single_id_ds_pair):
 
 def _nested_combine(
     datasets,
-    concat_dims,
+    concat_dim,
     compat,
     data_vars,
     coords,
     ids,
     fill_value,
-    join: JoinOptions,
+    join: JoinOptions | CombineKwargDefault,
     combine_attrs: CombineAttrsOptions,
 ):
     if len(datasets) == 0:
         return Dataset()
 
+    if isinstance(concat_dim, str | DataArray) or concat_dim is None:
+        concat_dim = [concat_dim]  # type: ignore[assignment]
+
     # Arrange datasets for concatenation
     # Use information from the shape of the user input
     if not ids:
@@ -373,7 +383,7 @@ def _nested_combine(
     # Apply series of concatenate or merge operations along each dimension
     combined = _combine_nd(
         combined_ids,
-        concat_dims,
+        concat_dims=concat_dim,
         compat=compat,
         data_vars=data_vars,
         coords=coords,
@@ -391,11 +401,11 @@ def _nested_combine(
 def combine_nested(
     datasets: DATASET_HYPERCUBE,
     concat_dim: str | DataArray | None | Sequence[str | DataArray | pd.Index | None],
-    compat: str = "no_conflicts",
-    data_vars: str = "all",
-    coords: str = "different",
+    compat: str | CombineKwargDefault = _COMPAT_DEFAULT,
+    data_vars: str | CombineKwargDefault = _DATA_VARS_DEFAULT,
+    coords: str | CombineKwargDefault = _COORDS_DEFAULT,
     fill_value: object = dtypes.NA,
-    join: JoinOptions = "outer",
+    join: JoinOptions | CombineKwargDefault = _JOIN_DEFAULT,
     combine_attrs: CombineAttrsOptions = "drop",
 ) -> Dataset:
     """
@@ -588,13 +598,10 @@ def combine_nested(
     if mixed_datasets_and_arrays:
         raise ValueError("Can't combine datasets with unnamed arrays.")
 
-    if isinstance(concat_dim, str | DataArray) or concat_dim is None:
-        concat_dim = [concat_dim]
-
     # The IDs argument tells _nested_combine that datasets aren't yet sorted
     return _nested_combine(
         datasets,
-        concat_dims=concat_dim,
+        concat_dim=concat_dim,
         compat=compat,
         data_vars=data_vars,
         coords=coords,
@@ -629,8 +636,8 @@ def _combine_single_variable_hypercube(
     fill_value,
     data_vars,
     coords,
-    compat: CompatOptions,
-    join: JoinOptions,
+    compat: CompatOptions | CombineKwargDefault,
+    join: JoinOptions | CombineKwargDefault,
     combine_attrs: CombineAttrsOptions,
 ):
     """
@@ -685,11 +692,13 @@ def _combine_single_variable_hypercube(
 
 def combine_by_coords(
     data_objects: Iterable[Dataset | DataArray] = [],
-    compat: CompatOptions = "no_conflicts",
-    data_vars: Literal["all", "minimal", "different"] | list[str] = "all",
-    coords: str = "different",
+    compat: CompatOptions | CombineKwargDefault = _COMPAT_DEFAULT,
+    data_vars: Literal["all", "minimal", "different"]
+    | list[str]
+    | CombineKwargDefault = _DATA_VARS_DEFAULT,
+    coords: str | CombineKwargDefault = _COORDS_DEFAULT,
     fill_value: object = dtypes.NA,
-    join: JoinOptions = "outer",
+    join: JoinOptions | CombineKwargDefault = _JOIN_DEFAULT,
     combine_attrs: CombineAttrsOptions = "no_conflicts",
 ) -> Dataset | DataArray:
     """