Type hints for combine functions (pydata#5519)

* Added test for combine_by_coords changes.

* Modified test case to expect a dataset instead of a DataArray. Added converter to combine_by_coords to check for all DataArray case and convert to datasets.

* Added tests to check combine_by_coords for exception with mixed DataArrays and dataset input and with empty list.

* Formatting changes after running black

* Added underscore to helper function to label as private.

* Black formatting changes for whats-new doc file.

* Removed imports in docstring that were automatically added by code styling tools to match the other docstrings.

* Removed duplicate new item line in whats-new.

* combine methods now accept unnamed DataArrays as input.

* combine nested test checks nested lists of unnamed DataArrays.

* Made combine_by_coords more readable.

* Cosmetic changes to code style.

* Removed extra test from merge with previous PR.

* Updated test to use pytest.raises instead of raises_regex.

* Added breaking-change entry to whats new page.

* Added deprecation warning to combine_coords

* Removed index monotonicity checking temporarily.

* Removed duplicate entries from whats new page.

* Removed TODO message

* Added test for combine_nested.

* Added check to combine methods to clarify parameter requirements.

* Reassigned description of changes to bug fixes category.

* Minor style changes.

* Added blank line for style purposes.

* added type hints

* force CI

Co-authored-by: Augustus Ijams <[email protected]>

Author: 2 people

xarray/core/combine.py

@@ -1,6 +1,7 @@
 import itertools
 import warnings
 from collections import Counter
+from typing import Iterable, Sequence, Union
 
 import pandas as pd
 
@@ -369,16 +370,23 @@ def _nested_combine(
     return combined
 
 
+# Define type for arbitrarily-nested list of lists recursively
+# Currently mypy cannot handle this but other linters can (https://stackoverflow.com/a/53845083/3154101)
+DATASET_HYPERCUBE = Union[Dataset, Iterable["DATASET_HYPERCUBE"]]  # type: ignore
+
+
 def combine_nested(
-    datasets,
-    concat_dim,
-    compat="no_conflicts",
-    data_vars="all",
-    coords="different",
-    fill_value=dtypes.NA,
-    join="outer",
-    combine_attrs="drop",
-):
+    datasets: DATASET_HYPERCUBE,
+    concat_dim: Union[
+        str, DataArray, None, Sequence[Union[str, "DataArray", pd.Index, None]]
+    ],
+    compat: str = "no_conflicts",
+    data_vars: str = "all",
+    coords: str = "different",
+    fill_value: object = dtypes.NA,
+    join: str = "outer",
+    combine_attrs: str = "drop",
+) -> Dataset:
     """
     Explicitly combine an N-dimensional grid of datasets into one by using a
     succession of concat and merge operations along each dimension of the grid.
@@ -651,16 +659,17 @@ def _combine_single_variable_hypercube(
 
 # TODO remove empty list default param after version 0.21, see PR4696
 def combine_by_coords(
-    data_objects=[],
-    compat="no_conflicts",
-    data_vars="all",
-    coords="different",
-    fill_value=dtypes.NA,
-    join="outer",
-    combine_attrs="no_conflicts",
-    datasets=None,
-):
+    data_objects: Sequence[Union[Dataset, DataArray]] = [],
+    compat: str = "no_conflicts",
+    data_vars: str = "all",
+    coords: str = "different",
+    fill_value: object = dtypes.NA,
+    join: str = "outer",
+    combine_attrs: str = "no_conflicts",
+    datasets: Sequence[Dataset] = None,
+) -> Union[Dataset, DataArray]:
     """
+
     Attempt to auto-magically combine the given datasets (or data arrays)
     into one by using dimension coordinates.
 
@@ -755,7 +764,7 @@ def combine_by_coords(
 
     Returns
     -------
-    combined : xarray.Dataset
+    combined : xarray.Dataset or xarray.DataArray
 
     See also
     --------