Added return_esmpy_regrid_operator to regrids and regridc

Changelog.rst

@@ -3,6 +3,9 @@ version 3.16.2
 
 **2024-04-??**
 
+* New keyword parameter to `cf.Field.regrids` and `cf.Field.regridc`:
+  ``return_esmpy_regrid_operator``
+  (https://github.com/NCAS-CMS/cf-python/issues/766)
 * Allow a halo to be added by `cf.Field.indices` and
   `cf.Field.subspace`
   (https://github.com/NCAS-CMS/cf-python/issues/759)

cf/docstring/docstring.py

@@ -651,6 +651,11 @@
                                 operation and define a halo to be
                                 added to the subspaced axes.
                 ==============  ======================================""",
+    # return_esmpy_regrid_operator
+    "{{return_esmpy_regrid_operator: `bool`, optional}}": """return_esmpy_regrid_operator: `bool`, optional
+                If True then do not perform the regridding, rather
+                return the `esmpy.Regrid` instance that defines the
+                regridding operation.""",
     # ----------------------------------------------------------------
     # Method description substitutions (4 levels of indentation)
     # ----------------------------------------------------------------

cf/field.py

@@ -13488,6 +13488,7 @@ def regrids(
         z=None,
         ln_z=None,
         verbose=None,
+        return_esmpy_regrid_operator=False,
         inplace=False,
         i=False,
         _compute_field_mass=None,
@@ -13728,6 +13729,10 @@ def regrids(
 
             {{inplace: `bool`, optional}}
 
+            {{return_esmpy_regrid_operator: `bool`, optional}}
+
+                .. versionadded:: 3.16.2
+
             axis_order: sequence, optional
                 Deprecated at version 3.14.0.
 
@@ -13744,7 +13749,8 @@ def regrids(
             `Field` or `None` or `RegridOperator`
                 The regridded field construct; or `None` if the
                 operation was in-place; or the regridding operator if
-                *return_operator* is True.
+                *return_operator* is True; or the `esmpy.Regrid` operator
+                object if *return_esmpy_regrid_operator* is True.
 
         **Examples**
 
@@ -13819,6 +13825,7 @@ def regrids(
             dst_z=dst_z,
             z=z,
             ln_z=ln_z,
+            return_esmpy_regrid_operator=return_esmpy_regrid_operator,
             inplace=inplace,
         )
 
@@ -13842,6 +13849,7 @@ def regridc(
         dst_z=None,
         z=None,
         ln_z=None,
+        return_esmpy_regrid_operator=False,
         inplace=False,
         i=False,
         _compute_field_mass=None,
@@ -14017,6 +14025,10 @@ def regridc(
 
             {{inplace: `bool`, optional}}
 
+            {{return_esmpy_regrid_operator: `bool`, optional}}
+
+                .. versionadded:: 3.16.2
+
             axis_order: sequence, optional
                 Deprecated at version 3.14.0.
 
@@ -14033,7 +14045,8 @@ def regridc(
             `Field` or `None` or `RegridOperator`
                 The regridded field construct; or `None` if the
                 operation was in-place; or the regridding operator if
-                *return_operator* is True.
+                *return_operator* is True; or the `esmpy.Regrid` operator
+                object if *return_esmpy_regrid_operator* is True.
 
         **Examples**
 
@@ -14107,6 +14120,7 @@ def regridc(
             dst_z=dst_z,
             z=z,
             ln_z=ln_z,
+            return_esmpy_regrid_operator=return_esmpy_regrid_operator,
             inplace=inplace,
         )
 

cf/query.py

@@ -495,7 +495,6 @@ def __str__(self):
         if self.open_lower:
             repr_value = "(" + repr_value[1:]
 
-
         if self.open_upper:
             repr_value = repr_value[:-1] + ")"
 
@@ -1740,15 +1739,15 @@ def wi(
              bound so that value0 is excluded from the
              range. By default the interval is closed
              so that value0 is included.
-             
+
              .. versionadded:: NEXTVERSION
 
         open_upper: `bool`, optional
              If True, open the interval at the upper
              bound so that value1 is excluded from the
              range. By default the interval is closed
              so that value1 is included.
-             
+
              .. versionadded:: NEXTVERSION
 
         units: `str` or `Units`, optional

cf/test/test_regrid.py

@@ -791,6 +791,25 @@ def test_Field_regrid_weights_file(self):
                 src.regrids(r, method="linear", weights_file=tmpfile)
             )
 
+    @unittest.skipUnless(esmpy_imported, "Requires esmpy/ESMF package.")
+    def test_return_esmpy_regrid_operator(self):
+        """esmpy regrid operator returns esmpy.Regrid in regrids and regridc"""
+        dst = self.dst
+        src = self.src
+
+        opers = src.regrids(
+            dst, method="conservative", return_esmpy_regrid_operator=True
+        )
+        operc = src.regridc(
+            dst,
+            axes=["Y", "X"],
+            method="conservative",
+            return_esmpy_regrid_operator=True,
+        )
+
+        self.assertIsInstance(opers, esmpy.api.regrid.Regrid)
+        self.assertIsInstance(operc, esmpy.api.regrid.Regrid)
+
 
 if __name__ == "__main__":
     print("Run date:", datetime.datetime.now())