Add cubelist combine methods.

Author: pp-mo

lib/iris/cube.py

@@ -634,6 +634,34 @@ def concatenate(
             check_derived_coords=check_derived_coords,
         )
 
+    def combine(self, options: str | dict | None = None, **kwargs) -> CubeList:
+        from iris.util import combine_cubes
+
+        return combine_cubes(self, options, **kwargs)
+
+    def combine_cube(self, options: str | dict | None = None, **kwargs) -> CubeList:
+        result = self.combine()
+        n_cubes = len(result)
+        if n_cubes != 1:
+            from iris.util import _combine_options_asdict
+
+            opts_dict = _combine_options_asdict(options)
+            merge_concat_sequence = opts_dict.get("merge_concat_sequence")
+            is_merge = (
+                not isinstance(merge_concat_sequence, str)
+                or len(merge_concat_sequence) < 0
+                or not merge_concat_sequence.endswith("m")
+            )
+            err_type = (
+                iris.exceptions.MergeError
+                if is_merge
+                else iris.exceptions.ConcatenateError
+            )
+            msg = f"'combine' operation yielded {n_cubes} cubes, expected exactly 1."
+            raise err_type(msg)
+
+        return result
+
     def realise_data(self):
         """Fetch 'real' data for all cubes, in a shared calculation.
 

lib/iris/util.py

@@ -2348,6 +2348,33 @@ def _print_xml(doc):
     return result.replace("
", "\n")
 
 
+def _combine_options_asdict(options: str | dict | None) -> dict:
+    """Convert any valid combine options into an options dictionary."""
+    from iris import LOAD_POLICY
+
+    if options is None:
+        opts_dict = LOAD_POLICY.settings()
+    elif isinstance(options, dict):
+        opts_dict = options
+    elif isinstance(options, str):
+        if options in LOAD_POLICY.SETTINGS:
+            opts_dict = LOAD_POLICY.SETTINGS[options]
+        else:
+            msg = (
+                "Unrecognised settings name : expected one of "
+                f"{tuple(LOAD_POLICY.SETTINGS)}."
+            )
+            raise ValueError(msg)
+    else:
+        msg = (  # type: ignore[unreachable]
+            f"arg 'options' has type {type(options)!r}, "
+            "expected one of (str | dict | None)"
+        )
+        raise ValueError(msg)  # type: ignore[unreachable]
+
+    return opts_dict
+
+
 def combine_cubes(
     cubes: List[Cube],
     options: str | dict | None = None,
@@ -2450,30 +2477,9 @@ def testcube(timepts):
 
     """
     # TODO: somehow, provide a real + useful working code example
-
-    from iris import LOAD_POLICY, CombineOptions
     from iris._combine import _combine_cubes
 
-    if options is None:
-        opts_dict = LOAD_POLICY.settings()
-    elif isinstance(options, str):
-        if options in CombineOptions.SETTINGS:
-            opts_dict = CombineOptions.SETTINGS[options]
-        else:
-            msg = (
-                "Unrecognised settings name : expected one of "
-                f"{tuple(CombineOptions.SETTINGS)}."
-            )
-            raise ValueError(msg)
-    elif isinstance(options, dict):
-        opts_dict = options
-    else:
-        msg = (  # type: ignore[unreachable]
-            f"arg 'options' has type {type(options)!r}, "
-            "expected one of (str | dict | None)"
-        )
-        raise ValueError(msg)  # type: ignore[unreachable]
-
+    opts_dict = _combine_options_asdict(options)
     if kwargs is not None:
         opts_dict = opts_dict.copy()  # avoid changing original
         opts_dict.update(kwargs)