From 9637d0e08e7b68bc110a686efd9f6456663656f7 Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Fri, 26 Apr 2024 15:29:19 -0500 Subject: [PATCH 1/5] clarify resource identifier docs Fixes: #https://github.com/dandi/dandi-cli/issues/1435 --- dandi/cli/cmd_download.py | 2 ++ dandi/cli/cmd_ls.py | 2 ++ dandi/dandiarchive.py | 9 +++++++++ 3 files changed, 13 insertions(+) diff --git a/dandi/cli/cmd_download.py b/dandi/cli/cmd_download.py index ee43459d6..e40f2b82d 100644 --- a/dandi/cli/cmd_download.py +++ b/dandi/cli/cmd_download.py @@ -18,6 +18,8 @@ help=f"""\ Download files or entire folders from DANDI. +\b +{_dandi_url_parser.resource_identifier_primer} \b {_dandi_url_parser.known_patterns} """ diff --git a/dandi/cli/cmd_ls.py b/dandi/cli/cmd_ls.py index eeb3dbecd..9ac9ed42f 100644 --- a/dandi/cli/cmd_ls.py +++ b/dandi/cli/cmd_ls.py @@ -26,6 +26,8 @@ The arguments may be either resource identifiers or paths to local files/directories. +\b +{_dandi_url_parser.resource_identifier_primer} \b {_dandi_url_parser.known_patterns} """ diff --git a/dandi/dandiarchive.py b/dandi/dandiarchive.py index 53c3506cb..1c1dc5c8b 100644 --- a/dandi/dandiarchive.py +++ b/dandi/dandiarchive.py @@ -675,6 +675,15 @@ class _dandi_url_parser: "https:///...", ), ] + resource_identifier_primer = """dandi commands and accept URLs and URL-like identifiers called + 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. +""" known_patterns = "Accepted resource identifier patterns:" + "\n - ".join( [""] + [display for _, _, display in known_urls] ) From d8bae4d607adf290f752553bd57b50762b0c38ba Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Fri, 26 Apr 2024 16:51:47 -0500 Subject: [PATCH 2/5] Add examples Co-authored-by: Yaroslav Halchenko --- dandi/cli/cmd_download.py | 21 ++++++++++++++++++++- dandi/dandiarchive.py | 19 ++++++++++--------- 2 files changed, 30 insertions(+), 10 deletions(-) diff --git a/dandi/cli/cmd_download.py b/dandi/cli/cmd_download.py index e40f2b82d..c7aff83dd 100644 --- a/dandi/cli/cmd_download.py +++ b/dandi/cli/cmd_download.py @@ -11,6 +11,20 @@ from ..download import DownloadExisting, DownloadFormat, PathType from ..utils import get_instance, joinurl +_examples = """ +EXAMPLES: \n +# Download only the dandiset.yaml \n +dandi download --download dandiset.yaml DANDI:000027 \n + +# Download only dandiset.yaml if there is a newer version \n +dandi download https://identifiers.org/DANDI:000027 --existing refresh + +# Download only the assets \n +dandi download --download assets DANDI:000027 + +# Download all from a specific version \n +dandi download DANDI:000027/0.210831.2033 +""" # The use of f-strings apparently makes this not a proper docstring, and so # click doesn't use it unless we explicitly assign it to `help`: @@ -20,9 +34,14 @@ \b {_dandi_url_parser.resource_identifier_primer} + \b {_dandi_url_parser.known_patterns} - """ + +\b +{_examples} + +""" ) @click.option( "-o", diff --git a/dandi/dandiarchive.py b/dandi/dandiarchive.py index 1c1dc5c8b..2d355b433 100644 --- a/dandi/dandiarchive.py +++ b/dandi/dandiarchive.py @@ -675,15 +675,16 @@ class _dandi_url_parser: "https:///...", ), ] - resource_identifier_primer = """dandi commands and accept URLs and URL-like identifiers called - 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. -""" + resource_identifier_primer = """RESOURCE ID/URLS:\n + dandi commands accept URLs and URL-like identifiers called + 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. + """ known_patterns = "Accepted resource identifier patterns:" + "\n - ".join( [""] + [display for _, _, display in known_urls] ) From 16c41b66996215a22a4ac51162ac0c46bb24ea3a Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Fri, 26 Apr 2024 19:18:27 -0500 Subject: [PATCH 3/5] line spacing --- dandi/cli/cmd_download.py | 1 + dandi/dandiarchive.py | 12 ++++++------ 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/dandi/cli/cmd_download.py b/dandi/cli/cmd_download.py index c7aff83dd..d44496b0b 100644 --- a/dandi/cli/cmd_download.py +++ b/dandi/cli/cmd_download.py @@ -26,6 +26,7 @@ dandi download DANDI:000027/0.210831.2033 """ + # The use of f-strings apparently makes this not a proper docstring, and so # click doesn't use it unless we explicitly assign it to `help`: @click.command( diff --git a/dandi/dandiarchive.py b/dandi/dandiarchive.py index 2d355b433..54bd9a772 100644 --- a/dandi/dandiarchive.py +++ b/dandi/dandiarchive.py @@ -676,14 +676,14 @@ class _dandi_url_parser: ), ] resource_identifier_primer = """RESOURCE ID/URLS:\n - dandi commands accept URLs and URL-like identifiers called - in the following formats for identifying Dandisets, - assets, and asset collections. + dandi commands accept URLs and URL-like identifiers called 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. + 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. """ known_patterns = "Accepted resource identifier patterns:" + "\n - ".join( [""] + [display for _, _, display in known_urls] From 3afd99b22d9871963ad9ddb6fb70861e2973e053 Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Sun, 28 Apr 2024 12:40:52 -0500 Subject: [PATCH 4/5] Add specific file example --- dandi/cli/cmd_download.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/dandi/cli/cmd_download.py b/dandi/cli/cmd_download.py index d44496b0b..fd62a7c05 100644 --- a/dandi/cli/cmd_download.py +++ b/dandi/cli/cmd_download.py @@ -24,6 +24,9 @@ # Download all from a specific version \n dandi download DANDI:000027/0.210831.2033 + +# Download a specific file or directory \n +dandi download dandi://DANDI/000027@0.210831.2033/sub-RAT123/sub-RAT123.nwb """ From 58c7c4c558e8662f19c55687d214b5987326d969 Mon Sep 17 00:00:00 2001 From: Austin Macdonald Date: Wed, 1 May 2024 10:49:13 -0500 Subject: [PATCH 5/5] Add example for directory Co-authored-by: Yaroslav Halchenko --- dandi/cli/cmd_download.py | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/dandi/cli/cmd_download.py b/dandi/cli/cmd_download.py index fd62a7c05..647d21951 100644 --- a/dandi/cli/cmd_download.py +++ b/dandi/cli/cmd_download.py @@ -12,20 +12,23 @@ from ..utils import get_instance, joinurl _examples = """ -EXAMPLES: \n -# Download only the dandiset.yaml \n -dandi download --download dandiset.yaml DANDI:000027 \n +EXAMPLES:\n +# Download only the dandiset.yaml\n +dandi download --download dandiset.yaml DANDI:000027\n -# Download only dandiset.yaml if there is a newer version \n +# Download only dandiset.yaml if there is a newer version\n dandi download https://identifiers.org/DANDI:000027 --existing refresh -# Download only the assets \n +# Download only the assets\n dandi download --download assets DANDI:000027 -# Download all from a specific version \n +# Download all from a specific version\n dandi download DANDI:000027/0.210831.2033 -# Download a specific file or directory \n +# Download a specific directory\n +dandi download dandi://DANDI/000027@0.210831.2033/sub-RAT123/ + +# Download a specific file\n dandi download dandi://DANDI/000027@0.210831.2033/sub-RAT123/sub-RAT123.nwb """