Move experimental equalise_attributes

docs/iris/src/userguide/merge_and_concat.rst

@@ -398,7 +398,7 @@ Merge
 Differences in the :data:`~iris.cube.Cube.attributes` the input cubes probably
 cause the greatest amount of merge-related difficulties.
 In recognition of this, Iris has a helper function,
-:func:`~iris.experimental.equalise_cubes.equalise_attributes`, to equalise
+:func:`~iris.util.equalise_attributes`, to equalise
 attributes differences in the input cubes.
 
 .. note::
@@ -407,16 +407,16 @@ attributes differences in the input cubes.
     :meth:`iris.cube.Cube.is_compatible` are **not** designed to give user
     indication of whether two cubes can be merged.
 
-To demonstrate using :func:`~iris.experimental.equalise_cubes.equalise_attributes`,
+To demonstrate using :func:`~iris.util.equalise_attributes`,
 let's return to our non-merging list of input cubes from the merge_cube example
 from earlier.
-We'll call :func:`~iris.experimental.equalise_cubes.equalise_attributes` on the
+We'll call :func:`~iris.util.equalise_attributes` on the
 input cubes before merging the input cubes using :meth:`~iris.cube.CubeList.merge_cube`:
 
 .. doctest:: merge_vs_merge_cube
     :options: +ELLIPSIS, +NORMALIZE_WHITESPACE
 
-    >>> from iris.experimental.equalise_cubes import equalise_attributes
+    >>> from iris.util import equalise_attributes
     >>> print(cubes)
     0: air_temperature / (kelvin)          (y: 4; x: 5)
     1: air_temperature / (kelvin)          (y: 4; x: 5)

docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2019-Nov-13_move_experimental_equalise_cubes.txt

@@ -0,0 +1,3 @@
+* The :func:`iris.experimental.equalise_cubes.equalise_attributes` function has been moved from the
+  :mod:`iris.experimental` module into the :mod:`iris.util` module. Please use the :func:`iris.util.equalise_attributes`
+  function instead.

lib/iris/experimental/equalise_cubes.py

@@ -8,38 +8,23 @@
 
 """
 
-import numpy as np
-
 
 def equalise_attributes(cubes):
     """
     Delete cube attributes that are not identical over all cubes in a group.
 
-    This function simply deletes any attributes which are not the same for
-    all the given cubes.  The cubes will then have identical attributes.  The
-    given cubes are modified in-place.
+    .. warning::
 
-    Args:
+        This function is now **disabled**.
 
-    * cubes (iterable of :class:`iris.cube.Cube`):
-        A collection of cubes to compare and adjust.
+        The functionality has been moved to
+        :func:`iris.util.equalise_attributes`.
 
     """
-    # Work out which attributes are identical across all the cubes.
-    common_keys = list(cubes[0].attributes.keys())
-    for cube in cubes[1:]:
-        cube_keys = list(cube.attributes.keys())
-        common_keys = [
-            key
-            for key in common_keys
-            if (
-                key in cube_keys
-                and np.all(cube.attributes[key] == cubes[0].attributes[key])
-            )
-        ]
-
-    # Remove all the other attributes.
-    for cube in cubes:
-        for key in list(cube.attributes.keys()):
-            if key not in common_keys:
-                del cube.attributes[key]
+    old = "iris.experimental.equalise_cubes.equalise_attributes"
+    new = "iris.util.equalise_attributes"
+    emsg = (
+        f'The function "{old}" has been moved.\n'
+        f'Please replace "{old}(<cubes>)" with "{new}(<cubes>)".'
+    )
+    raise Exception(emsg)

lib/iris/tests/unit/experimental/equalise_cubes/test_equalise_attributes.py → lib/iris/tests/unit/util/test_equalise_attributes.py

@@ -4,8 +4,7 @@
 # See COPYING and COPYING.LESSER in the root of the repository for full
 # licensing details.
 """
-Unit tests for the :func:`iris.experimental.equalise_cubes.equalise_attributes`
-function.
+Unit tests for the :func:`iris.util.equalise_attributes` function.
 
 """
 
@@ -16,7 +15,7 @@
 import numpy as np
 
 from iris.cube import Cube
-from iris.experimental.equalise_cubes import equalise_attributes
+from iris.util import equalise_attributes
 import iris.tests.stock
 
 

lib/iris/util.py

@@ -1794,3 +1794,37 @@ def mask_cube(cube, points_to_mask):
     cube.data = ma.masked_array(cube.data)
     cube.data[points_to_mask] = ma.masked
     return cube
+
+
+def equalise_attributes(cubes):
+    """
+    Delete cube attributes that are not identical over all cubes in a group.
+
+    This function simply deletes any attributes which are not the same for
+    all the given cubes.  The cubes will then have identical attributes.  The
+    given cubes are modified in-place.
+
+    Args:
+
+    * cubes (iterable of :class:`iris.cube.Cube`):
+        A collection of cubes to compare and adjust.
+
+    """
+    # Work out which attributes are identical across all the cubes.
+    common_keys = list(cubes[0].attributes.keys())
+    for cube in cubes[1:]:
+        cube_keys = list(cube.attributes.keys())
+        common_keys = [
+            key
+            for key in common_keys
+            if (
+                key in cube_keys
+                and np.all(cube.attributes[key] == cubes[0].attributes[key])
+            )
+        ]
+
+    # Remove all the other attributes.
+    for cube in cubes:
+        for key in list(cube.attributes.keys()):
+            if key not in common_keys:
+                del cube.attributes[key]