Revert "Allow a halo to be added by indices and subspace"

This reverts commit 3c54287.

Author: davidhassell

cf/docstring/docstring.py

@@ -80,14 +80,6 @@
         Whether `esmpy` logging is enabled or not is determined by
         `cf.regrid_logging`. If it is enabled then logging takes place
         after every call. By default logging is disabled.""",
-    # subspace halos
-    "{{subspace halos}}": """
-        If a halo is defined via a positional argument, then each
-        subspaced axis will be extended to include that many extra
-        elements at each "side" of the axis. The number of extra
-        elements will be automatically reduced if including the full
-        amount defined by the halo would extend the subspace beyond
-        the axis limits.""",
     # ----------------------------------------------------------------
     # Method description substitutions (3 levels of indentation)
     # ----------------------------------------------------------------
@@ -621,40 +613,6 @@
     "{{to_size: `int`, optional}}": """to_size: `int`, optional
                 Pad the axis after so that the new axis has the given
                 size.""",
-    # subspace mode options
-    "{{mode: optional}}": """mode: optional
-                Specify the mode of operation (``mode``) and a halo to
-                be added to the subspaced axes (``halo``) with
-                positional arguments in format ``mode``, or ``halo``,
-                or ``mode, halo``, or with no positional arguments at
-                all.
-
-                A mode of operation is given as a `str`, and a halo as
-                a non-negative `int` (or any object that can be
-                converted to one):
-
-                ==============  ======================================
-                *mode*          Description
-                ==============  ======================================
-                ````            If no positional arguments are
-                                provided then assume the
-                                ``'compress'`` mode of operation with
-                                no halo added to the subspaced
-                                axes.
-
-                ``mode``        Define the mode of operation with no
-                                halo added to the subspaced axes.
-
-                ``mode, halo``  Define a mode of operation, as well as
-                                a halo to be added to the subspaced
-                                axes.
-
-                ``halo``        Assume the ``'compress'`` mode of
-                                operation and define a halo to be
-                                added to the subspaced axes. Note that
-                                ``halo`` is equivalent to
-                                ``'compress', halo``.
-                ==============  ======================================""",
     # ----------------------------------------------------------------
     # Method description substitutions (4 levels of indentation)
     # ----------------------------------------------------------------
@@ -705,42 +663,4 @@
                 The removed CFA-netCDF file name substitution. If the
                 substitution was not defined then an empty dictionary
                 is returned.""",
-    # subspace valid modes Field
-    "{{subspace valid modes Field}}": """Valid modes are:
-
-                * ``'compress'`` This the default.
-                     Unselected locations are removed to create the
-                     subspace. If the result is not hyperrectangular
-                     then the minimum amount of unselected locations
-                     required to make it so will also be specially
-                     selected. Missing data is inserted at the
-                     specially selected locations, unless a halo has
-                     been defined (of any size, including 0).
-
-                * ``'envelope'``
-                     The subspace is the smallest hyperrectangular
-                     subspace that contains all of the selected
-                     locations. Missing data is inserted at unselected
-                     locations within the envelope, unless a halo has
-                     been defined (of any size, including 0).
-
-                * ``'full'``
-                     The subspace has the same domain as the original
-                     construct. Missing data is inserted at unselected
-                     locations, unless a halo has been defined (of any
-                     size, including 0).""",
-    # subspace valid modes Domain
-    "{{subspace valid modes Domain}}": """Valid modes are:
-
-                * ``'compress'`` This the default.
-                     Unselected locations are removed to create the
-                     subspace. If the result is not hyperrectangular
-                     then the minimum amount of unselected locations
-                     required to make it so will also be specially
-                     selected.
-
-                * ``'envelope'``
-                     The subspace is the smallest hyperrectangular
-                     subspace that contains all of the selected
-                     locations.""",
 }

cf/domain.py

@@ -743,7 +743,7 @@ def indices(self, *mode, **kwargs):
         """Create indices that define a subspace of the domain
         construct.
 
-        The indices returned by this method may be used to create the
+        The indices returned by this method be used to create the
         subspace by passing them to the `subspace` method of the
         original domain construct.
 
@@ -778,22 +778,34 @@ def indices(self, *mode, **kwargs):
           may still need to be inserted into the field construct's
           data.
 
-        **Halos**
-
-        {{subspace halos}}
-
         .. versionadded:: 3.11.0
 
         .. seealso:: `subspace`, `where`, `__getitem__`,
                      `__setitem__`, `cf.Field.indices`
 
         :Parameters:
 
-            {{mode: optional}}
-
-                {{subspace valid modes Domain}}
-
-            kwargs: optional
+            mode: `str`, *optional*
+                There are two modes of operation, each of which provides
+                indices for a different type of subspace:
+
+                ==============  ======================================
+                *mode*          Description
+                ==============  ======================================
+                ``'compress'``  This is the default mode. Unselected
+                                locations are removed to create the
+                                returned subspace. Note that if a
+                                multi-dimensional metadata construct
+                                is being used to define the indices
+                                then some missing data may still be
+                                inserted at unselected locations.
+
+                ``'envelope'``  The returned subspace is the smallest
+                                that contains all of the selected
+                                indices.
+                ==============  ======================================
+
+            kwargs: *optional*
                 A keyword name is an identity of a metadata construct,
                 and the keyword value provides a condition for
                 inferring indices that apply to the dimension (or
@@ -845,6 +857,19 @@ def indices(self, *mode, **kwargs):
                         : time(1) = [2019-01-01 00:00:00]
 
         """
+        if len(mode) > 1:
+            raise ValueError(
+                "Can't provide more than one positional argument. "
+                f"Got: {', '.join(repr(x) for x in mode)}"
+            )
+
+        if not mode or "compress" in mode:
+            mode = "compress"
+        elif "envelope" in mode:
+            mode = "envelope"
+        else:
+            raise ValueError(f"Invalid value for 'mode' argument: {mode[0]!r}")
+
         # Get the indices for every domain axis in the domain, without
         # any auxiliary masks.
         domain_indices = self._indices(mode, None, False, kwargs)
@@ -1095,19 +1120,19 @@ def roll(self, axis, shift, inplace=False):
         return d
 
     def subspace(self, *mode, **kwargs):
-        """Create a subspace of the field construct.
+        """Create indices that define a subspace of the domain
+        construct.
 
-        Creation of a new domain construct which spans a subspace of
-        the domain of an existing domain construct is achieved by
-        identifying indices based on the metadata constructs
-        (subspacing by metadata). The new domain construct is created
-        with the same properties as the original domain construct.
+        The indices returned by this method be used to create the subspace
+        by passing them to the `subspace` method of the original domain
+        construct.
 
-        **Subspacing by metadata**
+        The subspace is defined by identifying indices based on the
+        metadata constructs.
 
-        Subspacing by metadata selects metadata constructs and
-        specifies conditions on their data. Indices for subspacing are
-        then automatically inferred from where the conditions are met.
+        Metadata constructs are selected conditions are specified on their
+        data. Indices for subspacing are then automatically inferred from
+        where the conditions are met.
 
         Metadata constructs and the conditions on their data are defined
         by keyword parameters.
@@ -1117,9 +1142,6 @@ def subspace(self, *mode, **kwargs):
         * Multiple domain axes may be subspaced simultaneously, and it
           doesn't matter which order they are specified in.
 
-        * Subspace criteria may be provided for size 1 domain axes that
-          are not spanned by the field construct's data.
-
         * Explicit indices may also be assigned to a domain axis
           identified by a metadata construct, with either a Python `slice`
           object, or a sequence of integers or booleans.
@@ -1134,21 +1156,41 @@ def subspace(self, *mode, **kwargs):
           acting along orthogonal dimensions, some missing data may still
           need to be inserted into the field construct's data.
 
-        **Halos**
-
-        {{subspace halos}}
-
         .. versionadded:: 3.11.0
 
-        .. seealso:: `indices`, `cf.Field.subspace`
+        .. seealso:: `indices`
 
         :Parameters:
 
-            {{mode: optional}}
+            mode: `str`, *optional*
+                There are two modes of operation, each of which provides
+                indices for a different type of subspace:
+
+                ==============  ==========================================
+                *mode*          Description
+                ==============  ==========================================
+                ``'compress'``  Return indices that identify only the
+                                requested locations.
+
+                                This is the default mode.
+
+                                Note that if a multi-dimensional metadata
+                                construct is being used to define the
+                                indices then some unrequested locations
+                                may also be selected.
+
+                ``'envelope'``  The returned subspace is the smallest that
+                                contains all of the requested locations.
 
-                {{subspace valid modes Domain}}
+                ``'test'``      May be used on its own or in addition to
+                                one of the other positional arguments. Do
+                                not create a subspace, but return `True`
+                                or `False` depending on whether or not it
+                                is possible to create the specified
+                                subspace.
+                ==============  ==========================================
 
-            kwargs: optional
+            kwargs: *optional*
                 A keyword name is an identity of a metadata construct, and
                 the keyword value provides a condition for inferring
                 indices that apply to the dimension (or dimensions)