Combine cubes 2

docs/src/userguide/loading_iris_cubes.rst

@@ -15,6 +15,13 @@ Iris will attempt to return **as few cubes as possible**
 by collecting together multiple fields with a shared standard name
 into a single multidimensional cube.
 
+.. hint::
+
+    There are details at :class:`iris.CombineOptions` on how Iris works to load
+    fewer and larger cubes :  The :data:`iris.COMBINE_POLICY` object allows the user to
+    control how cubes are combined during the loading process.  See the documentation
+    of the :class:`iris.CombineOptions` class for details.
+
 The :py:func:`iris.load` function automatically recognises the format
 of the given files and attempts to produce Iris Cubes from their contents.
 

docs/src/whatsnew/latest.rst

@@ -30,6 +30,26 @@ This document explains the changes made to Iris for this release
 ✨ Features
 ===========
 
+#. `@pp-mo`_ renamed the :class:`iris.LoadPolicy` as :class:`iris.CombineOptions` and
+   :data:`iris.LOAD_POLICY` as :data:`iris.COMBINE_POLICY`, though the original names
+   remain functional (and refer to the same things) for now.
+   (:issue:`6203`, :pull:`6334`)
+
+#. `@pp-mo`_ added new :meth:`~iris.cube.CubeList.combine` and
+   :meth:`~iris.cube.CubeList.combine_cube` methods of a :class:`~iris.cube.CubeList`
+   as an alternative way of accessing the :func:`~iris.util.combine_cubes` mechanism.
+   (:issue:`6203`, :pull:`6334`)
+
+#. `@pp-mo`_ added a new utility function :func:`~iris.util.combine_cubes`, to give
+   general public access to the combine merge/concatenate mechanism introduced for
+   generalised loading support via :class:`iris.LoadPolicy` in the Iris 3.11 release.
+   (:issue:`6203`, :pull:`6334`)
+
+#. `@pp-mo`_ overhauled the :class:`iris.LoadPolicy` facility by adding a new
+   ``equalise_cubes_kwarg`` keyword, enabling it to call the
+   :func:`~iris.util.equalise_cubes` utility function as one of its processing stages.
+   (:issue:`6203`, :pull:`6334`)
+
 #. `@pp-mo`_ added a new utility function :func:`~iris.util.equalise_cubes`, to help
    with aligning cubes so they can merge / concatenate.
    (:issue:`6248`, :pull:`6257`)
@@ -48,11 +68,11 @@ This document explains the changes made to Iris for this release
    However, :meth:`~iris.cube.Cube.transpose` will work, as will
    :meth:`~iris.cube.Cube.copy`. Note that, ``cube.copy(data=iris.DATALESS)``
    will provide a dataless copy of a cube. (:issue:`4447`, :pull:`6253`)
-   
+
 #. `@ESadek-MO`_ added the :mod:`iris.quickplot` ``footer`` kwarg to
    render text in the bottom right of the plot figure.
    (:issue:`6247`, :pull:`6332`)
-   
+
 
 🐛 Bugs Fixed
 =============

lib/iris/__init__.py

@@ -18,6 +18,12 @@
 :class:`Cubes <iris.cube.Cube>`, and combine those cubes into
 higher-dimensional cubes where possible.
 
+.. note::
+
+    User control of the 'combine' process is provided via a specific
+    :class:`iris.CombineOptions` object called :data:`iris.COMBINE_POLICY`.
+    See the :class:`iris.CombineOptions` class for details.
+
 The :func:`load_cube` and :func:`load_cubes` functions are similar to
 :func:`load`, but they raise an exception if the number of cubes is not
 what was expected. They are more useful in scripts, where they can
@@ -94,14 +100,13 @@ def callback(cube, field, filename):
 import threading
 from typing import Callable, Literal
 
+from iris._combine import COMBINE_POLICY as _COMBINE_POLICY
+from iris._combine import CombineOptions
 import iris._constraints
 import iris.config
 import iris.io
 from iris.io import save
-from iris.loading import LOAD_POLICY as _LOAD_POLICY
 from iris.loading import (
-    CombineOptions,
-    LoadPolicy,
     load,
     load_cube,
     load_cubes,
@@ -111,8 +116,14 @@ def callback(cube, field, filename):
 # NOTE: we make an independent local 'LOAD_POLICY' definition here, just so that we
 # can ensure an entry for it in our API documentation page.
 
-#: A control object containing the current file loading strategy options.
-LOAD_POLICY = _LOAD_POLICY
+#: An object to control default cube combination and loading options
+COMBINE_POLICY = _COMBINE_POLICY
+
+#: An alias for the :class:`~iris._combine.CombineOptions` class.
+LoadPolicy = CombineOptions
+
+#: An alias for the :data:`~iris.COMBINE_POLICY` object.
+LOAD_POLICY = _COMBINE_POLICY
 
 
 from ._deprecation import IrisDeprecation, warn_deprecated
@@ -132,6 +143,7 @@ def callback(cube, field, filename):
 # Restrict the names imported when using "from iris import *"
 __all__ = [
     "AttributeConstraint",
+    "COMBINE_POLICY",
     "CombineOptions",
     "Constraint",
     "DATALESS",