Merge pull request #1548 from kabilar/docs

Update docs to generalize from `DANDI Archive` to `DANDI instance`

.github/workflows/test.yml

@@ -110,7 +110,7 @@ jobs:
         do python "$f"
         done
 
-    - name: Run Dandi API tests only
+    - name: Run DANDI API tests only
       if: matrix.mode == 'dandi-api'
       run: |
         export DANDI_TESTS_AUDIT_CSV=/tmp/audit.csv

README.md

@@ -14,9 +14,9 @@ The [DANDI Python client](https://pypi.org/project/dandi/) allows you to:
 * Validate data to locally conform to standards
 * Organize your data locally before upload
 * Upload `Dandisets`
-* Interact with the DANDI archive's web API from Python
-* Delete data in the DANDI archive
-* Perform other auxiliary operations with data or the DANDI archive
+* Interact with the DANDI instance's web API from Python
+* Delete data in the DANDI instance
+* Perform other auxiliary operations with data on the DANDI instance
 
 **Note**: This project is under heavy development. See [the issues log](https://github.com/dandi/dandi-cli/issues) or
 [Work-in-Progress (WiP)](https://github.com/dandi/dandi-cli/pulls).
@@ -37,14 +37,14 @@ or
 ## CLI Tool
 
 This package provides a command line utility with a basic interface
-to help you prepare and upload your data to, or obtain data from, the [DANDI archive](http://dandiarchive.org).
+to help you prepare and upload your data to, or obtain data from, a DANDI instance such as the [DANDI Archive](http://dandiarchive.org).
 
 
 ```bash
 $> dandi
 Usage: dandi [OPTIONS] COMMAND [ARGS]...
 
-  A client to support interactions with DANDI archive
+  A client to support interactions with a DANDI instance, such as the DANDI Archive
   (http://dandiarchive.org).
 
   To see help for a specific command, run
@@ -65,7 +65,7 @@ Commands:
   delete            Delete dandisets and assets from the server.
   digest            Calculate file digests
   download          Download a file or entire folder from DANDI.
-  instances         List known Dandi Archive instances that the CLI can...
+  instances         List known DANDI instances that the CLI can interact
   ls                List .nwb files and dandisets metadata.
   move              Move or rename assets in a local Dandiset and/or on...
   organize          (Re)organize NWB files according to their metadata.
@@ -77,7 +77,7 @@ Run `dandi --help` or `dandi <subcommand> --help` (e.g. `dandi upload --help`) t
 
 ## Resources
 
-* To learn how to interact with the DANDI archive and for examples on how to use the DANDI Client in various use cases,
+* To learn how to interact with the DANDI Archive and for examples on how to use the DANDI Client in various use cases,
 see [the handbook](https://www.dandiarchive.org/handbook/)
   (specifically the sections on using the CLI to
 [download](https://www.dandiarchive.org/handbook/12_download/) and

dandi/cli/cmd_instances.py

@@ -11,7 +11,7 @@
 @click.command()
 @map_to_click_exceptions
 def instances():
-    """List known Dandi Archive instances that the CLI can interact with"""
+    """List known DANDI instances that the CLI can interact with"""
     yaml = ruamel.yaml.YAML(typ="safe")
     yaml.default_flow_style = False
     instances = {}

dandi/cli/command.py

@@ -70,7 +70,8 @@ def print_version(ctx, param, value):
 @click.option("--pdb", help="Fall into pdb if errors out", is_flag=True)
 @click.pass_context
 def main(ctx, log_level, pdb=False):
-    """A client to support interactions with DANDI archive (http://dandiarchive.org).
+    """A client to support interactions with DANDI instances, such as the DANDI
+    Archive (http://dandiarchive.org).
 
     To see help for a specific command, run
 

dandi/cli/tests/data/update_dandiset_from_doi/biorxiv.json

@@ -13,13 +13,13 @@
     ],
     "version": "draft",
     "@context": "https://raw.githubusercontent.com/dandi/schema/master/releases/0.6.4/context.json",
-    "citation": "Aguillon-Rodriguez, Valeria; Angelaki, Dora E.; Bayer, Hannah M.; Bonacchi, Niccol\u00f2; Carandini, Matteo; Cazettes, Fanny; Chapuis, Gaelle A.; Churchland, Anne K.; Dan, Yang; Dewitt, Eric E. J.; Faulkner, Mayo; Forrest, Hamish; Haetzel, Laura M.; Hausser, Michael; Hofer, Sonja B.; Hu, Fei; Khanal, Anup; Krasniak, Christopher S.; Laranjeira, In\u00eas; Mainen, Zachary F.; Meijer, Guido T.; Miska, Nathaniel J.; Mrsic-Flogel, Thomas D.; Murakami, Masayoshi; Noel, Jean-Paul; Pan-Vazquez, Alejandro; Rossant, Cyrille; Sanders, Joshua I.; Socha, Karolina Z.; Terry, Rebecca; Urai, Anne E.; Vergara, Hernando M.; Wells, Miles J.; Wilson, Christian J.; Witten, Ilana B.; Wool, Lauren E.; Zador, Anthony (2023) Standardized and reproducible measurement of decision-making in mice (Version draft) [Data set]. DANDI archive. http://localhost:8085/dandiset/000001/draft",
+    "citation": "Aguillon-Rodriguez, Valeria; Angelaki, Dora E.; Bayer, Hannah M.; Bonacchi, Niccol\u00f2; Carandini, Matteo; Cazettes, Fanny; Chapuis, Gaelle A.; Churchland, Anne K.; Dan, Yang; Dewitt, Eric E. J.; Faulkner, Mayo; Forrest, Hamish; Haetzel, Laura M.; Hausser, Michael; Hofer, Sonja B.; Hu, Fei; Khanal, Anup; Krasniak, Christopher S.; Laranjeira, In\u00eas; Mainen, Zachary F.; Meijer, Guido T.; Miska, Nathaniel J.; Mrsic-Flogel, Thomas D.; Murakami, Masayoshi; Noel, Jean-Paul; Pan-Vazquez, Alejandro; Rossant, Cyrille; Sanders, Joshua I.; Socha, Karolina Z.; Terry, Rebecca; Urai, Anne E.; Vergara, Hernando M.; Wells, Miles J.; Wilson, Christian J.; Witten, Ilana B.; Wool, Lauren E.; Zador, Anthony (2023) Standardized and reproducible measurement of decision-making in mice (Version draft) [Data set]. DANDI Archive. http://localhost:8085/dandiset/000001/draft",
     "schemaKey": "Dandiset",
     "identifier": "DANDI:000001",
     "repository": "http://localhost:8085",
     "contributor": [
         {
-            "name": "Tests, Dandi-Cli",
+            "name": "Tests, DANDI-Cli",
             "email": "[email protected]",
             "roleName": [
                 "dcite:Author",

dandi/cli/tests/data/update_dandiset_from_doi/elife.json

@@ -13,13 +13,13 @@
     ],
     "version": "draft",
     "@context": "https://raw.githubusercontent.com/dandi/schema/master/releases/0.6.4/context.json",
-    "citation": "Chowdhury, Raeed H; Glaser, Joshua I; Miller, Lee E (2023) Area 2 of primary somatosensory cortex encodes kinematics of the whole arm (Version draft) [Data set]. DANDI archive. http://localhost:8085/dandiset/000004/draft",
+    "citation": "Chowdhury, Raeed H; Glaser, Joshua I; Miller, Lee E (2023) Area 2 of primary somatosensory cortex encodes kinematics of the whole arm (Version draft) [Data set]. DANDI Archive. http://localhost:8085/dandiset/000004/draft",
     "schemaKey": "Dandiset",
     "identifier": "DANDI:000004",
     "repository": "http://localhost:8085",
     "contributor": [
         {
-            "name": "Tests, Dandi-Cli",
+            "name": "Tests, DANDI-Cli",
             "email": "[email protected]",
             "roleName": [
                 "dcite:Author",

dandi/cli/tests/data/update_dandiset_from_doi/jneurosci.json

@@ -13,13 +13,13 @@
     ],
     "version": "draft",
     "@context": "https://raw.githubusercontent.com/dandi/schema/master/releases/0.6.4/context.json",
-    "citation": "Ito, Makoto; Doya, Kenji (2023) Validation of Decision-Making Models and Analysis of Decision Variables in the Rat Basal Ganglia (Version draft) [Data set]. DANDI archive. http://localhost:8085/dandiset/000002/draft",
+    "citation": "Ito, Makoto; Doya, Kenji (2023) Validation of Decision-Making Models and Analysis of Decision Variables in the Rat Basal Ganglia (Version draft) [Data set]. DANDI Archive. http://localhost:8085/dandiset/000002/draft",
     "schemaKey": "Dandiset",
     "identifier": "DANDI:000002",
     "repository": "http://localhost:8085",
     "contributor": [
         {
-            "name": "Tests, Dandi-Cli",
+            "name": "Tests, DANDI-Cli",
             "email": "[email protected]",
             "roleName": [
                 "dcite:Author",

dandi/cli/tests/data/update_dandiset_from_doi/nature.json

@@ -13,13 +13,13 @@
     ],
     "version": "draft",
     "@context": "https://raw.githubusercontent.com/dandi/schema/master/releases/0.6.4/context.json",
-    "citation": "Sit, Kevin K.; Goard, Michael J. (2023) Coregistration of heading to visual cues in retrosplenial cortex (Version draft) [Data set]. DANDI archive. http://localhost:8085/dandiset/000005/draft",
+    "citation": "Sit, Kevin K.; Goard, Michael J. (2023) Coregistration of heading to visual cues in retrosplenial cortex (Version draft) [Data set]. DANDI Archive. http://localhost:8085/dandiset/000005/draft",
     "schemaKey": "Dandiset",
     "identifier": "DANDI:000005",
     "repository": "http://localhost:8085",
     "contributor": [
         {
-            "name": "Tests, Dandi-Cli",
+            "name": "Tests, DANDI-Cli",
             "email": "[email protected]",
             "roleName": [
                 "dcite:Author",

dandi/cli/tests/data/update_dandiset_from_doi/neuron.json

@@ -13,13 +13,13 @@
     ],
     "version": "draft",
     "@context": "https://raw.githubusercontent.com/dandi/schema/master/releases/0.6.4/context.json",
-    "citation": "Tingley, David; Buzs\u00e1ki, Gy\u00f6rgy (2023) Routing of Hippocampal Ripples to Subcortical Structures via the Lateral Septum (Version draft) [Data set]. DANDI archive. http://localhost:8085/dandiset/000003/draft",
+    "citation": "Tingley, David; Buzs\u00e1ki, Gy\u00f6rgy (2023) Routing of Hippocampal Ripples to Subcortical Structures via the Lateral Septum (Version draft) [Data set]. DANDI Archive. http://localhost:8085/dandiset/000003/draft",
     "schemaKey": "Dandiset",
     "identifier": "DANDI:000003",
     "repository": "http://localhost:8085",
     "contributor": [
         {
-            "name": "Tests, Dandi-Cli",
+            "name": "Tests, DANDI-Cli",
             "email": "[email protected]",
             "roleName": [
                 "dcite:Author",

dandi/conftest.py

@@ -10,7 +10,7 @@ def pytest_addoption(parser: Parser) -> None:
         "--dandi-api",
         action="store_true",
         default=False,
-        help="Only run tests of the new Django Dandi API",
+        help="Only run tests of the new Django DANDI API",
     )
     parser.addoption(
         "--scheduled",

dandi/dandiapi.py

@@ -397,7 +397,7 @@ def get_page(pageno: int) -> list:
 
 
 class DandiAPIClient(RESTFullAPIClient):
-    """A client for interacting with a Dandi Archive server"""
+    """A client for interacting with a DANDI API server"""
 
     def __init__(
         self,
@@ -406,7 +406,7 @@ def __init__(
         dandi_instance: DandiInstance | None = None,
     ) -> None:
         """
-        Construct a client instance for the given API URL or Dandi instance
+        Construct a client instance for the given API URL or DANDI instance
         (mutually exclusive options).  If no URL or instance is supplied, the
         instance specified by the :envvar:`DANDI_INSTANCE` environment variable
         (default value: ``"dandi"``) is used.
@@ -442,7 +442,7 @@ def for_dandi_instance(
     ) -> DandiAPIClient:
         """
         Construct a client instance for the server identified by ``instance``
-        (either the name of a registered Dandi Archive instance or a
+        (either the name of a registered DANDI instance or a
         `DandiInstance` instance) and an optional authentication token/API key.
         If no token is supplied and ``authenticate`` is true,
         `dandi_authenticate()` is called on the instance before returning it.
@@ -638,7 +638,7 @@ def create_dandiset(
 
     def check_schema_version(self, schema_version: str | None = None) -> None:
         """
-        Confirms that the server is using the same version of the Dandi schema
+        Confirms that the server is using the same version of the DANDI schema
         as the client.  If it is not, a `SchemaVersionError` is raised.
 
         :param schema_version: the schema version to confirm that the server
@@ -889,7 +889,7 @@ def draft_version(self) -> Version:
     @property
     def api_path(self) -> str:
         """
-        The path (relative to the base endpoint for a Dandi Archive API) at
+        The path (relative to the base endpoint for the DANDI API) at
         which API requests for interacting with the Dandiset itself are made
         """
         return f"/dandisets/{self.identifier}/"
@@ -905,7 +905,7 @@ def api_url(self) -> str:
     @property
     def version_api_path(self) -> str:
         """
-        The path (relative to the base endpoint for a Dandi Archive API) at
+        The path (relative to the base endpoint for the DANDI API) at
         which API requests for interacting with the version in question of the
         Dandiset are made
         """
@@ -1429,7 +1429,7 @@ def from_base_data(
     @property
     def api_path(self) -> str:
         """
-        The path (relative to the base endpoint for a Dandi Archive API) at
+        The path (relative to the base endpoint for the DANDI API) at
         which API requests for interacting with the asset itself are made
         """
         return f"/assets/{self.identifier}/"
@@ -1639,7 +1639,7 @@ def digest_type(self) -> models.DigestType:
         """
         .. versionadded:: 0.36.0
 
-        The primary digest algorithm used by Dandi Archive for the asset,
+        The primary digest algorithm used by DANDI for the asset,
         determined based on its underlying data: dandi-etag for blob resources,
         dandi-zarr-checksum for Zarr resources
         """
@@ -1825,7 +1825,7 @@ def from_data(
     @property
     def api_path(self) -> str:
         """
-        The path (relative to the base endpoint for a Dandi Archive API) at
+        The path (relative to the base endpoint for the DANDI API) at
         which API requests for interacting with the asset itself are made
         """
         return f"/dandisets/{self.dandiset_id}/versions/{self.version_id}/assets/{self.identifier}/"

dandi/dandiarchive.py

@@ -1,6 +1,6 @@
 """
 This module provides functionality for parsing URLs and other resource
-identifiers for Dandisets & assets on Dandi Archive servers and for fetching
+identifiers for Dandisets & assets on DANDI instances and for fetching
 the objects to which the URLs refer.  See :ref:`resource_ids` for a list of
 accepted URL formats.
 
@@ -9,7 +9,7 @@
 Dandiset and/or assets specified in the URL.  Call an instance's
 `~ParsedDandiURL.get_dandiset()` and/or `~ParsedDandiURL.get_assets()` to get
 the assets, passing in a `~dandi.dandiapi.DandiAPIClient` for the appropriate
-Dandi Archive API instance; an unauthenticated client pointing to the correct
+DANDI API instance; an unauthenticated client pointing to the correct
 instance can be acquired via the `~ParsedDandiURL.get_client()` method.  As a
 convenience, one can acquire a client, the Dandiset, and an iterator of all
 assets by using the `~ParsedDandiAPI.navigate()` context manager like so:
@@ -59,7 +59,7 @@
 @dataclass
 class ParsedDandiURL(ABC):
     """
-    Parsed representation of a URL pointing to a Dandi Archive resource
+    Parsed representation of a URL pointing to a DANDI resource
     (Dandiset or asset(s)).  Subclasses must implement `get_assets()`.
 
     Most methods take a ``client: DandiAPIClient`` argument, which must be a
@@ -69,7 +69,7 @@ class ParsedDandiURL(ABC):
     passed instead.
     """
 
-    #: The Dandi Archive instance that the URL points to
+    #: The DANDI instance that the URL points to
     instance: DandiInstance
     #: The ID of the Dandiset given in the URL
     dandiset_id: str | None
@@ -80,7 +80,7 @@ class ParsedDandiURL(ABC):
 
     @property
     def api_url(self) -> AnyHttpUrl:
-        """The base URL of the Dandi API service, without a trailing slash"""
+        """The base URL of the DANDI API service, without a trailing slash"""
         # Kept for backwards compatibility
         adapter = TypeAdapter(AnyHttpUrl)
         return adapter.validate_python(self.instance.api.rstrip("/"))
@@ -717,7 +717,7 @@ def parse(
         cls, url: str, *, map_instance: bool = True, glob: bool = False
     ) -> ParsedDandiURL:
         """
-        Parse a Dandi Archive URL and return a `ParsedDandiURL` instance.  See
+        Parse a DANDI instance URL and return a `ParsedDandiURL` instance.  See
         :ref:`resource_ids` for the supported URL formats.
 
         .. versionadded:: 0.54.0

dandi/delete.py

@@ -126,7 +126,7 @@ def register_url(self, url: str) -> None:
         if isinstance(parsed_url, DandisetURL):
             if parsed_url.version_id is not None:
                 raise NotImplementedError(
-                    "Dandi API server does not support deletion of individual"
+                    "DANDI API server does not support deletion of individual"
                     " versions of a dandiset"
                 )
             assert parsed_url.dandiset_id is not None

dandi/download.py

@@ -262,7 +262,7 @@ def download_generator(self) -> Iterator[dict]:
 
         This function is a generator which yields records on ongoing
         activities.  Activities include traversal of the remote resource (DANDI
-        archive), download of individual assets while yielding records (TODO:
+        Archive), download of individual assets while yielding records (TODO:
         schema) while validating their checksums "on the fly", etc.
         """
 

dandi/exceptions.py

@@ -14,7 +14,7 @@ class OrganizeImpossibleError(ValueError):
 
 
 class UnknownURLError(ValueError):
-    """Given url is not known to correspond to DANDI archive schema(s)"""
+    """Given url is not known to correspond to DANDI schema(s)"""
 
     pass
 

dandi/files/__init__.py

@@ -183,7 +183,7 @@ def dandi_file(
         dandiset_path = Path(dandiset_path)
         path = filepath.relative_to(dandiset_path).as_posix()
         if path == ".":
-            raise ValueError("Dandi file path cannot equal Dandiset path")
+            raise ValueError("DANDI file path cannot equal Dandiset path")
     else:
         path = filepath.name
     if filepath.is_file() and path == dandiset_metadata_file:

dandi/files/bases.py

@@ -71,7 +71,7 @@ def get_metadata(
         digest: Digest | None = None,
         ignore_errors: bool = True,
     ) -> CommonModel:
-        """Return the Dandi metadata for the file"""
+        """Return the DANDI metadata for the file"""
         ...
 
     @abstractmethod
@@ -165,7 +165,7 @@ def get_metadata(
         digest: Digest | None = None,
         ignore_errors: bool = True,
     ) -> BareAsset:
-        """Return the Dandi metadata for the asset"""
+        """Return the DANDI metadata for the asset"""
         ...
 
     # TODO: @validate_cache.memoize_path

dandi/files/zarr.py

@@ -95,7 +95,7 @@ def iterdir(self) -> Iterator[LocalZarrEntry]:
     def get_digest(self) -> Digest:
         """
         Calculate the DANDI etag digest for the entry.  If the entry is a
-        directory, the algorithm will be the Dandi Zarr checksum algorithm; if
+        directory, the algorithm will be the DANDI Zarr checksum algorithm; if
         it is a file, it will be MD5.
         """
         # Avoid heavy import by importing within function:
@@ -132,7 +132,7 @@ class ZarrStat:
 
     #: The total size of the asset
     size: int
-    #: The Dandi Zarr checksum of the asset
+    #: The DANDI Zarr checksum of the asset
     digest: Digest
     #: A list of all files in the asset in unspecified order
     files: list[LocalZarrEntry]

dandi/organize.py

@@ -1123,7 +1123,7 @@ def validate_organized_path(
                 severity=Severity.ERROR,
                 scope=Scope.FILE,
                 path=filepath,
-                message="Filename does not conform to Dandi standard",
+                message="Filename does not conform to DANDI standard",
                 path_regex=ORGANIZED_FILENAME_REGEX,
                 dandiset_path=dandiset_path,
             )

dandi/tests/fixtures.py

@@ -585,7 +585,7 @@ def mkdandiset(self, name: str, embargo: bool = False) -> SampleDandiset:
                 "contributor": [
                     {
                         "schemaKey": "Person",
-                        "name": "Tests, Dandi-Cli",
+                        "name": "Tests, DANDI-Cli",
                         "email": "[email protected]",
                         "roleName": ["dcite:Author", "dcite:ContactPerson"],
                     }

dandi/tests/test_delete.py

@@ -398,7 +398,7 @@ def test_delete_version(
             force=True,
         )
     assert str(excinfo.value) == (
-        "Dandi API server does not support deletion of individual versions of a"
+        "DANDI API server does not support deletion of individual versions of a"
         " dandiset"
     )
     delete_spy.assert_not_called()