Merge pull request #540 from davidhassell/dask-TODODASKDOCS

dask: Deal with TODODASKDOCS placeholders

Changelog.rst

@@ -8,6 +8,8 @@ version 3.14.0
 * New method: `cf.Field.to_dask_array`
 * New keyword parameter to `cf.write`: ``omit_data``
   (https://github.com/NCAS-CMS/cf-python/issues/477)
+* Extend functionality of `cf.Data.roll` and `cf.Field.roll` to allow
+  multiple axes to be rolled simultaneously.
 * Fixed bug that raised an exception when using the ``equal`` or
   ``exist`` keyword of `cf.aggregate`
   (https://github.com/NCAS-CMS/cf-python/issues/499)

cf/data/array/cfanetcdfarray.py

@@ -266,13 +266,20 @@ def _subarray_shapes(self, shapes):
 
         :Parameters:
 
-            shapes:
-                TODODASKDOCS
+           shapes: `int`, sequence, `dict` or `str`, optional
+                Define the subarray shapes.
+
+                Any value accepted by the *chunks* parameter of the
+                `dask.array.from_array` function is allowed.
+
+                The subarray sizes implied by *chunks* for a dimension
+                that has been fragmented are ignored, so their
+                specification is arbitrary.
 
         :Returns:
 
-            `list`
-                The subarray sizes along each uncompressed dimension.
+            `tuple`
+                The subarray sizes along each dimension.
 
         **Examples**
 
@@ -470,9 +477,9 @@ def _subarrays(self, subarray_shapes):
             u_shapes.append(c)
 
             if dim in f_dims:
-                # no fragmentation along this dimension
                 f_locations.append(tuple(range(nc)))
             else:
+                # No fragmentation along this dimension
                 f_locations.append((0,) * nc)
 
             c = tuple(accumulate((0,) + c))

cf/data/array/fullarray.py

@@ -22,20 +22,37 @@ def __init__(
     ):
         """**Initialisation**
 
-        TODODASKDOCS
+        :Parameters:
 
-            :Parameters:
+            fill_value : scalar, optional
+                The fill value for the array. May be set to
+                `cf.masked` or `np.ma.masked`.
 
-                dtype : numpy.dtype
-                    The numpy data type of the data array.
+            dtype: `numpy.dtype`
+                The data type of the array.
 
-                shape : tuple
-                    The data array's dimension sizes.
+            shape: `tuple`
+                The array dimension sizes.
 
-                size : int
-                    Number of elements indexin the data array.
+            units: `str` or `None`, optional
+                The units of the netCDF variable. Set to `None` to
+                indicate that there are no units. If unset then the
+                units will be set to `None` during the first
+                `__getitem__` call.
 
-                fill_value : scalar, optional
+            calendar: `str` or `None`, optional
+                The calendar of the netCDF variable. By default, or if
+                set to `None`, then the CF default calendar is
+                assumed, if applicable. If unset then the calendar
+                will be set to `None` during the first `__getitem__`
+                call.
+
+            source: optional
+                Initialise the array from the given object.
+
+                {{init source}}
+
+            {{deep copy}}
 
         """
         super().__init__(source=source, copy=copy)
@@ -141,10 +158,19 @@ def __str__(self):
         return f"Filled with {fill_value!r}"
 
     def _set_units(self):
-        """TODODASKDOCS.
+        """The units and calendar properties.
+
+        These are the values set during initialisation, defaulting to
+        `None` if either was not set at that time.
 
         .. versionadded:: TODODASKVER
 
+        :Returns:
+
+            `tuple`
+                The units and calendar values, either of which may be
+                `None`.
+
         """
         # TODOCFA: Consider moving _set_units to cfdm.Array, or some
         #          other common ancestor so that this, and other,
@@ -178,7 +204,7 @@ def get_fill_value(self):
 
         :Returns:
 
-            TODODASKDOCS
+                The fill value.
 
         """
         return self._get_component("fill_value", None)

cf/data/array/gatheredarray.py

@@ -30,7 +30,7 @@ def __repr__(self):
         return super().__repr__().replace("<", "<CF ", 1)
 
     def to_dask_array(self, chunks="auto"):
-        """Create a dask array TODODASKDOCS.
+        """Convert the data to a `dask` array.
 
         .. versionadded:: TODODASKVER
 
@@ -49,6 +49,7 @@ def to_dask_array(self, chunks="auto"):
         :Returns:
 
             `dask.array.Array`
+                The `dask` array representation.
 
         """
         from functools import partial

cf/data/array/mixin/arraymixin.py

@@ -9,10 +9,18 @@ class ArrayMixin:
     """
 
     def __array_function__(self, func, types, args, kwargs):
-        """Implement the `numpy` ``__array_function__`` protocol."""
+        """Implement the `numpy` ``__array_function__`` protocol.
+
+        .. versionadded:: TODODASKVER
+
+        """
         return NotImplemented
 
     @property
     def Units(self):
-        """TODODASKDOCS."""
+        """The `cf.Units` object containing the units of the array.
+
+        .. versionadded:: TODODASKVER
+
+        """
         return Units(self.get_units(), self.get_calendar(None))

cf/data/array/mixin/raggedarraymixin.py

@@ -2,14 +2,14 @@
 
 
 class RaggedArrayMixin(CompressedArrayMixin):
-    """Mixin TODODASKDOCS class for a container of an array.
+    """Mixin class for compressed ragged arrays.
 
     .. versionadded:: TODODASKVER
 
     """
 
     def to_dask_array(self, chunks="auto"):
-        """Create a dask array TODODASKDOCS.
+        """Convert the data to a `dask` array.
 
         .. versionadded:: TODODASKVER
 
@@ -28,6 +28,7 @@ def to_dask_array(self, chunks="auto"):
         :Returns:
 
             `dask.array.Array`
+                The `dask` array representation.
 
         """
         from functools import partial

cf/data/array/subsampledarray.py

@@ -80,7 +80,7 @@ def __repr__(self):
         return super().__repr__().replace("<", "<CF ", 1)
 
     def to_dask_array(self, chunks="auto"):
-        """Create a dask array TODODASKDOCS.
+        """Convert the data to a `dask` array.
 
         .. versionadded:: TODODASKVER
 
@@ -99,6 +99,7 @@ def to_dask_array(self, chunks="auto"):
         :Returns:
 
             `dask.array.Array`
+                The `dask` array representation.
 
         """
         from functools import partial

cf/data/array/umarray.py

@@ -355,18 +355,22 @@ def _set_units(self, int_hdr):
         return units, calendar
 
     def _test_condition(self, condition, int_hdr):
-        """Return `True` if a field satisfies the condition specified
-        for a STASH code to standard name conversion.
+        """Return `True` if a field satisfies a condition for a STASH
+        code to standard name conversion.
 
         .. versionadded:: TODODASKVER
 
         :Parameters:
 
             condition: `str`
-                TODODASKDOCS
+                The condition. If False then the condition is always
+                passed, otherwise the condition is specified as
+                ``'true_latitude_longitude'`` or
+                ``'rotated_latitude_longitude'``.
 
             int_hdr: `numpy.ndarray`
-                TODODASKDOCS
+                The integer lookup header used to evaluate the
+                condition.
 
         :Returns:
 
@@ -409,16 +413,15 @@ def _test_version(self, valid_from, valid_to, version):
         :Parameters:
 
             valid_from: number or `None`
-                TODODASKDOCS
+                The lower bound of the version range, e.g. ``4.5``,
+                ``606.1``, etc.
 
             valid_to: number or `None`
-                TODODASKDOCS
+                The upper bound of the version range, e.g. ``4.5``,
+                ``606.1``, etc.
 
             version: number
-                TODODASKDOCS
-
-            int_hdr: `numpy.ndarray`
-                TODODASKDOCS
+                The version of field, e.g. ``4.5``, ``606.1``, etc.
 
         :Returns: