From 010cef95431def9d62c98537b9315c73d5644757 Mon Sep 17 00:00:00 2001 From: Kabilar Gunalan Date: Tue, 10 Dec 2024 11:45:10 -0600 Subject: [PATCH 1/6] Update to generalize docs from `DANDI Archive` to `DANDI instance` --- .github/workflows/test.yml | 2 +- README.md | 14 +++++++------- dandi/cli/cmd_instances.py | 2 +- dandi/cli/command.py | 2 +- .../data/update_dandiset_from_doi/biorxiv.json | 4 ++-- .../data/update_dandiset_from_doi/elife.json | 4 ++-- .../update_dandiset_from_doi/jneurosci.json | 4 ++-- .../data/update_dandiset_from_doi/nature.json | 4 ++-- .../data/update_dandiset_from_doi/neuron.json | 4 ++-- dandi/conftest.py | 2 +- dandi/dandiapi.py | 18 +++++++++--------- dandi/dandiarchive.py | 12 ++++++------ dandi/delete.py | 2 +- dandi/download.py | 2 +- dandi/exceptions.py | 2 +- dandi/files/__init__.py | 2 +- dandi/files/bases.py | 4 ++-- dandi/files/zarr.py | 4 ++-- dandi/organize.py | 2 +- dandi/tests/fixtures.py | 2 +- dandi/tests/test_delete.py | 2 +- docs/design/python-api-1.md | 2 +- docs/source/cmdline/dandi.rst | 4 ++-- docs/source/cmdline/instances.rst | 2 +- docs/source/modref/dandiapi.rst | 2 +- docs/source/modref/index.rst | 5 ++--- docs/source/ref/urls.rst | 6 +++--- setup.cfg | 2 +- 28 files changed, 58 insertions(+), 59 deletions(-) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index b81066c4b..b09c8b1a6 100644 --- a/.github/workflows/test.yml +++ b/.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 diff --git a/README.md b/README.md index 8805dc705..5d3ac09fa 100644 --- a/README.md +++ b/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... 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 --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 diff --git a/dandi/cli/cmd_instances.py b/dandi/cli/cmd_instances.py index 7c893187c..a4594b13d 100644 --- a/dandi/cli/cmd_instances.py +++ b/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 = {} diff --git a/dandi/cli/command.py b/dandi/cli/command.py index 37c4818fc..209c210e8 100644 --- a/dandi/cli/command.py +++ b/dandi/cli/command.py @@ -70,7 +70,7 @@ 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 a DANDI instance, such as the DANDI Archive (http://dandiarchive.org). To see help for a specific command, run diff --git a/dandi/cli/tests/data/update_dandiset_from_doi/biorxiv.json b/dandi/cli/tests/data/update_dandiset_from_doi/biorxiv.json index ac14fb425..11ca3a46e 100644 --- a/dandi/cli/tests/data/update_dandiset_from_doi/biorxiv.json +++ b/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": "nemo@example.com", "roleName": [ "dcite:Author", diff --git a/dandi/cli/tests/data/update_dandiset_from_doi/elife.json b/dandi/cli/tests/data/update_dandiset_from_doi/elife.json index 8d8a5e783..6fd685fe2 100644 --- a/dandi/cli/tests/data/update_dandiset_from_doi/elife.json +++ b/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": "nemo@example.com", "roleName": [ "dcite:Author", diff --git a/dandi/cli/tests/data/update_dandiset_from_doi/jneurosci.json b/dandi/cli/tests/data/update_dandiset_from_doi/jneurosci.json index 729e185f4..851a7a1e0 100644 --- a/dandi/cli/tests/data/update_dandiset_from_doi/jneurosci.json +++ b/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": "nemo@example.com", "roleName": [ "dcite:Author", diff --git a/dandi/cli/tests/data/update_dandiset_from_doi/nature.json b/dandi/cli/tests/data/update_dandiset_from_doi/nature.json index 11461684e..a13ae61fa 100644 --- a/dandi/cli/tests/data/update_dandiset_from_doi/nature.json +++ b/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": "nemo@example.com", "roleName": [ "dcite:Author", diff --git a/dandi/cli/tests/data/update_dandiset_from_doi/neuron.json b/dandi/cli/tests/data/update_dandiset_from_doi/neuron.json index fe2874f42..6c66782bc 100644 --- a/dandi/cli/tests/data/update_dandiset_from_doi/neuron.json +++ b/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": "nemo@example.com", "roleName": [ "dcite:Author", diff --git a/dandi/conftest.py b/dandi/conftest.py index a59f14b3d..93bd17afc 100644 --- a/dandi/conftest.py +++ b/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", diff --git a/dandi/dandiapi.py b/dandi/dandiapi.py index ffe727efd..f9bb4b10f 100644 --- a/dandi/dandiapi.py +++ b/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 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 a 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 a DANDI instance 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 instance 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 the DANDI instance 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 a DANDI instance 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}/" diff --git a/dandi/dandiarchive.py b/dandi/dandiarchive.py index 2c0c1ca1b..6a394b720 100644 --- a/dandi/dandiarchive.py +++ b/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 instance servers 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 instance 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 diff --git a/dandi/delete.py b/dandi/delete.py index 214fde211..e2d2948b0 100644 --- a/dandi/delete.py +++ b/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 diff --git a/dandi/download.py b/dandi/download.py index 235381420..17c20c0da 100644 --- a/dandi/download.py +++ b/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. """ diff --git a/dandi/exceptions.py b/dandi/exceptions.py index c317e5b9a..92e7ff160 100644 --- a/dandi/exceptions.py +++ b/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 Archive schema(s)""" pass diff --git a/dandi/files/__init__.py b/dandi/files/__init__.py index 1d20fbc54..cfdb458d9 100644 --- a/dandi/files/__init__.py +++ b/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: diff --git a/dandi/files/bases.py b/dandi/files/bases.py index 751f6d27e..8db802656 100644 --- a/dandi/files/bases.py +++ b/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 diff --git a/dandi/files/zarr.py b/dandi/files/zarr.py index 6b426fee4..1b28a44a4 100644 --- a/dandi/files/zarr.py +++ b/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] diff --git a/dandi/organize.py b/dandi/organize.py index 573b709d3..0de237da7 100644 --- a/dandi/organize.py +++ b/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, ) diff --git a/dandi/tests/fixtures.py b/dandi/tests/fixtures.py index ceaa2b7ab..3a326f855 100644 --- a/dandi/tests/fixtures.py +++ b/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": "nemo@example.com", "roleName": ["dcite:Author", "dcite:ContactPerson"], } diff --git a/dandi/tests/test_delete.py b/dandi/tests/test_delete.py index 2b33367ad..b3cf4b583 100644 --- a/dandi/tests/test_delete.py +++ b/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() diff --git a/docs/design/python-api-1.md b/docs/design/python-api-1.md index e8108ec2a..d99d29573 100644 --- a/docs/design/python-api-1.md +++ b/docs/design/python-api-1.md @@ -27,7 +27,7 @@ Designs for an improved Python API * Rename the `send_request()` method to `request()` to parallel `requests.Session.request()` * Rename the `parameters` argument to the HTTP methods to `params` to match `requests` * The `api_url` argument to `DandiAPIClient`'s constructor should default to the URL for the official Dandiarchive instance (which should also be available as a constant) - * Give `DandiAPIClient` a classmethod `for_dandi_instance(cls, instance: Union[str, dandi_instance], token=None, authenticate=True)` (Rethink name) that takes either the name of a Dandi instance or an actual `dandi_instance`, fetches a token from the environment, keychain, and/or user if one is not given and `authenticate` is true, and returns a `DandiAPIClient` instance + * Give `DandiAPIClient` a classmethod `for_dandi_instance(cls, instance: Union[str, dandi_instance], token=None, authenticate=True)` (Rethink name) that takes either the name of a DANDI instance or an actual `dandi_instance`, fetches a token from the environment, keychain, and/or user if one is not given and `authenticate` is true, and returns a `DandiAPIClient` instance * Most interaction with API resources should be via new `RemoteDandiset`, `Version`, and `RemoteAsset` classes and their methods * These classes (except `Version`?) will all contain a private `_client` attribute referring back to the associated `DandiAPIClient` instance. * Changes to `DandiAPIClient` methods: diff --git a/docs/source/cmdline/dandi.rst b/docs/source/cmdline/dandi.rst index f1777d4d9..db6cbcd94 100644 --- a/docs/source/cmdline/dandi.rst +++ b/docs/source/cmdline/dandi.rst @@ -5,8 +5,8 @@ dandi [] [] -A command-line client for interacting with the `DANDI Archive -`_. +A command-line client for interacting with a DANDI instance, such as the +`DANDI Archive `_. Global Options -------------- diff --git a/docs/source/cmdline/instances.rst b/docs/source/cmdline/instances.rst index a4a935682..de0034c08 100644 --- a/docs/source/cmdline/instances.rst +++ b/docs/source/cmdline/instances.rst @@ -5,7 +5,7 @@ dandi [] instances -List known Dandi Archive instances that can be passed to the +List known DANDI instances that can be passed to the ``-i``/``--dandi-instance`` option of other subcommands for the CLI to interact with. Output is in YAML. diff --git a/docs/source/modref/dandiapi.rst b/docs/source/modref/dandiapi.rst index a74bf5c89..529fd998a 100644 --- a/docs/source/modref/dandiapi.rst +++ b/docs/source/modref/dandiapi.rst @@ -3,7 +3,7 @@ ``dandi.dandiapi`` ================== -This module provides functionality for interacting with a Dandi Archive server +This module provides functionality for interacting with a DANDI instance server via the REST API. Interaction begins with the creation of a `DandiAPIClient` instance, which can be used to retrieve `RemoteDandiset` objects (representing Dandisets on the server) and `BaseRemoteAsset` objects (representing assets diff --git a/docs/source/modref/index.rst b/docs/source/modref/index.rst index 15b280b75..89572c7f7 100644 --- a/docs/source/modref/index.rst +++ b/docs/source/modref/index.rst @@ -27,8 +27,7 @@ Such interfaces mirror :ref:`Command-Line Interfaces `. Mid-level user interfaces ========================== -These interfaces provide object-oriented interfaces to manipulate Dandisets and assets in the -archive. +These interfaces provide object-oriented interfaces to manipulate Dandisets and assets on a DANDI instance. .. toctree:: @@ -37,7 +36,7 @@ archive. Low-level user interfaces ========================= -Low level interfaces to e.g. interact with archive REST API interfaces and files directly. +Low level interfaces to e.g. interact with the DANDI instance REST API and files directly. .. toctree:: diff --git a/docs/source/ref/urls.rst b/docs/source/ref/urls.rst index a1cc1a058..8c6811008 100644 --- a/docs/source/ref/urls.rst +++ b/docs/source/ref/urls.rst @@ -18,7 +18,7 @@ has one, and its draft version will be used otherwise. to one of the other URL formats - :samp:`DANDI:{dandiset-id}[/{version}]` (case insensitive) - — Refers to a Dandiset on the main archive instance named "dandi". + — Refers to a Dandiset on the main DANDI Archive instance named "dandi". `parse_dandi_url()` converts this format to a `DandisetURL`. - Any ``https://gui.dandiarchive.org/`` or @@ -62,12 +62,12 @@ has one, and its draft version will be used otherwise. `AssetGlobURL`. - :samp:`dandi://{instance-name}/{dandiset-id}[@{version}]` (where - ``instance-name`` is the name of a registered Dandi Archive instance) — + ``instance-name`` is the name of a registered DANDI instance) — Refers to a Dandiset. `parse_dandi_url()` converts this format to a `DandisetURL`. - :samp:`dandi://{instance-name}/{dandiset-id}[@{version}]/{path}` (where - ``instance-name`` is the name of a registered Dandi Archive instance) + ``instance-name`` is the name of a registered DANDI instance) - If the ``glob``/``--path-type glob`` option is in effect, the URL refers to a collection of assets whose paths match the glob pattern ``path``, and diff --git a/setup.cfg b/setup.cfg index d51ac6fd2..4620ae5b4 100644 --- a/setup.cfg +++ b/setup.cfg @@ -18,7 +18,7 @@ classifiers = Programming Language :: Python :: 3.12 Topic :: Scientific/Engineering license = Apache 2.0 -description = Command line client for interaction with DANDI archive elements +description = Command line client for interaction with DANDI instances long_description = file:README.md long_description_content_type = text/markdown; charset=UTF-8 platforms = OS Independent From 19327dde69ad467a54e74821a36cca99a0708e79 Mon Sep 17 00:00:00 2001 From: Kabilar Gunalan Date: Tue, 10 Dec 2024 12:55:21 -0600 Subject: [PATCH 2/6] Fix syntax --- dandi/cli/command.py | 2 +- dandi/dandiapi.py | 10 +++++----- dandi/dandiarchive.py | 4 ++-- dandi/exceptions.py | 2 +- docs/source/modref/dandiapi.rst | 2 +- docs/source/modref/index.rst | 4 ++-- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/dandi/cli/command.py b/dandi/cli/command.py index 209c210e8..02c93f5c4 100644 --- a/dandi/cli/command.py +++ b/dandi/cli/command.py @@ -70,7 +70,7 @@ 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 a DANDI instance, such as the 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 diff --git a/dandi/dandiapi.py b/dandi/dandiapi.py index f9bb4b10f..6e5142efa 100644 --- a/dandi/dandiapi.py +++ b/dandi/dandiapi.py @@ -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 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 instance 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 the DANDI instance 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 the DANDI instance 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 instance 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}/" diff --git a/dandi/dandiarchive.py b/dandi/dandiarchive.py index 6a394b720..afffe4450 100644 --- a/dandi/dandiarchive.py +++ b/dandi/dandiarchive.py @@ -1,6 +1,6 @@ """ This module provides functionality for parsing URLs and other resource -identifiers for Dandisets & assets on DANDI instance 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. @@ -59,7 +59,7 @@ @dataclass class ParsedDandiURL(ABC): """ - Parsed representation of a URL pointing to a DANDI instance 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 diff --git a/dandi/exceptions.py b/dandi/exceptions.py index 92e7ff160..01cd63c69 100644 --- a/dandi/exceptions.py +++ b/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 diff --git a/docs/source/modref/dandiapi.rst b/docs/source/modref/dandiapi.rst index 529fd998a..8212711d0 100644 --- a/docs/source/modref/dandiapi.rst +++ b/docs/source/modref/dandiapi.rst @@ -3,7 +3,7 @@ ``dandi.dandiapi`` ================== -This module provides functionality for interacting with a DANDI instance server +This module provides functionality for interacting with a DANDI instance via the REST API. Interaction begins with the creation of a `DandiAPIClient` instance, which can be used to retrieve `RemoteDandiset` objects (representing Dandisets on the server) and `BaseRemoteAsset` objects (representing assets diff --git a/docs/source/modref/index.rst b/docs/source/modref/index.rst index 89572c7f7..373b48502 100644 --- a/docs/source/modref/index.rst +++ b/docs/source/modref/index.rst @@ -27,7 +27,7 @@ Such interfaces mirror :ref:`Command-Line Interfaces `. Mid-level user interfaces ========================== -These interfaces provide object-oriented interfaces to manipulate Dandisets and assets on a DANDI instance. +Object-oriented interfaces to manipulate Dandisets and assets on a DANDI instance. .. toctree:: @@ -36,7 +36,7 @@ These interfaces provide object-oriented interfaces to manipulate Dandisets and Low-level user interfaces ========================= -Low level interfaces to e.g. interact with the DANDI instance REST API and files directly. +Low level interfaces to e.g. interact with the DANDI REST API and files directly. .. toctree:: From 7c25f8255332a5187bd17118a2bf652d1f0919ab Mon Sep 17 00:00:00 2001 From: Kabilar Gunalan Date: Tue, 10 Dec 2024 13:03:47 -0600 Subject: [PATCH 3/6] Fix linting error --- dandi/cli/command.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dandi/cli/command.py b/dandi/cli/command.py index 02c93f5c4..255926cd4 100644 --- a/dandi/cli/command.py +++ b/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 instances, such as the 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 From efb0b65bf0345e30cf356dfa683d6ef7aea33391 Mon Sep 17 00:00:00 2001 From: Kabilar Gunalan Date: Tue, 10 Dec 2024 13:05:32 -0600 Subject: [PATCH 4/6] Fix linting error --- dandi/cli/command.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dandi/cli/command.py b/dandi/cli/command.py index 255926cd4..d329795f7 100644 --- a/dandi/cli/command.py +++ b/dandi/cli/command.py @@ -70,7 +70,7 @@ 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 instances, such as the DANDI + """A client to support interactions with DANDI instances, such as the DANDI Archive (http://dandiarchive.org). To see help for a specific command, run From bf04f1a6cce04c36f0bb0e8f742a7aabb708f291 Mon Sep 17 00:00:00 2001 From: Kabilar Gunalan Date: Thu, 12 Dec 2024 22:27:40 -0600 Subject: [PATCH 5/6] Update dandi/dandiapi.py Co-authored-by: Yaroslav Halchenko --- dandi/dandiapi.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dandi/dandiapi.py b/dandi/dandiapi.py index 6e5142efa..e351b32e3 100644 --- a/dandi/dandiapi.py +++ b/dandi/dandiapi.py @@ -397,7 +397,7 @@ def get_page(pageno: int) -> list: class DandiAPIClient(RESTFullAPIClient): - """A client for interacting with a DANDI server""" + """A client for interacting with a DANDI API server""" def __init__( self, From 3d175a7c1ce982430448b2d39fa7a2dcc6e43f50 Mon Sep 17 00:00:00 2001 From: Kabilar Gunalan Date: Thu, 12 Dec 2024 22:28:43 -0600 Subject: [PATCH 6/6] Update README.md Co-authored-by: Yaroslav Halchenko --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 5d3ac09fa..26e1231e3 100644 --- a/README.md +++ b/README.md @@ -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 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.