Merge pull request #180 from davidhassell/construct-access

Construct access API

Changelog.rst

@@ -3,10 +3,21 @@ Version 1.9.1.0
 
 **2022-??-??**
 
+* New method: `cfdm.Field.auxiliary_coordinate`
+* New method: `cfdm.Field.cell_measure`
+* New method: `cfdm.Field.cell_method`
+* New method: `cfdm.Field.coordinate`
+* New method: `cfdm.Field.coordinate_reference`
+* New method: `cfdm.Field.dimension_coordinate`
+* New method: `cfdm.Field.domain_ancillary`
+* New method: `cfdm.Field.domain_axis`
+* New method: `cfdm.Field.field_ancillary`
+* New construct retrieval API methods
+  (https://github.com/NCAS-CMS/cfdm/issues/179)
 * Implement (bar writing to netCDF files) lossy compression by
   coordinate subsampling (https://github.com/NCAS-CMS/cfdm/issues/167)
 
-  ----
+----
 
 Version 1.9.0.3
 ---------------

cfdm/docstring/docstring.py

@@ -303,10 +303,17 @@
                 Keyword arguments as accepted by `Constructs.filter`
                 that define additional construct selection
                 criteria.""",
-    # Returns constructs
-    "{{Returns constructs}}": """
-                The selected constructs in a new `Constructs` object,
-                unless modified by any *filter_kwargs* parameters.""",
+    # key: `bool`, optional
+    "{{key: `bool`, optional}}": """key: `bool`, optional
+                If True then return the selected construct
+                identifier. By default the construct itself is
+                returned.""",
+    # item: `bool`, optional
+    "{{item: `bool`, optional}}": """item: `bool`, optional
+                If True then return as a tuple the selected construct identifier
+                and the construct itself. By default only the construct
+                itself is returned. If *key* is True then *item* is
+                ignored.""",
     # chunks subarrays
     "{{subarrays chunks: ``-1`` or sequence, optional}}": """chunks: ``-1`` or sequence, optional
                 Define the subarray shapes.
@@ -341,6 +348,13 @@
     # ----------------------------------------------------------------
     # Method description susbstitutions (4 levels of indentataion)
     # ----------------------------------------------------------------
+    # Returns constructs
+    "{{Returns constructs}}": """
+                The selected constructs in a new `Constructs` object,
+                unless modified by any *filter_kwargs* parameters.""",
+    # Returns construct
+    "{{Returns construct}}": """The selected construct, or its identifier if *key* is
+                True, or a tuple of both if *item* is True.""",
     # string value match
     "{{value match}}": """A value may be any object that can match via the
                 ``==`` operator, or a `re.Pattern` object that matches

cfdm/domain.py

@@ -353,12 +353,12 @@ def apply_masking(self, inplace=False):
 
         **Examples**
 
-        >>> d = cfdm.example_field(0).domain
+        >>> d = {{package}}.example_domain(0)
         >>> x = d.construct('longitude')
-        >>> x.data[[0, -1]] = cfdm.masked
+        >>> x.data[[0, -1]] = {{package}}.masked
         >>> print(x.data.array)
         [-- 67.5 112.5 157.5 202.5 247.5 292.5 --]
-        >>> cfdm.write(d, 'masked.nc')
+        >>> {{package}}.write(d, 'masked.nc')
         >>> no_mask = {{package}}.read('masked.nc', domain=True, mask=False)[0]
         >>> no_mask_x = no_mask.construct('longitude')
         >>> print(no_mask_x.data.array)
@@ -393,7 +393,7 @@ def climatological_time_axes(self):
 
         **Examples**
 
-        >>> d = cfdm.example_field(0)
+        >>> d = {{package}}.example_domain(0)
         >>> d.climatological_time_axes()
         set()
 
@@ -437,7 +437,7 @@ def creation_commands(
 
         .. seealso:: `set_construct`,
                      `{{package}}.Data.creation_commands`,
-                     `{{package}}.example_field`
+                     `{{package}}.example_domain`
 
         :Parameters:
 
@@ -457,8 +457,7 @@ def creation_commands(
 
         **Examples**
 
-        >>> f = {{package}}.example_field(0)
-        >>> d = f.domain
+        >>> f = {{package}}.example_domain(0)
         >>> print(d.creation_commands())
         #
         # domain:
@@ -804,6 +803,80 @@ def dump(
 
         return "\n".join(string)
 
+    def get_data_axes(self, *identity, default=ValueError(), **filter_kwargs):
+        """Gets the keys of the axes spanned by the construct data.
+
+        Specifically, returns the keys of the domain axis constructs
+        spanned by the data of a metadata construct.
+
+        .. versionadded:: (cfdm) 1.7.0
+
+        .. seealso:: `del_data_axes`, `set_data_axes`
+
+        :Parameters:
+
+            identity, filter_kwargs: optional
+                Select the unique construct returned by
+                ``d.construct(*identity, **filter_kwargs)``. See
+                `construct` for details.
+
+                .. versionadded:: (cfdm) 1.9.1.0
+
+            default: optional
+                Return the value of the *default* parameter if the
+                data axes have not been set.
+
+                {{default Exception}}
+
+            {{filter_kwargs: optional}}
+
+                .. versionadded:: (cfdm) 1.9.1.0
+
+        :Returns:
+
+            `tuple`
+                The keys of the domain axis constructs spanned by the
+                data.
+
+        **Examples**
+
+        >>> d = {{package}}.example_domain(0)
+        >>> d.get_data_axes('latitude')
+        ('domainaxis0',)
+        >>> d.get_data_axes('time')
+        ('domainaxis2',)
+        >>> d.has_data_axes()
+        True
+        >>> d.del_data_axes()
+        ('domainaxis0', 'domainaxis1')
+        >>> d.has_data_axes()
+        False
+        >>> d.get_data_axes(default='no axes')
+        'no axes'
+
+        """
+        key = self.construct(
+            *identity, key=True, default=None, **filter_kwargs
+        )
+        if key is None:
+            if default is None:
+                return default
+
+            return self._default(
+                default, "Can't get axes for non-existent construct"
+            )
+
+        axes = super().get_data_axes(key, default=None)
+        if axes is None:
+            if default is None:
+                return default
+
+            return self._default(
+                default, f"Construct {key!r} has not had axes set"
+            )
+
+        return axes
+
     def get_filenames(self):
         """Return the file names containing the metadata construct data.
 
@@ -816,7 +889,7 @@ def get_filenames(self):
 
         **Examples**
 
-        >>> d = {{package}}.example_field(0).domain
+        >>> d = {{package}}.example_domain(0)
         >>> {{package}}.write(d, 'temp_file.nc')
         >>> e = {{package}}.read('temp_file.nc', domain=True)[0]
         >>> e.get_filenames()