simplify identifier on dandi download cli command

[satra]

this came up in #1434

currently dandi download help looks like this:

  Accepted resource identifier patterns:
   - DANDI:<dandiset id>[/<version>]
   - https://gui.dandiarchive.org/...
   - https://identifiers.org/DANDI:<dandiset id>[/<version id>] (<version id> cannot be 'draft')
   - https://<server>[/api]/[#/]dandiset/<dandiset id>[/<version>][/files[?location=<path>]]
   - https://*dandiarchive-org.netflify.app/...
   - https://<server>[/api]/dandisets/<dandiset id>[/versions[/<version>]]
   - https://<server>[/api]/assets/<asset id>[/download]
   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/<asset id>[/download]
   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/?path=<path>
   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/?glob=<glob>
   - dandi://<instance name>/<dandiset id>[@<version>][/<path>]
   - https://<server>/...

while this is completely fine for us, it's entirely cryptic to someone who has just managed to get python and dandi cli installed.

can we simplify this to

<identifier>/...

where identifier is essentially: DANDI:<dandiset id>[/<version>] or DANDI-sandbox ....

any other choices of identifier would be for developers only and can be disclosed to them.

[rly]

It would also be nice to provide a few concrete examples in the help message. Thanks!

[yarikoptic]

can we simplify this to

<identifier>/...

where identifier is essentially: DANDI:<dandiset id>[/<version>] or DANDI-sandbox ....

there is no DANDI-sandbox, so I do not see how that would simplify anything, more - cause a confusion IMHO. If you see how it could look, please suggest a PR -- might be easier to distill in that form.

It would also be nice to provide a few concrete examples in the help message. Thanks!

That indeed might be helpful: how to download only datasets.yaml, entire dandiset, folder, file.

[satra]

there is no DANDI-sandbox

yes, but we can implement the prefix change as part of the schema overhaul. the intent of this issue is about simplifying communication to users. there is nothing that tells the use what <server> is. perhaps also remove elements like gui.dandiarchive, netlify, etc.,.

[yarikoptic]

re examples, @asmacdo promised to help. For the rest -- needs more clarify on what is desired

[yarikoptic]

I will assume this one addressed by

• clarify resource identifier docs #1437

and now dandi download --help is

❯ dandi download --help
Usage: dandi download [OPTIONS] [URL]...

  Download files or entire folders from DANDI.

  RESOURCE ID/URLS:

      dandi commands accept URLs and URL-like identifiers called <resource
      ids> in the following formats for identifying Dandisets, assets, and
      asset collections.

      Text in [brackets] is optional.  A server field is a base API or GUI URL
      for a DANDI Archive instance.  If an optional ``version`` field is
      omitted from a URL, the given Dandiset's most recent published version
      will be used if it has one, and its draft version will be used
      otherwise.

  Accepted resource identifier patterns:
   - DANDI:<dandiset id>[/<version>]
   - https://gui.dandiarchive.org/...
   - https://identifiers.org/DANDI:<dandiset id>[/<version id>] (<version id> cannot be 'draft')
   - https://<server>[/api]/[#/]dandiset/<dandiset id>[/<version>][/files[?location=<path>]]
   - https://*dandiarchive-org.netlify.app/...
   - https://<server>[/api]/dandisets/<dandiset id>[/versions[/<version>]]
   - https://<server>[/api]/assets/<asset id>[/download]
   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/<asset id>[/download]
   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/?path=<path>
   - https://<server>[/api]/dandisets/<dandiset id>/versions/<version>/assets/?glob=<glob>
   - dandi://<instance name>/<dandiset id>[@<version>][/<path>]
   - https://<server>/...



  EXAMPLES:

  # Download only the dandiset.yaml

  dandi download --download dandiset.yaml DANDI:000027

  # Download only dandiset.yaml if there is a newer version

  dandi download https://identifiers.org/DANDI:000027 --existing refresh

  # Download only the assets

  dandi download --download assets DANDI:000027

  # Download all from a specific version

  dandi download DANDI:000027/0.210831.2033

  # Download a specific directory

  dandi download dandi://DANDI/000027@0.210831.2033/sub-RAT123/

  # Download a specific file

  dandi download dandi://DANDI/000027@0.210831.2033/sub-RAT123/sub-RAT123.nwb

Options:
  -o, --output-dir DIRECTORY      Directory where to download to (directory
                                  must exist). Files will be downloaded with
                                  paths relative to that directory.
  -e, --existing [error|skip|overwrite|overwrite-different|refresh]
                                  What to do if a file found existing locally.
                                  'refresh': verify that according to the size
                                  and mtime, it is the same file, if not -
                                  download and overwrite.  [default: error]
  -f, --format [pyout|debug]      Choose the format/frontend for output. TODO:
                                  support all of the ls
  --path-type [exact|glob]        Whether to interpret asset paths in URLs as
                                  exact matches or glob patterns  [default:
                                  exact]
  -J, --jobs N[:M]                Number of parallel download jobs and,
                                  optionally number of subjobs per Zarr asset
                                  [default: 6]
  --download [dandiset.yaml,assets,all]
                                  Comma-separated list of elements to download
                                  [default: all]
  --sync                          Delete local assets that do not exist on the
                                  server
  -i, --dandi-instance TEXT       DANDI Archive instance to download from. If
                                  any URLs are provided, they must point to
                                  the given instance. If no URL is provided,
                                  and there is a local dandiset.yaml file, the
                                  Dandiset with the identifier given in the
                                  file will be downloaded from the given
                                  instance.  [env var: DANDI_INSTANCE]
  --help                          Show this message and exit.

if anyone sees how/what to improve further, please submit a PR.