Add a public 'combine_cubes'.

Author: pp-mo

lib/iris/_combine.py

@@ -13,13 +13,16 @@
 
 import contextlib
 import threading
-from typing import Mapping
+from typing import List, Mapping
+
+import iris
 
 
 class CombineOptions(threading.local):
     """A container for cube combination options.
 
-    Controls for generalised merge/concatenate options.
+    Controls for generalised merge/concatenate options : see :data:`iris.LOAD_POLICY`
+    and :func:`iris.util.combine_cubes`.
 
     Also controls the detection and handling of cases where a hybrid coordinate
     uses multiple reference fields during loading : for example, a UM file which
@@ -246,64 +249,57 @@ def context(self, settings=None, **kwargs):
             self.set(saved_settings)
 
 
-def _combine_cubes(cubes, options):
-    """Combine cubes as for load, according to "loading policy" options.
+def _combine_cubes_inner(
+    cubes: List[iris.cube.Cube], options: dict
+) -> iris.cube.CubeList:
+    """Combine cubes, according to "combine options".
 
-    Applies :meth:`~iris.cube.CubeList.merge`/:meth:`~iris.cube.CubeList.concatenate`
-    steps to the given cubes, as determined by the 'settings'.
+    As described for the main "iris.utils.combine_cubes".
 
     Parameters
     ----------
-    cubes : list of :class:`~iris.cube.Cube`
-        A list of cubes to combine.
+    cubes : list of Cube
+        Cubes to combine.
+
     options : dict
-        Settings, as described for :class:`iris.CombineOptions`.
+        A list of options, as described in CombineOptions.
 
     Returns
     -------
-    :class:`~iris.cube.CubeList`
-
-    .. Note::
-        The ``support_multiple_references`` keyword/property has no effect on the
-        :func:`_combine_cubes` operation : it only takes effect during a load operation.
-
-    Notes
-    -----
-    TODO: make this public API in future.
-    At that point, change the API to support (options=None, **kwargs) + add testing of
-    those modes (notably arg type = None / str / dict).
-
+        CubeList
     """
     from iris.cube import CubeList
 
-    if not isinstance(cubes, CubeList):
-        cubes = CubeList(cubes)
+    if isinstance(cubes, CubeList):
+        cubelist = cubes
+    else:
+        cubelist = CubeList(cubes)
 
+    sequence = options["merge_concat_sequence"]
     while True:
-        n_original_cubes = len(cubes)
-        sequence = options["merge_concat_sequence"]
+        n_original_cubes = len(cubelist)
 
         if sequence[0] == "c":
             # concat if it comes first
-            cubes = cubes.concatenate()
+            cubelist = cubelist.concatenate()
         if "m" in sequence:
             # merge if requested
             # NOTE: this needs "unique=False" to make "iris.load()" work correctly.
             # TODO: make configurable via options.
-            cubes = cubes.merge(unique=False)
+            cubelist = cubelist.merge(unique=False)
         if sequence[-1] == "c":
             # concat if it comes last
-            cubes = cubes.concatenate()
+            cubelist = cubelist.concatenate()
 
         # Repeat if requested, *and* this step reduced the number of cubes
-        if not options["repeat_until_unchanged"] or len(cubes) >= n_original_cubes:
+        if not options["repeat_until_unchanged"] or len(cubelist) >= n_original_cubes:
             break
 
-    return cubes
+    return cubelist
 
 
 def _combine_load_cubes(cubes):
-    # A special version to call _combine_cubes while also implementing the
+    # A special version to call _combine_cubes_inner while also implementing the
     # _MULTIREF_DETECTION behaviour
     from iris import LOAD_POLICY
 
@@ -318,4 +314,4 @@ def _combine_load_cubes(cubes):
         if _MULTIREF_DETECTION.found_multiple_refs:
             options["merge_concat_sequence"] += "c"
 
-    return _combine_cubes(cubes, options)
+    return _combine_cubes_inner(cubes, options)

lib/iris/tests/unit/test_combine_cubes.py

@@ -2,7 +2,7 @@
 #
 # This file is part of Iris and is released under the BSD license.
 # See LICENSE in the root of the repository for full licensing details.
-"""Unit tests for the :func:`iris.io.loading.combine_cubes` function.
+"""Unit tests for the :func:`iris.loading.combine_cubes` function.
 
 Note: These tests are fairly extensive to cover functional uses within the loading
 operations.
@@ -13,8 +13,8 @@
 import pytest
 
 from iris import LoadPolicy
-from iris._combine import _combine_cubes
 from iris.tests.unit.fileformats.test_load_functions import cu
+from iris.util import combine_cubes
 
 
 @pytest.fixture(params=list(LoadPolicy.SETTINGS.keys()))
@@ -23,12 +23,12 @@ def options(request):
     return request.param  # Return the name of the attribute to test.
 
 
-# Interface to convert settings-name / kwargs into an options dict,
-# TODO: remove this wrapper when the API of "combine_cubes" is opened up.
-def combine_cubes(cubes, settings_name="default", **kwargs):
-    options = LoadPolicy.SETTINGS[settings_name]
-    options.update(kwargs)
-    return _combine_cubes(cubes, options)
+# # Interface to convert settings-name / kwargs into an options dict,
+# # TODO: remove this wrapper when the API of "combine_cubes" is opened up.
+# def combine_cubes(cubes, settings_name="default", **kwargs):
+#     options = LoadPolicy.SETTINGS[settings_name]
+#     options.update(kwargs)
+#     return _combine_cubes(cubes, options)
 
 
 class Test:

lib/iris/util.py

@@ -15,14 +15,15 @@
 import os.path
 import sys
 import tempfile
-from typing import Literal
+from typing import List, Literal
 from warnings import warn
 
 import cf_units
 from dask import array as da
 import numpy as np
 import numpy.ma as ma
 
+import iris
 from iris._deprecation import warn_deprecated
 from iris._lazy_data import is_lazy_data, is_lazy_masked_data
 from iris._shapefiles import create_shapefile_mask
@@ -2320,3 +2321,70 @@ def equalise_cubes(
     # Return a CubeList result = the *original* cubes, as modified
     result = CubeList(cubes)
     return result
+
+
+def combine_cubes(
+    cubes: List[iris.cube.Cube],
+    options: str | dict | None = None,
+    **kwargs,
+):
+    """Combine cubes, according to "combine options".
+
+    Applies a combination of :meth:`~iris.cube.CubeList.merge` and/or
+    :meth:`~iris.cube.CubeList.concatenate` steps to the given cubes,
+    as determined by the given settings (from 'options' and 'kwargs').
+
+    Parameters
+    ----------
+    cubes : list of :class:`~iris.cube.Cube`
+        A list of cubes to combine.
+
+    options : str or dict, optional
+        Name of a CombineOptions "setting", or a dictionary of settings options, as
+        described for :class:`~iris.CombineOptions`.
+        Defaults to :meth:`iris.LOAD_POLICY.settings`.
+
+    kwargs : dict
+        Individual option setting values.  These take precedence over those defined by
+        the 'options' arg, as described for :meth:`~iris.CombineOptions.set`.
+
+    Returns
+    -------
+    :class:`~iris.cube.CubeList`
+
+    .. Note::
+        The ``support_multiple_references`` keyword/property has **no** effect on
+        :func:`_combine_cubes` : this only acts during load operations.
+
+    Examples
+    --------
+    >>> results = combine_cubes(cubes)
+    >>> results = combine_cubes(cubes, options=CombineOptions("recommended"))
+    >>> results = combine_cubes(cubes, repeat_until_unchanged=True)
+
+    """
+    # TODO: somehow make a real + useful example
+
+    from iris import LOAD_POLICY, CombineOptions
+    from iris._combine import _combine_cubes_inner
+
+    err = None
+    opts_dict = {}
+    if options is None:
+        opts_dict = LOAD_POLICY.settings().copy()
+    elif isinstance(options, str):
+        if options in CombineOptions.SETTINGS:
+            opts_dict = CombineOptions.SETTINGS[options].copy()
+        else:
+            err = (
+                "Unrecognised settings name : expected one of "
+                f"{tuple(CombineOptions.SETTINGS)}."
+            )
+
+    if err:
+        raise ValueError(err)
+
+    if kwargs is not None:
+        opts_dict.update(kwargs)
+
+    return _combine_cubes_inner(cubes, opts_dict)