From 7e0fb16d3d894585c5568c9a41d56474b7be316a Mon Sep 17 00:00:00 2001
From: Patrick Peglar <patrick.peglar@metoffice.gov.uk>
Date: Thu, 20 Feb 2025 10:58:45 +0000
Subject: [PATCH 1/7] Remove unused 'unique' option from load collections and
 combine methods.

---
 lib/iris/_combine.py                      | 10 ++++------
 lib/iris/loading.py                       | 22 +++++-----------------
 lib/iris/tests/unit/test_combine_cubes.py |  2 +-
 3 files changed, 10 insertions(+), 24 deletions(-)

diff --git a/lib/iris/_combine.py b/lib/iris/_combine.py
index 7b01dfc87e..b401f82638 100644
--- a/lib/iris/_combine.py
+++ b/lib/iris/_combine.py
@@ -246,7 +246,7 @@ def context(self, settings=None, **kwargs):
             self.set(saved_settings)
 
 
-def _combine_cubes(cubes, options, merge_require_unique):
+def _combine_cubes(cubes, options):
     """Combine cubes as for load, according to "loading policy" options.
 
     Applies :meth:`~iris.cube.CubeList.merge`/:meth:`~iris.cube.CubeList.concatenate`
@@ -258,8 +258,6 @@ def _combine_cubes(cubes, options, merge_require_unique):
         A list of cubes to combine.
     options : dict
         Settings, as described for :class:`iris.CombineOptions`.
-    merge_require_unique : bool
-        Value for the 'unique' keyword in any merge operations.
 
     Returns
     -------
@@ -290,7 +288,7 @@ def _combine_cubes(cubes, options, merge_require_unique):
             cubes = cubes.concatenate()
         if "m" in sequence:
             # merge if requested
-            cubes = cubes.merge(unique=merge_require_unique)
+            cubes = cubes.merge()
         if sequence[-1] == "c":
             # concat if it comes last
             cubes = cubes.concatenate()
@@ -302,7 +300,7 @@ def _combine_cubes(cubes, options, merge_require_unique):
     return cubes
 
 
-def _combine_load_cubes(cubes, merge_require_unique=False):
+def _combine_load_cubes(cubes):
     # A special version to call _combine_cubes while also implementing the
     # _MULTIREF_DETECTION behaviour
     from iris import LOAD_POLICY
@@ -318,4 +316,4 @@ def _combine_load_cubes(cubes, merge_require_unique=False):
         if _MULTIREF_DETECTION.found_multiple_refs:
             options["merge_concat_sequence"] += "c"
 
-    return _combine_cubes(cubes, options, merge_require_unique=merge_require_unique)
+    return _combine_cubes(cubes, options)
diff --git a/lib/iris/loading.py b/lib/iris/loading.py
index f68cb7d9e5..39eb438447 100644
--- a/lib/iris/loading.py
+++ b/lib/iris/loading.py
@@ -58,23 +58,17 @@ def add(self, cube):
         if sub_cube is not None:
             self.cubes.append(sub_cube)
 
-    def combined(self, unique=False):
+    def combined(self):
         """Return a new :class:`_CubeFilter` by combining the list of cubes.
 
         Combines the list of cubes with :func:`~iris._combine_load_cubes`.
 
-        Parameters
-        ----------
-        unique : bool, default=False
-            If True, raises `iris.exceptions.DuplicateDataError` if
-            duplicate cubes are detected.
-
         """
         from iris._combine import _combine_load_cubes
 
         return _CubeFilter(
             self.constraint,
-            _combine_load_cubes(self.cubes, merge_require_unique=unique),
+            _combine_load_cubes(self.cubes),
         )
 
 
@@ -110,19 +104,13 @@ def cubes(self):
             result.extend(pair.cubes)
         return result
 
-    def combined(self, unique=False):
+    def combined(self):
         """Return a new :class:`_CubeFilterCollection` by combining all the cube lists of this collection.
 
         Combines each list of cubes using :func:`~iris._combine_load_cubes`.
 
-        Parameters
-        ----------
-        unique : bool, default=False
-            If True, raises `iris.exceptions.DuplicateDataError` if
-            duplicate cubes are detected.
-
         """
-        return _CubeFilterCollection([pair.combined(unique) for pair in self.pairs])
+        return _CubeFilterCollection([pair.combined() for pair in self.pairs])
 
 
 def _load_collection(uris, constraints=None, callback=None):
@@ -203,7 +191,7 @@ def load_cube(uris, constraint=None, callback=None):
     if len(constraints) != 1:
         raise ValueError("only a single constraint is allowed")
 
-    cubes = _load_collection(uris, constraints, callback).combined(unique=False).cubes()
+    cubes = _load_collection(uris, constraints, callback).combined().cubes()
 
     try:
         # NOTE: this call currently retained to preserve the legacy exceptions
diff --git a/lib/iris/tests/unit/test_combine_cubes.py b/lib/iris/tests/unit/test_combine_cubes.py
index a60831ed4c..107b7d4a4f 100644
--- a/lib/iris/tests/unit/test_combine_cubes.py
+++ b/lib/iris/tests/unit/test_combine_cubes.py
@@ -28,7 +28,7 @@ def options(request):
 def combine_cubes(cubes, settings_name="default", **kwargs):
     options = LoadPolicy.SETTINGS[settings_name]
     options.update(kwargs)
-    return _combine_cubes(cubes, options, merge_require_unique=False)
+    return _combine_cubes(cubes, options)
 
 
 class Test:

From 9096b3417626d56d0c9aa9289ddf94767af25092 Mon Sep 17 00:00:00 2001
From: Patrick Peglar <patrick.peglar@metoffice.gov.uk>
Date: Thu, 20 Feb 2025 15:04:25 +0000
Subject: [PATCH 2/7] Reinstate 'unique=False' in combine merges to fix load().

---
 lib/iris/_combine.py | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lib/iris/_combine.py b/lib/iris/_combine.py
index b401f82638..b39599002f 100644
--- a/lib/iris/_combine.py
+++ b/lib/iris/_combine.py
@@ -288,7 +288,9 @@ def _combine_cubes(cubes, options):
             cubes = cubes.concatenate()
         if "m" in sequence:
             # merge if requested
-            cubes = cubes.merge()
+            # NOTE: this needs "unique=False" to make "iris.load()" work correctly.
+            # TODO: make configurable via options.
+            cubes = cubes.merge(unique=False)
         if sequence[-1] == "c":
             # concat if it comes last
             cubes = cubes.concatenate()

From bebeddcec251b81cf6503f059628029b0386beb6 Mon Sep 17 00:00:00 2001
From: Patrick Peglar <patrick.peglar@metoffice.gov.uk>
Date: Thu, 20 Feb 2025 16:25:30 +0000
Subject: [PATCH 3/7] Add a public 'combine_cubes'.

---
 lib/iris/_combine.py                      | 60 +++++++++----------
 lib/iris/tests/unit/test_combine_cubes.py | 16 +++---
 lib/iris/util.py                          | 70 ++++++++++++++++++++++-
 3 files changed, 105 insertions(+), 41 deletions(-)

diff --git a/lib/iris/_combine.py b/lib/iris/_combine.py
index b39599002f..e491d2a0c2 100644
--- a/lib/iris/_combine.py
+++ b/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)
diff --git a/lib/iris/tests/unit/test_combine_cubes.py b/lib/iris/tests/unit/test_combine_cubes.py
index 107b7d4a4f..85f3c071b6 100644
--- a/lib/iris/tests/unit/test_combine_cubes.py
+++ b/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:
diff --git a/lib/iris/util.py b/lib/iris/util.py
index dfefb504e9..59f0cb07e4 100644
--- a/lib/iris/util.py
+++ b/lib/iris/util.py
@@ -15,7 +15,7 @@
 import os.path
 import sys
 import tempfile
-from typing import Literal
+from typing import List, Literal
 from warnings import warn
 
 import cf_units
@@ -23,6 +23,7 @@
 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)

From 618202a79a1505e57a2c5dbd8cdbde8befe230ae Mon Sep 17 00:00:00 2001
From: Patrick Peglar <patrick.peglar@metoffice.gov.uk>
Date: Thu, 20 Feb 2025 16:39:29 +0000
Subject: [PATCH 4/7] Move CombineOptions class into iris.loading to avoid
 circularity.

---
 lib/iris/_combine.py | 235 +------------------------------------------
 lib/iris/loading.py  | 235 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 234 insertions(+), 236 deletions(-)

diff --git a/lib/iris/_combine.py b/lib/iris/_combine.py
index e491d2a0c2..6a0232eacf 100644
--- a/lib/iris/_combine.py
+++ b/lib/iris/_combine.py
@@ -11,244 +11,11 @@
 publicly available.
 """
 
-import contextlib
-import threading
-from typing import List, Mapping
+from typing import List
 
 import iris
 
 
-class CombineOptions(threading.local):
-    """A container for cube combination 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
-    contains a series of fields describing time-varying orography.
-
-    Options can be set directly, or via :meth:`~iris.LoadPolicy.set`, or changed for
-    the scope of a code block with :meth:`~iris.LoadPolicy.context`.
-
-    .. note ::
-
-        The default behaviour will "fix" loading for cases like the time-varying
-        orography case described above.  However, this is not strictly
-        backwards-compatible.  If this causes problems, you can force identical loading
-        behaviour to earlier Iris versions with ``LOAD_POLICY.set("legacy")`` or
-        equivalent.
-
-    .. testsetup::
-
-        from iris import LOAD_POLICY
-
-    Notes
-    -----
-    The individual configurable options are :
-
-    * ``support_multiple_references`` = True / False
-        When enabled, the presence of multiple aux-factory reference cubes, which merge
-        to define a extra dimension, will add that dimension to the loaded cubes.
-        This is essential for correct support of time-dependent hybrid coordinates (i.e.
-        aux factories) when loading from fields-based data (e.g. PP or GRIB).
-        For example (notably) time-dependent orography in UM data on hybrid-heights.
-
-        In addition, when such multiple references are detected, an extra concatenate
-        step is added to the 'merge_concat_sequence' (see below), if none is already
-        configured there.
-
-    * ``merge_concat_sequence`` = "m" / "c" / "cm" / "mc"
-        Specifies whether to merge, or concatenate, or both in either order.
-        This is the "combine" operation which is applied to loaded data.
-
-    * ``repeat_until_unchanged`` = True / False
-        When enabled, the configured "combine" operation will be repeated until the
-        result is stable (no more cubes are combined).
-
-    Several common sets of options are provided in :data:`~iris.LOAD_POLICY.SETTINGS` :
-
-    *  ``"legacy"``
-        Produces loading behaviour identical to Iris versions < 3.11, i.e. before the
-        varying hybrid references were supported.
-
-    * ``"default"``
-        As "legacy" except that ``support_multiple_references=True``.  This differs
-        from "legacy" only when multiple mergeable reference fields are encountered,
-        in which case incoming cubes are extended into the extra dimension, and a
-        concatenate step is added.
-
-    * ``"recommended"``
-        Enables multiple reference handling, *and* applies a merge step followed by
-        a concatenate step.
-
-    * ``"comprehensive"``
-        Like "recommended", but will also *repeat* the merge+concatenate steps until no
-        further change is produced.
-
-        .. note ::
-
-            The 'comprehensive' policy makes a maximum effort to reduce the number of
-            cubes to a minimum.  However, it still cannot combine cubes with a mixture
-            of matching dimension and scalar coordinates.  This may be supported at
-            some later date, but for now is not possible without specific user actions.
-
-    .. Note ::
-
-        See also : :ref:`controlling_merge`.
-
-    """
-
-    # Useful constants
-    OPTION_KEYS = (
-        "support_multiple_references",
-        "merge_concat_sequence",
-        "repeat_until_unchanged",
-    )
-    _OPTIONS_ALLOWED_VALUES = {
-        "support_multiple_references": (False, True),
-        "merge_concat_sequence": ("", "m", "c", "mc", "cm"),
-        "repeat_until_unchanged": (False, True),
-    }
-    SETTINGS = {
-        "legacy": dict(
-            support_multiple_references=False,
-            merge_concat_sequence="m",
-            repeat_until_unchanged=False,
-        ),
-        "default": dict(
-            support_multiple_references=True,
-            merge_concat_sequence="m",
-            repeat_until_unchanged=False,
-        ),
-        "recommended": dict(
-            support_multiple_references=True,
-            merge_concat_sequence="mc",
-            repeat_until_unchanged=False,
-        ),
-        "comprehensive": dict(
-            support_multiple_references=True,
-            merge_concat_sequence="mc",
-            repeat_until_unchanged=True,
-        ),
-    }
-
-    def __init__(self, options: str | dict | None = None, **kwargs):
-        """Create loading strategy control object."""
-        self.set("default")
-        self.set(options, **kwargs)
-
-    def __setattr__(self, key, value):
-        if key not in self.OPTION_KEYS:
-            raise KeyError(f"LoadPolicy object has no property '{key}'.")
-
-        allowed_values = self._OPTIONS_ALLOWED_VALUES[key]
-        if value not in allowed_values:
-            msg = (
-                f"{value!r} is not a valid setting for LoadPolicy.{key} : "
-                f"must be one of '{allowed_values}'."
-            )
-            raise ValueError(msg)
-
-        self.__dict__[key] = value
-
-    def set(self, options: str | dict | None = None, **kwargs):
-        """Set new options.
-
-        Parameters
-        ----------
-        * options : str or dict, optional
-            A dictionary of options values, or the name of one of the
-            :data:`~iris.LoadPolicy.SETTINGS` standard option sets,
-            e.g. "legacy" or "comprehensive".
-        * kwargs : dict
-            Individual option settings, from :data:`~iris.LoadPolicy.OPTION_KEYS`.
-
-        Note
-        ----
-        Keyword arguments are applied after the 'options' arg, and
-        so will take precedence.
-
-        """
-        if options is None:
-            options = {}
-        elif isinstance(options, str) and options in self.SETTINGS:
-            options = self.SETTINGS[options]
-        elif not isinstance(options, Mapping):
-            msg = (
-                f"Invalid arg options={options!r} : "
-                f"must be a dict, or one of {tuple(self.SETTINGS.keys())}"
-            )
-            raise TypeError(msg)
-
-        # Override any options with keywords
-        options.update(**kwargs)
-        bad_keys = [key for key in options if key not in self.OPTION_KEYS]
-        if bad_keys:
-            msg = f"Unknown options {bad_keys} : valid options are {self.OPTION_KEYS}."
-            raise ValueError(msg)
-
-        # Implement all options by changing own content.
-        for key, value in options.items():
-            setattr(self, key, value)
-
-    def settings(self):
-        """Return an options dict containing the current settings."""
-        return {key: getattr(self, key) for key in self.OPTION_KEYS}
-
-    def __repr__(self):
-        msg = f"{self.__class__.__name__}("
-        msg += ", ".join(f"{key}={getattr(self, key)!r}" for key in self.OPTION_KEYS)
-        msg += ")"
-        return msg
-
-    @contextlib.contextmanager
-    def context(self, settings=None, **kwargs):
-        """Return a context manager applying given options.
-
-        Parameters
-        ----------
-        settings : str or dict
-            Options dictionary or name, as for :meth:`~LoadPolicy.set`.
-        kwargs : dict
-            Option values, as for :meth:`~LoadPolicy.set`.
-
-        Examples
-        --------
-        .. testsetup::
-
-            import iris
-            from iris import LOAD_POLICY, sample_data_path
-
-        >>> # Show how a CombineOptions acts in the context of a load operation
-        >>> # (N.B. the LOAD_POLICY actually *is* a CombineOptions type object)
-        >>> path = sample_data_path("time_varying_hybrid_height", "*.pp")
-        >>> # "legacy" load behaviour allows merge but not concatenate
-        >>> with LOAD_POLICY.context("legacy"):
-        ...     cubes = iris.load(path, "x_wind")
-        >>> print(cubes)
-        0: x_wind / (m s-1)                    (time: 2; model_level_number: 5; latitude: 144; longitude: 192)
-        1: x_wind / (m s-1)                    (time: 12; model_level_number: 5; latitude: 144; longitude: 192)
-        2: x_wind / (m s-1)                    (model_level_number: 5; latitude: 144; longitude: 192)
-        >>>
-        >>> # "recommended" behaviour enables concatenation
-        >>> with LOAD_POLICY.context("recommended"):
-        ...     cubes = iris.load(path, "x_wind")
-        >>> print(cubes)
-        0: x_wind / (m s-1)                    (model_level_number: 5; time: 15; latitude: 144; longitude: 192)
-        """
-        # Save the current state
-        saved_settings = self.settings()
-
-        # Apply the new options and execute the context
-        try:
-            self.set(settings, **kwargs)
-            yield
-        finally:
-            # Re-establish the former state
-            self.set(saved_settings)
-
-
 def _combine_cubes_inner(
     cubes: List[iris.cube.Cube], options: dict
 ) -> iris.cube.CubeList:
diff --git a/lib/iris/loading.py b/lib/iris/loading.py
index 39eb438447..fa04a3712a 100644
--- a/lib/iris/loading.py
+++ b/lib/iris/loading.py
@@ -4,8 +4,10 @@
 # See LICENSE in the root of the repository for full licensing details.
 """Iris general file loading mechanism."""
 
+import contextlib
 import itertools
-from typing import Iterable
+import threading
+from typing import Iterable, Mapping
 
 
 def _generate_cubes(uris, callback, constraints):
@@ -278,7 +280,236 @@ def load_raw(uris, constraints=None, callback=None):
         return _load_collection(uris, constraints, callback).cubes()
 
 
-from iris._combine import CombineOptions
+class CombineOptions(threading.local):
+    """A container for cube combination options.
+
+    Controls for generalised merge/concatenate options.  These are used as controls for
+    both the :func:`iris.util.combine_cubes` utility method and the core Iris loading
+    functions : see  :data:`iris.LOAD_POLICY`.
+
+    For loading, this also controls the detection and handling of cases where a hybrid
+    coordinate uses multiple reference fields during loading : for example, a UM file
+    which contains a series of fields describing a time-varying orography.
+
+    Options can be set directly, or via :meth:`~iris.LoadPolicy.set`, or changed for
+    the scope of a code block with :meth:`~iris.LoadPolicy.context`.
+
+    .. note ::
+
+        The default behaviour will "fix" loading for cases like the time-varying
+        orography case described above.  However, this is not strictly
+        backwards-compatible.  If this causes problems, you can force identical loading
+        behaviour to earlier Iris versions with ``LOAD_POLICY.set("legacy")`` or
+        equivalent.
+
+    .. testsetup::
+
+        from iris import LOAD_POLICY
+
+    Notes
+    -----
+    The individual configurable options are :
+
+    * ``support_multiple_references`` = True / False
+        When enabled, the presence of multiple aux-factory reference cubes, which merge
+        to define a extra dimension, will add that dimension to the loaded cubes.
+        This is essential for correct support of time-dependent hybrid coordinates (i.e.
+        aux factories) when loading from fields-based data (e.g. PP or GRIB).
+        For example (notably) time-dependent orography in UM data on hybrid-heights.
+
+        In addition, when such multiple references are detected, an extra concatenate
+        step is added to the 'merge_concat_sequence' (see below), if none is already
+        configured there.
+
+    * ``merge_concat_sequence`` = "m" / "c" / "cm" / "mc"
+        Specifies whether to merge, or concatenate, or both in either order.
+        This is the "combine" operation which is applied to loaded data.
+
+    * ``repeat_until_unchanged`` = True / False
+        When enabled, the configured "combine" operation will be repeated until the
+        result is stable (no more cubes are combined).
+
+    Several common sets of options are provided in :data:`~iris.LOAD_POLICY.SETTINGS` :
+
+    *  ``"legacy"``
+        Produces loading behaviour identical to Iris versions < 3.11, i.e. before the
+        varying hybrid references were supported.
+
+    * ``"default"``
+        As "legacy" except that ``support_multiple_references=True``.  This differs
+        from "legacy" only when multiple mergeable reference fields are encountered,
+        in which case incoming cubes are extended into the extra dimension, and a
+        concatenate step is added.
+
+    * ``"recommended"``
+        Enables multiple reference handling, *and* applies a merge step followed by
+        a concatenate step.
+
+    * ``"comprehensive"``
+        Like "recommended", but will also *repeat* the merge+concatenate steps until no
+        further change is produced.
+
+        .. note ::
+
+            The 'comprehensive' policy makes a maximum effort to reduce the number of
+            cubes to a minimum.  However, it still cannot combine cubes with a mixture
+            of matching dimension and scalar coordinates.  This may be supported at
+            some later date, but for now is not possible without specific user actions.
+
+    .. Note ::
+
+        See also : :ref:`controlling_merge`.
+
+    """
+
+    # Useful constants
+    OPTION_KEYS = (
+        "support_multiple_references",
+        "merge_concat_sequence",
+        "repeat_until_unchanged",
+    )
+    _OPTIONS_ALLOWED_VALUES = {
+        "support_multiple_references": (False, True),
+        "merge_concat_sequence": ("", "m", "c", "mc", "cm"),
+        "repeat_until_unchanged": (False, True),
+    }
+    SETTINGS = {
+        "legacy": dict(
+            support_multiple_references=False,
+            merge_concat_sequence="m",
+            repeat_until_unchanged=False,
+        ),
+        "default": dict(
+            support_multiple_references=True,
+            merge_concat_sequence="m",
+            repeat_until_unchanged=False,
+        ),
+        "recommended": dict(
+            support_multiple_references=True,
+            merge_concat_sequence="mc",
+            repeat_until_unchanged=False,
+        ),
+        "comprehensive": dict(
+            support_multiple_references=True,
+            merge_concat_sequence="mc",
+            repeat_until_unchanged=True,
+        ),
+    }
+
+    def __init__(self, options: str | dict | None = None, **kwargs):
+        """Create loading strategy control object."""
+        self.set("default")
+        self.set(options, **kwargs)
+
+    def __setattr__(self, key, value):
+        if key not in self.OPTION_KEYS:
+            raise KeyError(f"LoadPolicy object has no property '{key}'.")
+
+        allowed_values = self._OPTIONS_ALLOWED_VALUES[key]
+        if value not in allowed_values:
+            msg = (
+                f"{value!r} is not a valid setting for LoadPolicy.{key} : "
+                f"must be one of '{allowed_values}'."
+            )
+            raise ValueError(msg)
+
+        self.__dict__[key] = value
+
+    def set(self, options: str | dict | None = None, **kwargs):
+        """Set new options.
+
+        Parameters
+        ----------
+        * options : str or dict, optional
+            A dictionary of options values, or the name of one of the
+            :data:`~iris.LoadPolicy.SETTINGS` standard option sets,
+            e.g. "legacy" or "comprehensive".
+        * kwargs : dict
+            Individual option settings, from :data:`~iris.LoadPolicy.OPTION_KEYS`.
+
+        Note
+        ----
+        Keyword arguments are applied after the 'options' arg, and
+        so will take precedence.
+
+        """
+        if options is None:
+            options = {}
+        elif isinstance(options, str) and options in self.SETTINGS:
+            options = self.SETTINGS[options]
+        elif not isinstance(options, Mapping):
+            msg = (
+                f"Invalid arg options={options!r} : "
+                f"must be a dict, or one of {tuple(self.SETTINGS.keys())}"
+            )
+            raise TypeError(msg)
+
+        # Override any options with keywords
+        options.update(**kwargs)
+        bad_keys = [key for key in options if key not in self.OPTION_KEYS]
+        if bad_keys:
+            msg = f"Unknown options {bad_keys} : valid options are {self.OPTION_KEYS}."
+            raise ValueError(msg)
+
+        # Implement all options by changing own content.
+        for key, value in options.items():
+            setattr(self, key, value)
+
+    def settings(self):
+        """Return an options dict containing the current settings."""
+        return {key: getattr(self, key) for key in self.OPTION_KEYS}
+
+    def __repr__(self):
+        msg = f"{self.__class__.__name__}("
+        msg += ", ".join(f"{key}={getattr(self, key)!r}" for key in self.OPTION_KEYS)
+        msg += ")"
+        return msg
+
+    @contextlib.contextmanager
+    def context(self, settings=None, **kwargs):
+        """Return a context manager applying given options.
+
+        Parameters
+        ----------
+        settings : str or dict
+            Options dictionary or name, as for :meth:`~LoadPolicy.set`.
+        kwargs : dict
+            Option values, as for :meth:`~LoadPolicy.set`.
+
+        Examples
+        --------
+        .. testsetup::
+
+            import iris
+            from iris import LOAD_POLICY, sample_data_path
+
+        >>> # Show how a CombineOptions acts in the context of a load operation
+        >>> # (N.B. the LOAD_POLICY actually *is* a CombineOptions type object)
+        >>> path = sample_data_path("time_varying_hybrid_height", "*.pp")
+        >>> # "legacy" load behaviour allows merge but not concatenate
+        >>> with LOAD_POLICY.context("legacy"):
+        ...     cubes = iris.load(path, "x_wind")
+        >>> print(cubes)
+        0: x_wind / (m s-1)                    (time: 2; model_level_number: 5; latitude: 144; longitude: 192)
+        1: x_wind / (m s-1)                    (time: 12; model_level_number: 5; latitude: 144; longitude: 192)
+        2: x_wind / (m s-1)                    (model_level_number: 5; latitude: 144; longitude: 192)
+        >>>
+        >>> # "recommended" behaviour enables concatenation
+        >>> with LOAD_POLICY.context("recommended"):
+        ...     cubes = iris.load(path, "x_wind")
+        >>> print(cubes)
+        0: x_wind / (m s-1)                    (model_level_number: 5; time: 15; latitude: 144; longitude: 192)
+        """
+        # Save the current state
+        saved_settings = self.settings()
+
+        # Apply the new options and execute the context
+        try:
+            self.set(settings, **kwargs)
+            yield
+        finally:
+            # Re-establish the former state
+            self.set(saved_settings)
 
 
 class LoadPolicy(CombineOptions):

From 7986ffd911925b13da71e1b316d6d6d67f4dbaa5 Mon Sep 17 00:00:00 2001
From: Patrick Peglar <patrick.peglar@metoffice.gov.uk>
Date: Thu, 20 Feb 2025 18:14:57 +0000
Subject: [PATCH 5/7] Docstring fixes.

---
 lib/iris/util.py | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/lib/iris/util.py b/lib/iris/util.py
index 59f0cb07e4..c0db32d835 100644
--- a/lib/iris/util.py
+++ b/lib/iris/util.py
@@ -2340,9 +2340,9 @@ def combine_cubes(
         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`.
+        Name of one of the :class:`iris.CombineOptions.SETTINGS`, or a dictionary of
+        settings options, as described for :class:`~iris.CombineOptions`.
+        Defaults to the current state of :data:`iris.LOAD_POLICY`.
 
     kwargs : dict
         Individual option setting values.  These take precedence over those defined by
@@ -2353,8 +2353,8 @@ def combine_cubes(
     :class:`~iris.cube.CubeList`
 
     .. Note::
-        The ``support_multiple_references`` keyword/property has **no** effect on
-        :func:`_combine_cubes` : this only acts during load operations.
+        The ``support_multiple_references`` keyword/property has *no* effect on
+        :func:`combine_cubes` : this only acts during load operations.
 
     Examples
     --------

From a59821864349865c51a20d2da0f7ea6c6ee6668e Mon Sep 17 00:00:00 2001
From: Patrick Peglar <patrick.peglar@metoffice.gov.uk>
Date: Fri, 21 Feb 2025 14:24:53 +0000
Subject: [PATCH 6/7] Various things being trialled WIP.

---
 lib/iris/_combine/__init__.py                 | 190 ++++++++++++++
 .../_combine_functions.py}                    |  25 +-
 lib/iris/loading.py                           | 237 ++++--------------
 lib/iris/tests/unit/test_combine_cubes.py     |   4 +-
 lib/iris/util.py                              |   2 +-
 5 files changed, 248 insertions(+), 210 deletions(-)
 create mode 100644 lib/iris/_combine/__init__.py
 rename lib/iris/{_combine.py => _combine/_combine_functions.py} (76%)

diff --git a/lib/iris/_combine/__init__.py b/lib/iris/_combine/__init__.py
new file mode 100644
index 0000000000..1cc85eed93
--- /dev/null
+++ b/lib/iris/_combine/__init__.py
@@ -0,0 +1,190 @@
+# Copyright Iris contributors
+#
+# 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.
+"""Generalised mechanism for combining cubes into larger ones.
+
+Integrates merge and concatenate with the cube-equalisation options and the promotion of
+hybrid reference dimensions on loading.
+
+This is effectively a generalised "combine cubes" operation, but it is not (yet)
+publicly available.
+"""
+import threading
+from typing import Mapping
+
+class CombineOptions(threading.local):
+    """A container for cube combination options.
+
+    Controls for generalised merge/concatenate options.  These are used as controls for
+    both the :func:`iris.util.combine_cubes` utility method and the core Iris loading
+    functions : see also  :data:`iris.loading.LoadPolicy`.
+
+    It specifies a number of possible operations which may be applied to a list of
+    cubes, in a definite sequence, all of which tend to combine cubes into a smaller
+    number of larger or higher-dimensional cubes.
+
+    Notes
+    -----
+    The individual configurable options are :
+
+    * ``equalise_cube_kwargs`` = dict or None
+        If not None, this enables and provides keyword controls for a call to the
+        :func:`iris.util.equalise_cubes` utility.  If active, this always occurs
+        **before** any merge/concatenate phase.
+
+    * ``merge_concat_sequence`` = "m" / "c" / "cm" / "mc"
+        Specifies whether to apply :meth:`~iris.cube.CubeList.merge`, or
+        :meth:`~iris.cube.CubeList.concatenate` operations, or both, in either order.
+
+    * ``merge_uses_unique`` = True / False
+        When True, any merge operation will error if its result contains multiple
+        identical cubes.  Otherwise (unique=False), that is a permitted result.
+
+        .. Note::
+
+            By default, in a normal :meth:`~iris.cube.CubeList.merge` operation on a
+            :class:`~iris.cube.CubeList`, unique is ``True`` unless specified otherwise.
+            For loading operations, however, the default is ``unique=False``, as this
+            is required to make sense when making for multiple
+
+    * ``repeat_until_unchanged`` = True / False
+        When enabled, the configured "combine" operation will be repeated until the
+        result is stable (no more cubes are combined).
+
+    Several common sets of options are provided in :data:`~iris.LOAD_POLICY.SETTINGS` :
+
+    *  ``"legacy"``
+        Produces loading behaviour identical to Iris versions < 3.11, i.e. before the
+        varying hybrid references were supported.
+
+    * ``"default"``
+        As "legacy" except that ``support_multiple_references=True``.  This differs
+        from "legacy" only when multiple mergeable reference fields are encountered,
+        in which case incoming cubes are extended into the extra dimension, and a
+        concatenate step is added.
+
+    * ``"recommended"``
+        Enables multiple reference handling, *and* applies a merge step followed by
+        a concatenate step.
+
+    * ``"comprehensive"``
+        Like "recommended", but will also *repeat* the merge+concatenate steps until no
+        further change is produced.
+
+        .. note ::
+
+            The 'comprehensive' policy makes a maximum effort to reduce the number of
+            cubes to a minimum.  However, it still cannot combine cubes with a mixture
+            of matching dimension and scalar coordinates.  This may be supported at
+            some later date, but for now is not possible without specific user actions.
+
+    .. Note ::
+
+        See also : :ref:`controlling_merge`.
+
+    """
+
+    # Useful constants
+    OPTION_KEYS = (
+        # "support_multiple_references",
+        "merge_concat_sequence",
+        "repeat_until_unchanged",
+    )
+    _OPTIONS_ALLOWED_VALUES = {
+        # "support_multiple_references": (False, True),
+        "merge_concat_sequence": ("", "m", "c", "mc", "cm"),
+        "repeat_until_unchanged": (False, True),
+    }
+    SETTING_NAMES = ("legacy", "default", "recommended", "comprehensive")
+    SETTINGS = {
+        "legacy": dict(
+            # support_multiple_references=False,
+            merge_concat_sequence="m",
+            repeat_until_unchanged=False,
+        ),
+        "default": dict(
+            # support_multiple_references=True,
+            merge_concat_sequence="m",
+            repeat_until_unchanged=False,
+        ),
+        "recommended": dict(
+            # support_multiple_references=True,
+            merge_concat_sequence="mc",
+            repeat_until_unchanged=False,
+        ),
+        "comprehensive": dict(
+            # support_multiple_references=True,
+            merge_concat_sequence="mc",
+            repeat_until_unchanged=True,
+        ),
+    }
+
+    def __init__(self, options: str | dict | None = None, **kwargs):
+        """Create loading strategy control object."""
+        self.set("default")
+        self.set(options, **kwargs)
+
+    def __setattr__(self, key, value):
+        if key not in self.OPTION_KEYS:
+            raise KeyError(f"LoadPolicy object has no property '{key}'.")
+
+        allowed_values = self._OPTIONS_ALLOWED_VALUES[key]
+        if value not in allowed_values:
+            msg = (
+                f"{value!r} is not a valid setting for LoadPolicy.{key} : "
+                f"must be one of '{allowed_values}'."
+            )
+            raise ValueError(msg)
+
+        self.__dict__[key] = value
+
+    def set(self, options: str | dict | None = None, **kwargs):
+        """Set new options.
+
+        Parameters
+        ----------
+        * options : str or dict, optional
+            A dictionary of options values, or the name of one of the
+            :data:`~iris.LoadPolicy.SETTINGS` standard option sets,
+            e.g. "legacy" or "comprehensive".
+        * kwargs : dict
+            Individual option settings, from :data:`~iris.LoadPolicy.OPTION_KEYS`.
+
+        Note
+        ----
+        Keyword arguments are applied after the 'options' arg, and
+        so will take precedence.
+
+        """
+        if options is None:
+            options = {}
+        elif isinstance(options, str) and options in self.SETTINGS:
+            options = self.SETTINGS[options]
+        elif not isinstance(options, Mapping):
+            msg = (
+                f"Invalid arg options={options!r} : "
+                f"must be a dict, or one of {tuple(self.SETTINGS.keys())}"
+            )
+            raise TypeError(msg)
+
+        # Override any options with keywords
+        options.update(**kwargs)
+        bad_keys = [key for key in options if key not in self.OPTION_KEYS]
+        if bad_keys:
+            msg = f"Unknown options {bad_keys} : valid options are {self.OPTION_KEYS}."
+            raise ValueError(msg)
+
+        # Implement all options by changing own content.
+        for key, value in options.items():
+            setattr(self, key, value)
+
+    def settings(self):
+        """Return an options dict containing the current settings."""
+        return {key: getattr(self, key) for key in self.OPTION_KEYS}
+
+    def __repr__(self):
+        msg = f"{self.__class__.__name__}("
+        msg += ", ".join(f"{key}={getattr(self, key)!r}" for key in self.OPTION_KEYS)
+        msg += ")"
+        return msg
diff --git a/lib/iris/_combine.py b/lib/iris/_combine/_combine_functions.py
similarity index 76%
rename from lib/iris/_combine.py
rename to lib/iris/_combine/_combine_functions.py
index 6a0232eacf..3683eb8939 100644
--- a/lib/iris/_combine.py
+++ b/lib/iris/_combine/_combine_functions.py
@@ -2,23 +2,24 @@
 #
 # 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.
-"""Generalised mechanism for combining cubes into larger ones.
-
-Integrates merge and concatenate with the cube-equalisation options and the promotion of
-hybrid reference dimensions on loading.
-
-This is effectively a generalised "combine cubes" operation, but it is not (yet)
-publicly available.
+"""Private functions supporting the combine_cubes and loading operations.
+
+Placed in a separate submodule, purely so that iris.loading can import
+iris._combine.CombineOptions without causing a circular import problem.
+For legacy reasons, we are obliged to expose the iris load_xxx functions in
+iris.__all__, so it must be possible to import from iris.loading into a
+partially initalised iris main module.
+But do we want to import from iris.cube here, to type these routine properly.
 """
 
 from typing import List
 
 import iris
+from iris import LOAD_POLICY
+from iris.cube import Cube, CubeList
 
 
-def _combine_cubes_inner(
-    cubes: List[iris.cube.Cube], options: dict
-) -> iris.cube.CubeList:
+def _combine_cubes_inner(cubes: List[Cube], options: dict) -> CubeList:
     """Combine cubes, according to "combine options".
 
     As described for the main "iris.utils.combine_cubes".
@@ -35,8 +36,6 @@ def _combine_cubes_inner(
     -------
         CubeList
     """
-    from iris.cube import CubeList
-
     if isinstance(cubes, CubeList):
         cubelist = cubes
     else:
@@ -68,8 +67,6 @@ def _combine_cubes_inner(
 def _combine_load_cubes(cubes):
     # A special version to call _combine_cubes_inner while also implementing the
     # _MULTIREF_DETECTION behaviour
-    from iris import LOAD_POLICY
-
     options = LOAD_POLICY.settings()
     if (
         options["support_multiple_references"]
diff --git a/lib/iris/loading.py b/lib/iris/loading.py
index fa04a3712a..95d8e8c584 100644
--- a/lib/iris/loading.py
+++ b/lib/iris/loading.py
@@ -2,12 +2,19 @@
 #
 # 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.
-"""Iris general file loading mechanism."""
+"""Iris file loading support."""
+
+#
+# N.B. it is not currently possible to properly typehint the loading functions,
+# since we are obliged for backwards-compatibilty to import and expose them in the
+# iris main module API, but importing iris.cube here will cause a circular import.
+#
 
 import contextlib
 import itertools
-import threading
-from typing import Iterable, Mapping
+from typing import Iterable
+
+from iris._combine import CombineOptions
 
 
 def _generate_cubes(uris, callback, constraints):
@@ -66,7 +73,7 @@ def combined(self):
         Combines the list of cubes with :func:`~iris._combine_load_cubes`.
 
         """
-        from iris._combine import _combine_load_cubes
+        from iris._combine._combine_functions import _combine_load_cubes
 
         return _CubeFilter(
             self.constraint,
@@ -280,16 +287,16 @@ def load_raw(uris, constraints=None, callback=None):
         return _load_collection(uris, constraints, callback).cubes()
 
 
-class CombineOptions(threading.local):
-    """A container for cube combination options.
+class LoadPolicy(CombineOptions):
+    """A control object for Iris loading options.
 
-    Controls for generalised merge/concatenate options.  These are used as controls for
-    both the :func:`iris.util.combine_cubes` utility method and the core Iris loading
-    functions : see  :data:`iris.LOAD_POLICY`.
+    Incorporates all the settings of a :class:`~iris.CombineOptions`, and adds the
+    ``support_multiple_references`` control.
 
-    For loading, this also controls the detection and handling of cases where a hybrid
-    coordinate uses multiple reference fields during loading : for example, a UM file
-    which contains a series of fields describing a time-varying orography.
+    IN addition to controlling "combine" operation during loading, this also controls
+    the detection and handling of cases where a hybrid coordinate uses multiple
+    reference fields during loading : for example, a UM file which contains a series of
+    fields describing a time-varying orography.
 
     Options can be set directly, or via :meth:`~iris.LoadPolicy.set`, or changed for
     the scope of a code block with :meth:`~iris.LoadPolicy.context`.
@@ -306,165 +313,37 @@ class CombineOptions(threading.local):
 
         from iris import LOAD_POLICY
 
-    Notes
-    -----
-    The individual configurable options are :
-
-    * ``support_multiple_references`` = True / False
-        When enabled, the presence of multiple aux-factory reference cubes, which merge
-        to define a extra dimension, will add that dimension to the loaded cubes.
-        This is essential for correct support of time-dependent hybrid coordinates (i.e.
-        aux factories) when loading from fields-based data (e.g. PP or GRIB).
-        For example (notably) time-dependent orography in UM data on hybrid-heights.
-
-        In addition, when such multiple references are detected, an extra concatenate
-        step is added to the 'merge_concat_sequence' (see below), if none is already
-        configured there.
-
-    * ``merge_concat_sequence`` = "m" / "c" / "cm" / "mc"
-        Specifies whether to merge, or concatenate, or both in either order.
-        This is the "combine" operation which is applied to loaded data.
-
-    * ``repeat_until_unchanged`` = True / False
-        When enabled, the configured "combine" operation will be repeated until the
-        result is stable (no more cubes are combined).
-
-    Several common sets of options are provided in :data:`~iris.LOAD_POLICY.SETTINGS` :
-
-    *  ``"legacy"``
-        Produces loading behaviour identical to Iris versions < 3.11, i.e. before the
-        varying hybrid references were supported.
-
-    * ``"default"``
-        As "legacy" except that ``support_multiple_references=True``.  This differs
-        from "legacy" only when multiple mergeable reference fields are encountered,
-        in which case incoming cubes are extended into the extra dimension, and a
-        concatenate step is added.
-
-    * ``"recommended"``
-        Enables multiple reference handling, *and* applies a merge step followed by
-        a concatenate step.
-
-    * ``"comprehensive"``
-        Like "recommended", but will also *repeat* the merge+concatenate steps until no
-        further change is produced.
-
-        .. note ::
-
-            The 'comprehensive' policy makes a maximum effort to reduce the number of
-            cubes to a minimum.  However, it still cannot combine cubes with a mixture
-            of matching dimension and scalar coordinates.  This may be supported at
-            some later date, but for now is not possible without specific user actions.
-
-    .. Note ::
-
-        See also : :ref:`controlling_merge`.
+    Examples
+    --------
+    >>> LOAD_POLICY.set("legacy")
+    >>> print(LOAD_POLICY)
+    LoadPolicy(support_multiple_references=False, merge_concat_sequence='m', repeat_until_unchanged=False)
+    >>> LOAD_POLICY.support_multiple_references = True
+    >>> print(LOAD_POLICY)
+    LoadPolicy(support_multiple_references=True, merge_concat_sequence='m', repeat_until_unchanged=False)
+    >>> LOAD_POLICY.set(merge_concat_sequence="cm")
+    >>> print(LOAD_POLICY)
+    LoadPolicy(support_multiple_references=True, merge_concat_sequence='cm', repeat_until_unchanged=False)
+    >>> with LOAD_POLICY.context("comprehensive"):
+    ...    print(LOAD_POLICY)
+    LoadPolicy(support_multiple_references=True, merge_concat_sequence='mc', repeat_until_unchanged=True)
+    >>> print(LOAD_POLICY)
+    LoadPolicy(support_multiple_references=True, merge_concat_sequence='cm', repeat_until_unchanged=False)
 
     """
 
-    # Useful constants
-    OPTION_KEYS = (
-        "support_multiple_references",
-        "merge_concat_sequence",
-        "repeat_until_unchanged",
+    OPTION_KEYS = ("support_multiple_references",) + CombineOptions.OPTION_KEYS
+    # allowed values are as for CombineOptions, plus boolean values for multiple-refs
+    _OPTIONS_ALLOWED_VALUES = dict(
+        list(CombineOptions._OPTIONS_ALLOWED_VALUES.items())
+        + [("support_multiple_references", (True, False))]
     )
-    _OPTIONS_ALLOWED_VALUES = {
-        "support_multiple_references": (False, True),
-        "merge_concat_sequence": ("", "m", "c", "mc", "cm"),
-        "repeat_until_unchanged": (False, True),
-    }
+    # Settings are as for CombineOptions, but all with multiple load references enabled
     SETTINGS = {
-        "legacy": dict(
-            support_multiple_references=False,
-            merge_concat_sequence="m",
-            repeat_until_unchanged=False,
-        ),
-        "default": dict(
-            support_multiple_references=True,
-            merge_concat_sequence="m",
-            repeat_until_unchanged=False,
-        ),
-        "recommended": dict(
-            support_multiple_references=True,
-            merge_concat_sequence="mc",
-            repeat_until_unchanged=False,
-        ),
-        "comprehensive": dict(
-            support_multiple_references=True,
-            merge_concat_sequence="mc",
-            repeat_until_unchanged=True,
-        ),
+        key: dict(list(settings.items()) + [("support_multiple_references", True)])
+        for key, settings in CombineOptions.SETTINGS.items()
     }
 
-    def __init__(self, options: str | dict | None = None, **kwargs):
-        """Create loading strategy control object."""
-        self.set("default")
-        self.set(options, **kwargs)
-
-    def __setattr__(self, key, value):
-        if key not in self.OPTION_KEYS:
-            raise KeyError(f"LoadPolicy object has no property '{key}'.")
-
-        allowed_values = self._OPTIONS_ALLOWED_VALUES[key]
-        if value not in allowed_values:
-            msg = (
-                f"{value!r} is not a valid setting for LoadPolicy.{key} : "
-                f"must be one of '{allowed_values}'."
-            )
-            raise ValueError(msg)
-
-        self.__dict__[key] = value
-
-    def set(self, options: str | dict | None = None, **kwargs):
-        """Set new options.
-
-        Parameters
-        ----------
-        * options : str or dict, optional
-            A dictionary of options values, or the name of one of the
-            :data:`~iris.LoadPolicy.SETTINGS` standard option sets,
-            e.g. "legacy" or "comprehensive".
-        * kwargs : dict
-            Individual option settings, from :data:`~iris.LoadPolicy.OPTION_KEYS`.
-
-        Note
-        ----
-        Keyword arguments are applied after the 'options' arg, and
-        so will take precedence.
-
-        """
-        if options is None:
-            options = {}
-        elif isinstance(options, str) and options in self.SETTINGS:
-            options = self.SETTINGS[options]
-        elif not isinstance(options, Mapping):
-            msg = (
-                f"Invalid arg options={options!r} : "
-                f"must be a dict, or one of {tuple(self.SETTINGS.keys())}"
-            )
-            raise TypeError(msg)
-
-        # Override any options with keywords
-        options.update(**kwargs)
-        bad_keys = [key for key in options if key not in self.OPTION_KEYS]
-        if bad_keys:
-            msg = f"Unknown options {bad_keys} : valid options are {self.OPTION_KEYS}."
-            raise ValueError(msg)
-
-        # Implement all options by changing own content.
-        for key, value in options.items():
-            setattr(self, key, value)
-
-    def settings(self):
-        """Return an options dict containing the current settings."""
-        return {key: getattr(self, key) for key in self.OPTION_KEYS}
-
-    def __repr__(self):
-        msg = f"{self.__class__.__name__}("
-        msg += ", ".join(f"{key}={getattr(self, key)!r}" for key in self.OPTION_KEYS)
-        msg += ")"
-        return msg
-
     @contextlib.contextmanager
     def context(self, settings=None, **kwargs):
         """Return a context manager applying given options.
@@ -484,7 +363,6 @@ def context(self, settings=None, **kwargs):
             from iris import LOAD_POLICY, sample_data_path
 
         >>> # Show how a CombineOptions acts in the context of a load operation
-        >>> # (N.B. the LOAD_POLICY actually *is* a CombineOptions type object)
         >>> path = sample_data_path("time_varying_hybrid_height", "*.pp")
         >>> # "legacy" load behaviour allows merge but not concatenate
         >>> with LOAD_POLICY.context("legacy"):
@@ -494,7 +372,7 @@ def context(self, settings=None, **kwargs):
         1: x_wind / (m s-1)                    (time: 12; model_level_number: 5; latitude: 144; longitude: 192)
         2: x_wind / (m s-1)                    (model_level_number: 5; latitude: 144; longitude: 192)
         >>>
-        >>> # "recommended" behaviour enables concatenation
+        >>> # "recommended" behaviour enables concatenation also
         >>> with LOAD_POLICY.context("recommended"):
         ...     cubes = iris.load(path, "x_wind")
         >>> print(cubes)
@@ -512,32 +390,5 @@ def context(self, settings=None, **kwargs):
             self.set(saved_settings)
 
 
-class LoadPolicy(CombineOptions):
-    """A control object for Iris loading options.
-
-    Incorporates all the settings of a :class:`~iris.CombineOptions`.
-
-    Examples
-    --------
-    >>> LOAD_POLICY.set("legacy")
-    >>> print(LOAD_POLICY)
-    LoadPolicy(support_multiple_references=False, merge_concat_sequence='m', repeat_until_unchanged=False)
-    >>> LOAD_POLICY.support_multiple_references = True
-    >>> print(LOAD_POLICY)
-    LoadPolicy(support_multiple_references=True, merge_concat_sequence='m', repeat_until_unchanged=False)
-    >>> LOAD_POLICY.set(merge_concat_sequence="cm")
-    >>> print(LOAD_POLICY)
-    LoadPolicy(support_multiple_references=True, merge_concat_sequence='cm', repeat_until_unchanged=False)
-    >>> with LOAD_POLICY.context("comprehensive"):
-    ...    print(LOAD_POLICY)
-    LoadPolicy(support_multiple_references=True, merge_concat_sequence='mc', repeat_until_unchanged=True)
-    >>> print(LOAD_POLICY)
-    LoadPolicy(support_multiple_references=True, merge_concat_sequence='cm', repeat_until_unchanged=False)
-
-    """
-
-    pass
-
-
 #: A control object containing the current file loading strategy options.
 LOAD_POLICY = LoadPolicy()
diff --git a/lib/iris/tests/unit/test_combine_cubes.py b/lib/iris/tests/unit/test_combine_cubes.py
index 85f3c071b6..7ff3a8dec9 100644
--- a/lib/iris/tests/unit/test_combine_cubes.py
+++ b/lib/iris/tests/unit/test_combine_cubes.py
@@ -12,12 +12,12 @@
 
 import pytest
 
-from iris import LoadPolicy
+from iris._combine import CombineOptions
 from iris.tests.unit.fileformats.test_load_functions import cu
 from iris.util import combine_cubes
 
 
-@pytest.fixture(params=list(LoadPolicy.SETTINGS.keys()))
+@pytest.fixture(params=list(CombineOptions.SETTINGS.keys()))
 def options(request):
     # N.B. "request" is a standard PyTest fixture
     return request.param  # Return the name of the attribute to test.
diff --git a/lib/iris/util.py b/lib/iris/util.py
index c0db32d835..1722997d4c 100644
--- a/lib/iris/util.py
+++ b/lib/iris/util.py
@@ -2366,7 +2366,7 @@ def combine_cubes(
     # TODO: somehow make a real + useful example
 
     from iris import LOAD_POLICY, CombineOptions
-    from iris._combine import _combine_cubes_inner
+    from iris._combine._combine_functions import _combine_cubes_inner
 
     err = None
     opts_dict = {}

From 00fae8a8b886e4fa0177c503b412511102d75866 Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Fri, 21 Feb 2025 14:33:30 +0000
Subject: [PATCH 7/7] [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci
---
 lib/iris/_combine/__init__.py | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/lib/iris/_combine/__init__.py b/lib/iris/_combine/__init__.py
index 1cc85eed93..a8ae3bcf8e 100644
--- a/lib/iris/_combine/__init__.py
+++ b/lib/iris/_combine/__init__.py
@@ -10,9 +10,11 @@
 This is effectively a generalised "combine cubes" operation, but it is not (yet)
 publicly available.
 """
+
 import threading
 from typing import Mapping
 
+
 class CombineOptions(threading.local):
     """A container for cube combination options.