dev

Author: davidhassell

Changelog.rst

@@ -7,6 +7,8 @@ version 3.17.0
   (https://github.com/NCAS-CMS/cf-python/issues/843)
 * Replace dataset aggregation functionality (CFA) with that imported
   from `cfdm` (https://github.com/NCAS-CMS/cf-python/issues/841)
+* New keyword parameter to `cf.Field.compute_vertical_coordinates`:
+  ``key`` (https://github.com/NCAS-CMS/cf-python/issues/802)
 * Changed dependency: ``Python>=3.9.0``
 * Changed dependency: ``numpy>=2.0.0``
 * Changed dependency: ``cfdm>=1.12.0.0, <1.12.1.0``
@@ -17,6 +19,7 @@ version 3.17.0
 
 ----
 
+
 version 3.16.3
 --------------
 

DOCUMENTATION.md

@@ -1,4 +1,4 @@
-* The generation of recipes using Sphinx-Gallery requires:
+* The generation of recipes using Sphinx-Gallery requires `Python<3.12.0` and:
 
   ```txt
   pip install sphinx-gallery==0.11.0
@@ -10,6 +10,7 @@
   pip install sphinxcontrib-devhelp==1.0.2
   pip install sphinxcontrib-serializinghtml==1.1.3
   pip install sphinxcontrib-qthelp==1.0.3
+  pip install sphinxcontrib.applehelp==1.0.4
   pip install alabaster==0.7.13
   pip install sphinx==2.4.5
   ```

cf/aggregate.py

@@ -4732,7 +4732,7 @@ def _aggregate_2_fields(
             anc0["hash_value"] = hash_value0 + hash_value1
 
             # The result of aggregating a promoted amd non-promoted
-            # field ancillary is a non-promoted fierld ancillary
+            # field ancillary is a non-promoted field ancillary
             if (
                 key0 in m0.promoted_field_ancillaries
                 and key1 not in m1.promoted_field_ancillaries
@@ -5011,7 +5011,7 @@ def _fix_promoted_field_ancillaries(output_meta, axes_aggregated):
 
         output_meta: `list`
             The list of `_Meta` objects. If any include promoted field
-            ancillaries then thses will be updated in-place.
+            ancillaries then these will be updated in-place.
 
     :Returns:
 

cf/data/data.py

@@ -2804,7 +2804,7 @@ def _concatenate_conform_units(cls, data1, units0, relaxed_units, copy):
         """Check and conform the units of data prior to concatenation.
 
         This is a helper function for `concatenate` that may be easily
-        overridden in sublcasses, to allow for customisation of the
+        overridden in subclasses, to allow for customisation of the
         concatenation process.
 
         .. versionadded:: NEXTVERSION
@@ -2853,7 +2853,7 @@ def _concatenate_conform_units(cls, data1, units0, relaxed_units, copy):
         else:
             raise ValueError(
                 "Can't concatenate: All the input arrays must have "
-                "equivalent units. Got {units0!r} and {units1!r}"
+                f"equivalent units. Got {units0!r} and {units1!r}"
             )
 
         return data1
@@ -2865,7 +2865,7 @@ def _concatenate_post_process(
         """Post-process concatenated data.
 
         This is a helper function for `concatenate` that may be easily
-        overridden in sublcasses, to allow for customisation of the
+        overridden in subclasses, to allow for customisation of the
         concatenation process.
 
         .. versionadded:: NEXTVERSION
@@ -2905,15 +2905,6 @@ def _concatenate_post_process(
             )
             concatenated_data.cyclic(axes=axis, iscyclic=False)
 
-        #        # Set whether or not the concatenated name is deterministic
-        #        deterministic = True
-        #        for d in conformed_data:
-        #            if not d.has_deterministic_name():
-        #                deterministic = False
-        #               break#
-        #
-        #        concatenated_data._update_deterministic(deterministic)
-
         return concatenated_data
 
     @_inplace_enabled(default=False)

cf/field.py

@@ -9141,7 +9141,12 @@ def domain_mask(self, **kwargs):
     @_inplace_enabled(default=False)
     @_manage_log_level_via_verbosity
     def compute_vertical_coordinates(
-        self, default_to_zero=True, strict=True, inplace=False, verbose=None
+        self,
+        default_to_zero=True,
+        strict=True,
+        key=False,
+        inplace=False,
+        verbose=None,
     ):
         """Compute non-parametric vertical coordinates.
 
@@ -9176,7 +9181,7 @@ def compute_vertical_coordinates(
             {{default_to_zero: `bool`, optional}}
 
             strict: `bool`
-                If False then allow the computation to occur when
+                If False then allow the computation to occur when:
 
                 * A domain ancillary construct has no standard name, but
                   the corresponding term has a standard name that is
@@ -9195,15 +9200,30 @@ def compute_vertical_coordinates(
                 names, then an exception is raised regardless of the value
                 of *strict*.
 
+            key: `bool`
+                If True, return alongside the field construct the key
+                identifying the auxiliary coordinate of the field with
+                the newly-computed vertical coordinates, as a 2-tuple
+                of field and then key. If False, the default, then only
+                return the field construct.
+
+                If no coordinates were computed, `None` will be
+                returned in the key (second) position of the 2-tuple.
+
+                .. versionadded:: 3.17.0
+
             {{inplace: `bool`, optional}}
 
             {{verbose: `int` or `str` or `None`, optional}}
 
         :Returns:
 
-            `Field` or `None`
+            `Field`, 2-tuple, or `None`
                 The field construct with the new non-parametric vertical
-                coordinates, or `None` if the operation was in-place.
+                coordinates, or a 2-tuple of this field construct along
+                with the key of the new auxiliary coordinate with the
+                computed vertical coordinates, or `None` if the operation
+                was in-place.
 
         **Examples**
 
@@ -9230,7 +9250,7 @@ def compute_vertical_coordinates(
         >>> print(f.auxiliary_coordinate('altitude', default=None))
         None
         >>> g = f.compute_vertical_coordinates()
-        >>> print(g.auxiliary_coordinates)
+        >>> print(g.auxiliary_coordinates())
         Constructs:
         {'auxiliarycoordinate0': <CF AuxiliaryCoordinate: latitude(10, 9) degrees_N>,
          'auxiliarycoordinate1': <CF AuxiliaryCoordinate: longitude(9, 10) degrees_E>,
@@ -9246,12 +9266,35 @@ def compute_vertical_coordinates(
             Bounds:units = 'm'
             Bounds:Data(1, 10, 9, 2) = [[[[5.0, ..., 5415.0]]]] m
 
+        >>> g, key = f.compute_vertical_coordinates(key=True)
+        >>> g
+        <CF Field: air_temperature(atmosphere_hybrid_height_coordinate(1), grid_latitude(10), grid_longitude(9)) K>
+        >>> key
+        'auxiliarycoordinate3'
+
+        >>> i = f.compute_vertical_coordinates(inplace=True)
+        >>> print(i)
+        None
+        >>> print(f.auxiliary_coordinates())
+        Constructs:
+        {'auxiliarycoordinate0': <CF AuxiliaryCoordinate: latitude(10, 9) degrees_N>,
+        'auxiliarycoordinate1': <CF AuxiliaryCoordinate: longitude(9, 10) degrees_E>,
+        'auxiliarycoordinate2': <CF AuxiliaryCoordinate: long_name=Grid latitude name(10) >,
+        'auxiliarycoordinate3': <CF AuxiliaryCoordinate: altitude(1, 10, 9) m>}
+
         """
         f = _inplace_enabled_define_and_cleanup(self)
 
+        if inplace and key:
+            raise ValueError(
+                "Can't set both key=True and inplace=True, since inplace "
+                "will always do the operation in-place and return None."
+            )
+
         detail = is_log_level_detail(logger)
         debug = is_log_level_debug(logger)
 
+        return_key = None  # in case there are no vertical coords to compute
         for cr in f.coordinate_references(todict=True).values():
             # --------------------------------------------------------
             # Compute the non-parametric vertical coordinates, if
@@ -9293,20 +9336,25 @@ def compute_vertical_coordinates(
                     f"{c.dump(display=False, _level=1)}"
                 )  # pragma: no cover
 
-            key = f.set_construct(c, axes=computed_axes, copy=False)
+            return_key = f.set_construct(c, axes=computed_axes, copy=False)
 
             # Reference the new coordinates from the coordinate
             # reference construct
-            cr.set_coordinate(key)
+            cr.set_coordinate(return_key)
 
             if debug:
                 logger.debug(
-                    f"Non-parametric coordinates construct key: {key!r}\n"
+                    "Non-parametric coordinates construct key: "
+                    f"{return_key!r}\n"
                     "Updated coordinate reference construct:\n"
                     f"{cr.dump(display=False, _level=1)}"
                 )  # pragma: no cover
 
-        return f
+        if key:
+            # 2-tuple, where return_key will be None if nothing was computed
+            return f, return_key
+        else:
+            return f
 
     def match_by_construct(self, *identities, OR=False, **conditions):
         """Whether or not there are particular metadata constructs.

cf/functions.py

@@ -2754,6 +2754,11 @@ def dirname(path, normalise=False, uri=None, isdir=False, sep=False):
 
 dirname.__doc__ = cfdm.dirname.__doc__.replace("cfdm.", "cf.")
 
+from functools import partial
+
+dirname2 = partial(cfdm.dirname)
+dirname2.__doc__ = cfdm.dirname.__doc__.replace("cfdm.", "cf.")
+
 
 def pathjoin(path1, path2):
     """Join two file path components intelligently.

cf/read_write/read.py

@@ -848,8 +848,8 @@ def __new__(
         if nfields is not None and len(out) != nfields:
             raise ValueError(
                 f"{nfields} field{cls._plural(nfields)} requested but "
-                f"{len(out)} field/domain constucts found in "
-                f"file{cls._plural(file_counter)}"
+                f"{len(out)} field/domain constuct{cls._plural(len(out))}"
+                f" found in file{cls._plural(file_counter)}"
             )
 
         return out

cf/read_write/um/umread.py

@@ -567,7 +567,7 @@ def __init__(
                 Unpacking is determined by netCDF conventions for the
                 following variable attributes ``add_offset`` and
                 ``scale_factor``, as applied to lookup header entries
-                BDATUM and BMKS repectively.
+                BDATUM and BMKS respectively.
 
                 .. versionadded:: NEXTVERSION
 
@@ -3499,7 +3499,7 @@ def read(
                 Unpacking is determined by netCDF conventions for the
                 following variable attributes ``add_offset`` and
                 ``scale_factor``, as applied to lookup header entries
-                BDATUM and BMKS repectively.
+                BDATUM and BMKS respectively.
 
                 .. versionadded:: NEXTVERSION
 

cf/test/test_docstring.py

@@ -87,14 +87,21 @@ def test_docstring(self):
                     if name.startswith("__") and not inspect.isfunction(f):
                         continue
 
-                    if f.__doc__ is not None:
-                        self.assertNotIn(
-                            "{{",
-                            f.__doc__,
-                            f"\nCLASS: {klass}"
-                            f"\nMETHOD NAME: {name}"
-                            f"\nMETHOD: {f}",
-                        )
+                    self.assertIsNotNone(
+                        f.__doc__,
+                        f"\nCLASS: {klass}"
+                        f"\nMETHOD NAME: {name}"
+                        f"\nMETHOD: {f}"
+                        f"\n__doc__: {f.__doc__}",
+                    )
+
+                    self.assertNotIn(
+                        "{{",
+                        f.__doc__,
+                        f"\nCLASS: {klass}"
+                        f"\nMETHOD NAME: {name}"
+                        f"\nMETHOD: {f}",
+                    )
 
     def test_docstring_package(self):
         string = f">>> f = {self.package}."

cf/test/test_formula_terms.py

@@ -757,6 +757,17 @@ def test_compute_vertical_coordinates(self):
         g = f.compute_vertical_coordinates(verbose=None)
         altitude = g.auxiliary_coordinate("altitude")
 
+        # Test the 'key' parameter
+        k = f.compute_vertical_coordinates(key=True, verbose=None)
+        self.assertEqual(len(k), 2)  # expect a 2-tuple of field then key
+        self.assertTrue(k[0].equals(g))  # field result, same as above
+        self.assertEqual(k[1], "auxiliarycoordinate3")  # i.e. key for altitude
+        # key=True and inplace=True are incompatible inputs
+        with self.assertRaises(ValueError):
+            k = f.compute_vertical_coordinates(
+                key=True, inplace=True, verbose=None
+            )
+
         self.assertTrue(altitude)
         self.assertTrue(altitude.has_bounds())
         self.assertEqual(altitude.shape, (1,) + orog.shape)
@@ -881,6 +892,11 @@ def test_compute_vertical_coordinates(self):
         f = cf.example_field(0)
         g = f.compute_vertical_coordinates()
         self.assertTrue(g.equals(f))
+        # With key=True, expect the key (second in return 2-tuple) to be None
+        k = f.compute_vertical_coordinates(key=True)
+        self.assertEqual(len(k), 2)
+        self.assertTrue(k[0].equals(f))
+        self.assertEqual(k[1], None)
 
         # ------------------------------------------------------------
         # Check other types