Demo custom constraint errors on download command

This command has one of the most complex input specification implemented
as nested constraints. Here is a demo of a (semi-structured) error message
rendering before this change:

```
❯ datalad download wurst
[ERROR  ] 1 command parameter constraint violation
spec=['wurst']
  does not match any of 3 alternatives
    - does not match any of 2 alternatives
      - not a recognized mapping
      - does not match any of 2 alternatives
        - the JSON object must be str, bytes or bytearray, not list
        - not a string
    - does not match any of 2 alternatives
      - not enough values to unpack (expected 2, got 1)
      - does not match any of 2 alternatives
        - Expecting value: line 1 column 1 (char 0)
        - URL is missing 'scheme' component
    - not '-', or a path to an existing file
```

There is a lot of information already, but clarity is lacking.

This change applied the `WithDescription` meta constraint to bring
clarity to the error messages. The new message for the same invalid
call used above now looks like this

```
❯ datalad download wurst
[ERROR  ] 1 command parameter constraint violation
spec=['wurst']
  does not provide URL->(PATH|-) mapping(s)
    - not a single item
      - not a dict, length-2-iterable, or space-delimited str
      - not a URL with a path component from which a filename can be derived
      - not a JSON-encoded str with an object or length-2-array
    - not a list of any such item
    - not a path to a file with one such item per-line, nor '-' to read any such item from STDIN
```

The custom message use the fact that the order of constraints and
therefore the order in which violations are detected is deterministic.
The respective individual message can reference prior messages such that
the result is a more cohesive whole that, importantly, can avoid
needless repetition of information.

Conceptually (and technically), although this message is composed of the
output of multiple constraints, it is neverthess still a *single*
message, produced by a *single* top-level constraint (`AnyOf`).
Therefore, we need not worry much about this information being taken
apart and thereby becoming harder to comprehend or incomplete.

The particular set of example message may inform #274 and guidelines on
how constraints and their messaging should be implemented.

Author: mih

datalad_next/commands/download.py

@@ -35,6 +35,7 @@
     EnsurePath,
     EnsureURL,
     EnsureValue,
+    WithDescription,
 )
 from datalad_next.constraints.dataset import EnsureDataset
 from datalad_next.url_operations.any import AnyUrlOperations
@@ -101,37 +102,64 @@ class Download(ValidatedInterface):
     # The special value '-' is used to indicate stdout
     # if given as a single string, we support single-space-delimited items:
     # "<url> <path>"
-    url2path_constraint = EnsureMapping(
-        key=url_constraint,
-        value=EnsureValue('-') | EnsurePath(),
-        delimiter=' ',
-        # we disallow length-2 sequences to be able to distinguish from
-        # a length-2 list of URLs.
-        # the key issue is the flexibility of EnsurePath -- pretty much
-        # anything could be a valid unix path
-        allow_length2_sequence=False,
+    url2path_constraint = WithDescription(
+        EnsureMapping(
+            key=url_constraint,
+            value=EnsureValue('-') | EnsurePath(),
+            delimiter=' ',
+            # we disallow length-2 sequences to be able to distinguish from
+            # a length-2 list of URLs.
+            # the key issue is the flexibility of EnsurePath -- pretty much
+            # anything could be a valid unix path
+            allow_length2_sequence=False,
+        ),
+        error_message=f'not a dict, length-2-iterable, or space-delimited str',
     )
     # each specification items is either a mapping url->path, just a url, or a
     # JSON-encoded url->path mapping.  the order is complex-to-simple for the
     # first two (to be able to distinguish a mapping from an encoded URL. The
     # JSON-encoding is tried last, it want match accidentally)
-    spec_item_constraint = url2path_constraint | (
-        (
-            EnsureJSON() | EnsureURLFilenamePairFromURL()
-        ) & url2path_constraint)
+    urlonly_item_constraint = WithDescription(
+        EnsureURLFilenamePairFromURL() & url2path_constraint,
+        error_message='not a URL with a path component '
+        'from which a filename can be derived',
+    )
+    json_item_constraint = WithDescription(
+        EnsureJSON() & url2path_constraint,
+        error_message='not a JSON-encoded str with an object or length-2-array',
+    )
+    any_item_constraint = WithDescription(
+        AnyOf(
+            # TODO explain
+            url2path_constraint,
+            urlonly_item_constraint,
+            json_item_constraint,
+        ),
+        error_message='not a single item\n{__itemized_causes__}',
+    )
 
     # we support reading specification items (matching any format defined
     # above) as
     # - a single item
     # - as a list of items
     # - a list given in a file, or via stdin (or any file-like in Python)
-    spec_constraint = AnyOf(
-        spec_item_constraint,
-        EnsureListOf(spec_item_constraint),
-        EnsureGeneratorFromFileLike(
-            spec_item_constraint,
-            exc_mode='yield',
+    spec_constraint = WithDescription(
+        AnyOf(
+            any_item_constraint,
+            WithDescription(
+                EnsureListOf(any_item_constraint),
+                error_message='not a list of any such item',
+            ),
+            WithDescription(
+                EnsureGeneratorFromFileLike(
+                    any_item_constraint,
+                    exc_mode='yield',
+                ),
+                error_message="not a path to a file with one such item per-line, "
+                "nor '-' to read any such item from STDIN",
+            ),
         ),
+        error_message="does not provide URL->(PATH|-) mapping(s)\n{__itemized_causes__}"
     )
 
     force_choices = EnsureChoice('overwrite-existing')