Cubelist extract strict

docs/iris/src/whatsnew/contributions_3.0.0/incompatiblechange_2020-May-22_cubelist_extract_cubes.txt

@@ -0,0 +1,10 @@
+* The method :meth:`~iris.cube.CubeList.extract_strict`, and the 'strict'
+  keyword to :meth:`~iris.cube.CubeList.extract` method have been removed, and
+  are replaced by the new routines :meth:`~iris.cube.CubeList.extract_cube` and
+  :meth:`~iris.cube.CubeList.extract_cubes`.
+  The new routines perform the same operation, but in a style more like other
+  Iris functions such as :meth:`iris.load_cube` and :meth:`iris.load_cubes`.
+  Unlike 'strict extraction', the type of return value is now completely
+  consistent : :meth:`~iris.cube.CubeList.extract_cube` always returns a cube,
+  and :meth:`~iris.cube.CubeList.extract_cubes` always returns a CubeList of a
+  length equal to the number of constraints.

lib/iris/_constraints.py

@@ -428,7 +428,7 @@ def list_of_constraints(constraints):
     using :func:`as_constraint`.
 
     """
-    if not isinstance(constraints, (list, tuple)):
+    if isinstance(constraints, str) or not isinstance(constraints, Iterable):
         constraints = [constraints]
 
     return [as_constraint(constraint) for constraint in constraints]

lib/iris/cube.py

@@ -268,7 +268,7 @@ def xml(self, checksum=False, order=True, byteorder=True):
         # return our newly created XML string
         return doc.toprettyxml(indent="  ")
 
-    def extract(self, constraints, strict=False):
+    def extract(self, constraints):
         """
         Filter each of the cubes which can be filtered by the given
         constraints.
@@ -278,23 +278,57 @@ def extract(self, constraints, strict=False):
         **n** when filtered with **m** constraints can generate a maximum of
         **m * n** cubes.
 
-        Keywords:
+        Args:
+
+        * constraints (:class:`~iris.Constraint` or iterable of constraints):
+            A single constraint or an iterable.
+
+        """
+        return self._extract_and_merge(self, constraints, strict=False)
+
+    def extract_cube(self, constraint):
+        """
+        Extract a single cube from a CubeList, and return it.
+        Raise an error if the extract produces no cubes, or more than one.
+
+        Args:
+
+        * constraint (:class:`~iris.Constraint`):
+            The constraint to extract with.
 
-        * strict - boolean
-            If strict is True, then there must be exactly one cube which is
-            filtered per constraint. Note: if a single constraint is given, a
-            Cube is returned rather than a CubeList.
+        .. see also::
+            :meth:`~iris.cube.CubeList.extract`
 
         """
+        # Just validate this, so we can accept strings etc, but not multiples.
+        constraint = iris._constraints.as_constraint(constraint)
         return self._extract_and_merge(
-            self, constraints, strict, merge_unique=None
+            self, constraint, strict=True, return_single_cube=True
         )
 
-    @staticmethod
-    def _extract_and_merge(cubes, constraints, strict, merge_unique=False):
-        # * merge_unique - if None: no merging, if false: non unique merging,
-        # else unique merging (see merge)
+    def extract_cubes(self, constraints):
+        """
+        Extract specific cubes from a CubeList, one for each given constraint.
+        Each constraint must produce exactly one cube, otherwise an error is
+        raised.
+
+        Args:
 
+        * constraints (iterable of, or single, :class:`~iris.Constraint`):
+            The constraints to extract with.
+
+        .. see also::
+            :meth:`~iris.cube.CubeList.extract`
+
+        """
+        return self._extract_and_merge(
+            self, constraints, strict=True, return_single_cube=False
+        )
+
+    @staticmethod
+    def _extract_and_merge(
+        cubes, constraints, strict=False, return_single_cube=False
+    ):
         constraints = iris._constraints.list_of_constraints(constraints)
 
         # group the resultant cubes by constraints in a dictionary
@@ -307,10 +341,6 @@ def _extract_and_merge(cubes, constraints, strict, merge_unique=False):
                 if sub_cube is not None:
                     cube_list.append(sub_cube)
 
-        if merge_unique is not None:
-            for constraint, cubelist in constraint_groups.items():
-                constraint_groups[constraint] = cubelist.merge(merge_unique)
-
         result = CubeList()
         for constraint in constraints:
             constraint_cubes = constraint_groups[constraint]
@@ -322,18 +352,18 @@ def _extract_and_merge(cubes, constraints, strict, merge_unique=False):
                 raise iris.exceptions.ConstraintMismatchError(msg)
             result.extend(constraint_cubes)
 
-        if strict and len(constraints) == 1:
+        if return_single_cube:
+            if len(result) != 1:
+                # Practically this should never occur, as we now *only* request
+                # single cube result for 'extract_cube'.
+                msg = "Got {!s} cubes for constraints {!r}, expecting 1."
+                raise iris.exceptions.ConstraintMismatchError(
+                    msg.format(len(result), constraints)
+                )
             result = result[0]
 
         return result
 
-    def extract_strict(self, constraints):
-        """
-        Calls :meth:`CubeList.extract` with the strict keyword set to True.
-
-        """
-        return self.extract(constraints, strict=True)
-
     def extract_overlapping(self, coord_names):
         """
         Returns a :class:`CubeList` of cubes extracted over regions

lib/iris/tests/test_constraints.py

@@ -292,7 +292,7 @@ class TestCubeListStrictConstraint(StrictConstraintMixin, tests.IrisTest):
     suffix = "load_strict"
 
     def load_match(self, files, constraints):
-        cubes = iris.load(files).extract_strict(constraints)
+        cubes = iris.load(files).extract_cubes(constraints)
         return cubes
 
 
@@ -317,25 +317,25 @@ def setUp(self):
 
     def test_standard_name(self):
         constraint = iris.Constraint(self.standard_name)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
 
     def test_long_name(self):
         constraint = iris.Constraint(self.long_name)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.long_name, self.long_name)
 
     def test_var_name(self):
         constraint = iris.Constraint(self.var_name)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.var_name, self.var_name)
 
     def test_stash(self):
         constraint = iris.Constraint(self.stash)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(str(result.attributes["STASH"]), self.stash)
 
@@ -348,7 +348,7 @@ def test_unknown(self):
         cube.attributes = None
         # Extract the unknown cube.
         constraint = iris.Constraint("unknown")
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.name(), "unknown")
 
@@ -380,14 +380,14 @@ def test_standard_name(self):
 
         # Match.
         constraint = NameConstraint(standard_name=self.standard_name)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
 
         # Match - callable.
         kwargs = dict(standard_name=lambda item: item.startswith("air_pot"))
         constraint = NameConstraint(**kwargs)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
 
@@ -397,7 +397,7 @@ def test_standard_name__None(self):
         constraint = NameConstraint(
             standard_name=None, long_name=self.long_name
         )
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertIsNone(result.standard_name)
         self.assertEqual(result.long_name, self.long_name)
@@ -410,7 +410,7 @@ def test_long_name(self):
 
         # Match.
         constraint = NameConstraint(long_name=self.long_name)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.long_name, self.long_name)
 
@@ -420,7 +420,7 @@ def test_long_name(self):
             and item.startswith("air pot")
         )
         constraint = NameConstraint(**kwargs)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.long_name, self.long_name)
 
@@ -430,7 +430,7 @@ def test_long_name__None(self):
         constraint = NameConstraint(
             standard_name=self.standard_name, long_name=None
         )
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
         self.assertIsNone(result.long_name)
@@ -443,14 +443,14 @@ def test_var_name(self):
 
         # Match.
         constraint = NameConstraint(var_name=self.var_name)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.var_name, self.var_name)
 
         # Match - callable.
         kwargs = dict(var_name=lambda item: item.startswith("ap"))
         constraint = NameConstraint(**kwargs)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.var_name, self.var_name)
 
@@ -460,7 +460,7 @@ def test_var_name__None(self):
         constraint = NameConstraint(
             standard_name=self.standard_name, var_name=None
         )
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
         self.assertIsNone(result.var_name)
@@ -473,14 +473,14 @@ def test_stash(self):
 
         # Match.
         constraint = NameConstraint(STASH=self.stash)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(str(result.attributes["STASH"]), self.stash)
 
         # Match - callable.
         kwargs = dict(STASH=lambda stash: stash.item == 4)
         constraint = NameConstraint(**kwargs)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
 
     def test_stash__None(self):
@@ -489,7 +489,7 @@ def test_stash__None(self):
         constraint = NameConstraint(
             standard_name=self.standard_name, STASH=None
         )
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
         self.assertIsNone(result.attributes.get("STASH"))
@@ -499,7 +499,7 @@ def test_compound(self):
         constraint = NameConstraint(
             standard_name=self.standard_name, long_name=self.long_name
         )
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
 
@@ -518,7 +518,7 @@ def test_compound(self):
             long_name=self.long_name,
             var_name=self.var_name,
         )
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
         self.assertEqual(result.long_name, self.long_name)
@@ -541,7 +541,7 @@ def test_compound(self):
             var_name=self.var_name,
             STASH=self.stash,
         )
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertEqual(result.standard_name, self.standard_name)
         self.assertEqual(result.long_name, self.long_name)
@@ -571,7 +571,7 @@ def test_unknown(self):
         cube.var_name = None
         cube.attributes = None
         constraint = NameConstraint(None, None, None, None)
-        result = self.cubes.extract(constraint, strict=True)
+        result = self.cubes.extract_cube(constraint)
         self.assertIsNotNone(result)
         self.assertIsNone(result.standard_name)
         self.assertIsNone(result.long_name)

lib/iris/tests/test_merge.py

@@ -79,9 +79,7 @@ def custom_coord_callback(cube, field, filename):
         # Load slices, decorating a coord with custom attributes
         cubes = iris.load_raw(self._data_path, callback=custom_coord_callback)
         # Merge
-        merged = iris.cube.CubeList._extract_and_merge(
-            cubes, constraints=None, strict=False, merge_unique=False
-        )
+        merged = iris.cube.CubeList(cubes).merge()
         # Check the custom attributes are in the merged cube
         for cube in merged:
             assert cube.coord("time").attributes["monty"] == "python"