dandifs 0.1.0__tar.gz

dandifs-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Yaël Balbastre
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dandifs-0.1.0/PKG-INFO

@@ -0,0 +1,188 @@
+Metadata-Version: 2.4
+Name: dandifs
+Version: 0.1.0
+Summary: A fsspec filesystem for the DANDI archive
+Author-email: Yael Balbastre <y.balbastre@ucl.ac.uk>
+Maintainer-email: Yael Balbastre <y.balbastre@ucl.ac.uk>
+License: MIT License
+        
+        Copyright (c) 2025 Yaël Balbastre
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/balbasty/dandifs
+Project-URL: Issues, https://github.com/balbasty/dandifs/issues
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fsspec[http]>=2022.1.0
+Requires-Dist: aiohttp
+Requires-Dist: typing_extensions
+Provides-Extra: auth
+Requires-Dist: keyring!=23.9.0; extra == "auth"
+Requires-Dist: keyrings.alt; extra == "auth"
+Requires-Dist: pycryptodomex; extra == "auth"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-asyncio; extra == "test"
+Requires-Dist: aioresponses; extra == "test"
+Requires-Dist: aiohttp<3.14; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff==0.16.5; extra == "lint"
+Requires-Dist: codespell; extra == "lint"
+Dynamic: license-file
+
+# dandifs
+
+An [`fsspec`](https://filesystem-spec.readthedocs.io) filesystem for the
+[DANDI archive](https://dandiarchive.org).
+
+`dandifs` resolves `dandi://` URLs to the bytes behind DANDI assets, including
+files that live **inside a Zarr asset**. It is async-first (built on
+`aiohttp`, via fsspec's `AsyncFileSystem`), has a small dependency footprint,
+and does **not** depend on `dandi` or `dandi-schema`.
+
+## Install
+
+```bash
+pip install dandifs
+# optional: keyring-based credentials for private/embargoed dandisets
+pip install "dandifs[auth]"
+```
+
+## URL format
+
+```
+dandi://<instance>/<dandiset>[@<version>]/<path>
+```
+
+- `<instance>` — a registered instance name (`dandi`, `dandi-staging`,
+  `ember`, `ember-sandbox`, ...) or any DANDI-schema server (see *Instances*).
+- `<dandiset>` — the six-digit dandiset identifier, e.g. `000026`.
+- `@<version>` — optional; defaults to the most recent published version, or
+  the draft version if none is published.
+- `<path>` — a path within the dandiset. It may descend **into** a Zarr asset:
+  in `.../image.zarr/0/0/0`, only `.../image.zarr` is a registered asset and
+  `0/0/0` is a key inside that Zarr's store.
+
+## Public surface
+
+The **only** public API is the filesystem class, `DandiFileSystem`.
+Everything else is internal.
+
+## Usage
+
+### Via the registered protocol
+
+```python
+import fsspec, json
+
+with fsspec.open(
+    "dandi://dandi/000026/rawdata/sub-I38/ses-MRI/anat/"
+    "sub-I38_ses-MRI-echo-4_flip-4_VFA.json"
+) as f:
+    info = json.load(f)
+```
+
+### Bound to a dandiset
+
+```python
+from dandifs import DandiFileSystem
+
+fs = DandiFileSystem("000026")            # bind to a dandiset (+ version)
+fs.ls("rawdata")                          # browse
+fs.glob("**/anat/*.json")                 # glob assets
+with fs.open("rawdata/sub-I38/.../VFA.json") as f:
+    data = f.read()
+```
+
+### Files inside a Zarr asset
+
+```python
+fs = DandiFileSystem("000108")
+
+fs.ls("path/to/image.zarr")               # list entries inside the Zarr
+fs.info("path/to/image.zarr/0/0/0")       # stat a chunk
+with fs.open("path/to/image.zarr/0/0/0", "rb") as f:
+    chunk = f.read()                      # read chunk bytes
+```
+
+This also works transparently with libraries that open a store through fsspec,
+e.g. `zarr.open("dandi://dandi/<id>/path/to/image.zarr")`.
+
+### Async
+
+`DandiFileSystem` is a real async filesystem. Following fsspec's
+[`AsyncFileSystem`](https://filesystem-spec.readthedocs.io/en/latest/async.html)
+convention, the asynchronous API **is** the set of underscore-prefixed
+coroutine methods (`_ls`, `_info`, `_cat_file`, `_cat`, `_exists`, `_glob`,
+`_get`, ...) — the same pattern used by `s3fs`, `gcsfs`, and every other
+async fsspec backend. The public, non-underscore names (`ls`, `cat_file`,
+...) are the *synchronous* wrappers fsspec generates from those coroutines.
+Pass `asynchronous=True` and `await` the coroutines:
+
+```python
+fs = DandiFileSystem("000026", asynchronous=True)
+entries = await fs._ls("rawdata")
+data = await fs._cat_file("rawdata/sub-I38/.../VFA.json")
+```
+
+The synchronous API is generated from these coroutines by fsspec and runs on
+fsspec's shared background event loop, so it also works inside a running loop
+(e.g. Jupyter).
+
+## Authentication
+
+Public dandisets need **no** authentication. For private or embargoed
+resources, a token is resolved **lazily** — only after a request returns
+`401` — in this order:
+
+1. an explicit `token=` argument to `DandiFileSystem`;
+2. the `DANDI_API_KEY` environment variable;
+3. a per-instance `<INSTANCE>_API_KEY` variable (e.g. `EMBER_API_KEY`);
+4. the system keyring (only if the optional `auth` extra is installed).
+
+```python
+fs = DandiFileSystem("000026", token="…")          # explicit
+# or: export DANDI_API_KEY=…   (recommended)
+```
+
+## Instances
+
+Registered instances: `dandi`, `dandi-staging`, `ember`, `ember-sandbox`, and
+`dandi-api-local-docker-tests`. You can also point at any DANDI-schema server:
+
+```python
+# by API URL
+DandiFileSystem("000001", instance="https://api.my-dandi.org/api")
+# by a bare server URL — discovered lazily via the server's /info/ endpoint
+DandiFileSystem("000001", instance="https://my-dandi.org")
+```
+
+## Licensing
+
+`dandifs` is released under the MIT License (see `LICENSE`). Portions of this
+project are derived from [dandi-cli](https://github.com/dandi/dandi-cli)
+(Apache-2.0); see the per-file `NOTICE` headers and `OTHER_LICENSES`.

dandifs-0.1.0/README.md

@@ -0,0 +1,132 @@
+# dandifs
+
+An [`fsspec`](https://filesystem-spec.readthedocs.io) filesystem for the
+[DANDI archive](https://dandiarchive.org).
+
+`dandifs` resolves `dandi://` URLs to the bytes behind DANDI assets, including
+files that live **inside a Zarr asset**. It is async-first (built on
+`aiohttp`, via fsspec's `AsyncFileSystem`), has a small dependency footprint,
+and does **not** depend on `dandi` or `dandi-schema`.
+
+## Install
+
+```bash
+pip install dandifs
+# optional: keyring-based credentials for private/embargoed dandisets
+pip install "dandifs[auth]"
+```
+
+## URL format
+
+```
+dandi://<instance>/<dandiset>[@<version>]/<path>
+```
+
+- `<instance>` — a registered instance name (`dandi`, `dandi-staging`,
+  `ember`, `ember-sandbox`, ...) or any DANDI-schema server (see *Instances*).
+- `<dandiset>` — the six-digit dandiset identifier, e.g. `000026`.
+- `@<version>` — optional; defaults to the most recent published version, or
+  the draft version if none is published.
+- `<path>` — a path within the dandiset. It may descend **into** a Zarr asset:
+  in `.../image.zarr/0/0/0`, only `.../image.zarr` is a registered asset and
+  `0/0/0` is a key inside that Zarr's store.
+
+## Public surface
+
+The **only** public API is the filesystem class, `DandiFileSystem`.
+Everything else is internal.
+
+## Usage
+
+### Via the registered protocol
+
+```python
+import fsspec, json
+
+with fsspec.open(
+    "dandi://dandi/000026/rawdata/sub-I38/ses-MRI/anat/"
+    "sub-I38_ses-MRI-echo-4_flip-4_VFA.json"
+) as f:
+    info = json.load(f)
+```
+
+### Bound to a dandiset
+
+```python
+from dandifs import DandiFileSystem
+
+fs = DandiFileSystem("000026")            # bind to a dandiset (+ version)
+fs.ls("rawdata")                          # browse
+fs.glob("**/anat/*.json")                 # glob assets
+with fs.open("rawdata/sub-I38/.../VFA.json") as f:
+    data = f.read()
+```
+
+### Files inside a Zarr asset
+
+```python
+fs = DandiFileSystem("000108")
+
+fs.ls("path/to/image.zarr")               # list entries inside the Zarr
+fs.info("path/to/image.zarr/0/0/0")       # stat a chunk
+with fs.open("path/to/image.zarr/0/0/0", "rb") as f:
+    chunk = f.read()                      # read chunk bytes
+```
+
+This also works transparently with libraries that open a store through fsspec,
+e.g. `zarr.open("dandi://dandi/<id>/path/to/image.zarr")`.
+
+### Async
+
+`DandiFileSystem` is a real async filesystem. Following fsspec's
+[`AsyncFileSystem`](https://filesystem-spec.readthedocs.io/en/latest/async.html)
+convention, the asynchronous API **is** the set of underscore-prefixed
+coroutine methods (`_ls`, `_info`, `_cat_file`, `_cat`, `_exists`, `_glob`,
+`_get`, ...) — the same pattern used by `s3fs`, `gcsfs`, and every other
+async fsspec backend. The public, non-underscore names (`ls`, `cat_file`,
+...) are the *synchronous* wrappers fsspec generates from those coroutines.
+Pass `asynchronous=True` and `await` the coroutines:
+
+```python
+fs = DandiFileSystem("000026", asynchronous=True)
+entries = await fs._ls("rawdata")
+data = await fs._cat_file("rawdata/sub-I38/.../VFA.json")
+```
+
+The synchronous API is generated from these coroutines by fsspec and runs on
+fsspec's shared background event loop, so it also works inside a running loop
+(e.g. Jupyter).
+
+## Authentication
+
+Public dandisets need **no** authentication. For private or embargoed
+resources, a token is resolved **lazily** — only after a request returns
+`401` — in this order:
+
+1. an explicit `token=` argument to `DandiFileSystem`;
+2. the `DANDI_API_KEY` environment variable;
+3. a per-instance `<INSTANCE>_API_KEY` variable (e.g. `EMBER_API_KEY`);
+4. the system keyring (only if the optional `auth` extra is installed).
+
+```python
+fs = DandiFileSystem("000026", token="…")          # explicit
+# or: export DANDI_API_KEY=…   (recommended)
+```
+
+## Instances
+
+Registered instances: `dandi`, `dandi-staging`, `ember`, `ember-sandbox`, and
+`dandi-api-local-docker-tests`. You can also point at any DANDI-schema server:
+
+```python
+# by API URL
+DandiFileSystem("000001", instance="https://api.my-dandi.org/api")
+# by a bare server URL — discovered lazily via the server's /info/ endpoint
+DandiFileSystem("000001", instance="https://my-dandi.org")
+```
+
+## Licensing
+
+`dandifs` is released under the MIT License (see `LICENSE`). Portions of this
+project are derived from [dandi-cli](https://github.com/dandi/dandi-cli)
+(Apache-2.0); see the per-file `NOTICE` headers and `OTHER_LICENSES`.

dandifs-0.1.0/dandifs/__init__.py

@@ -0,0 +1,14 @@
+"""
+dandifs: an fsspec filesystem for the DANDI archive.
+
+The only public surface is the filesystem class. Everything else
+(``_api``, ``_instance``, ``_parser``, ``_keyring``, ``_utils``, ``_consts``,
+``_exceptions``) is internal and may change without notice.
+"""
+
+from ._fs import DandiFileSystem
+from ._utils import get_logger, get_version
+
+__version__ = get_version()
+
+__all__ = ["DandiFileSystem", "get_logger"]

dandifs-0.1.0/dandifs/_api.py

@@ -0,0 +1,226 @@
+# NOTICE
+#   This file was inspired by [dandi-cli] dandi/dandiapi.py, which is
+#   distributed under the Apache 2.0 license, but has been rewritten to be
+#   async (aiohttp) and dependency-light.
+#   See: https://github.com/dandi/dandi-cli/blob/master/LICENSE
+"""
+Internal async REST client for DANDI API servers.
+
+The client is deliberately stateless with respect to the aiohttp session: the
+owning filesystem creates and manages the session (on the fsspec event loop)
+and passes it into every call. The client only holds the API base URL and the
+(lazily resolved) authentication token.
+"""
+
+import asyncio
+import json
+from typing import Any, AsyncIterator, Dict, Optional
+
+from ._consts import DRAFT, REQUEST_RETRIES, RETRY_STATUSES
+from ._exceptions import DandiHTTPError, FailedToConnectError, HTTP404Error
+from ._keyring import resolve_token
+from ._utils import USER_AGENT, clean_params, get_logger, joinurl
+
+LOG = get_logger("api")
+
+
+def _decode(body: bytes) -> str:
+    return body.decode("utf-8", "replace")
+
+
+class DandiClient:
+    """An async client for a single DANDI API server."""
+
+    def __init__(
+        self,
+        api_url: str,
+        instance_name: Optional[str] = None,
+        token: Optional[str] = None,
+        use_keyring: bool = True,
+    ) -> None:
+        self.api_url = api_url.rstrip("/")
+        self.instance_name = instance_name
+        self._token = token
+        self._auth_tried = False
+        self.use_keyring = use_keyring
+
+    # -- low-level -----------------------------------------------------
+
+    def _headers(self) -> Dict[str, str]:
+        headers = {"Accept": "application/json", "User-Agent": USER_AGENT}
+        if self._token:
+            headers["Authorization"] = "token {}".format(self._token)
+        return headers
+
+    async def request(
+        self,
+        session: Any,
+        method: str,
+        path: str,
+        params: Optional[dict] = None,
+        json_resp: bool = True,
+    ) -> Any:
+        """
+        Perform an HTTP request, retrying transient failures and resolving
+        authentication lazily (only after a 401).
+        """
+        url = joinurl(self.api_url, path)
+        qparams = clean_params(params)
+        for attempt in range(REQUEST_RETRIES):
+            LOG.debug("%s %s", method.upper(), url)
+            async with session.request(
+                method, url, params=qparams, headers=self._headers()
+            ) as resp:
+                status = resp.status
+                if status == 401 and not self._auth_tried:
+                    self._auth_tried = True
+                    token = resolve_token(
+                        self.instance_name, use_keyring=self.use_keyring
+                    )
+                    if token and token != self._token:
+                        LOG.debug("Retrying %s with resolved token", url)
+                        self._token = token
+                        continue
+                if status in RETRY_STATUSES:
+                    delay = min(0.5 * (2**attempt), 10.0)
+                    LOG.debug("Status %d for %s; retrying in %.1fs", status, url, delay)
+                    await asyncio.sleep(delay)
+                    continue
+                body = await resp.read()
+                if status == 404:
+                    raise HTTP404Error(url, _decode(body))
+                if status >= 400:
+                    raise DandiHTTPError(status, url, _decode(body))
+                if not json_resp:
+                    return body
+                text = _decode(body).strip()
+                return json.loads(text) if text else None
+        raise FailedToConnectError(
+            "Request to {} failed after {} attempts".format(url, REQUEST_RETRIES)
+        )
+
+    async def get(
+        self, session: Any, path: str, params: Optional[dict] = None, **kw: Any
+    ) -> Any:
+        """Convenience GET wrapper around :meth:`request`."""
+        return await self.request(session, "GET", path, params=params, **kw)
+
+    async def paginate(
+        self, session: Any, path: str, params: Optional[dict] = None
+    ) -> AsyncIterator[dict]:
+        """Yield items across all pages of a paginated endpoint."""
+        page = await self.get(session, path, params=params)
+        while page is not None:
+            for item in page.get("results", []):
+                yield item
+            nxt = page.get("next")
+            if not nxt:
+                break
+            page = await self.get(session, nxt)
+
+    # -- DANDI endpoints ----------------------------------------------
+
+    @staticmethod
+    def _version_path(dandiset_id: str, version_id: str) -> str:
+        return "/dandisets/{}/versions/{}".format(dandiset_id, version_id)
+
+    async def get_dandiset(self, session: Any, dandiset_id: str) -> dict:
+        """Return the dandiset record."""
+        return await self.get(session, "/dandisets/{}/".format(dandiset_id))
+
+    async def resolve_version(
+        self, session: Any, dandiset_id: str, version_id: Optional[str]
+    ) -> str:
+        """Return ``version_id`` or the dandiset's default (published/draft)."""
+        if version_id:
+            return version_id
+        record = await self.get_dandiset(session, dandiset_id)
+        published = record.get("most_recent_published_version")
+        if published:
+            return published["version"]
+        draft = record.get("draft_version")
+        if draft:
+            return draft["version"]
+        return DRAFT
+
+    async def assets(
+        self,
+        session: Any,
+        dandiset_id: str,
+        version_id: str,
+        path: Optional[str] = None,
+        glob: Optional[str] = None,
+        order: Optional[str] = None,
+        metadata: bool = False,
+    ) -> AsyncIterator[dict]:
+        """Iterate over assets, optionally filtered by path prefix or glob."""
+        params: Dict[str, Any] = {}
+        if path is not None:
+            params["path"] = path
+        if glob is not None:
+            params["glob"] = glob
+        if order is not None:
+            params["order"] = order
+        if metadata:
+            params["metadata"] = True
+        endpoint = self._version_path(dandiset_id, version_id) + "/assets/"
+        async for asset in self.paginate(session, endpoint, params):
+            yield asset
+
+    async def asset_with_path(
+        self,
+        session: Any,
+        dandiset_id: str,
+        version_id: str,
+        path: str,
+        metadata: bool = True,
+    ) -> Optional[dict]:
+        """Return the asset whose path equals ``path`` exactly, or ``None``."""
+        async for asset in self.assets(
+            session, dandiset_id, version_id, path=path, metadata=metadata
+        ):
+            if asset.get("path") == path:
+                return asset
+        return None
+
+    async def asset_paths(
+        self,
+        session: Any,
+        dandiset_id: str,
+        version_id: str,
+        path_prefix: Optional[str] = None,
+    ) -> AsyncIterator[dict]:
+        """Iterate over the immediate children (folders/files) of a prefix."""
+        params: Dict[str, Any] = {}
+        if path_prefix is not None:
+            params["path_prefix"] = path_prefix
+        endpoint = self._version_path(dandiset_id, version_id) + "/assets/paths/"
+        async for entry in self.paginate(session, endpoint, params):
+            yield entry
+
+    async def get_asset(
+        self,
+        session: Any,
+        dandiset_id: str,
+        version_id: str,
+        asset_id: str,
+        info: bool = False,
+    ) -> dict:
+        """Return an asset record (or its ``/info/`` metadata)."""
+        suffix = "/info/" if info else "/"
+        endpoint = self._version_path(dandiset_id, version_id) + (
+            "/assets/{}{}".format(asset_id, suffix)
+        )
+        return await self.get(session, endpoint)
+
+    async def zarr_files(
+        self, session: Any, zarr_id: str, prefix: Optional[str] = None
+    ) -> AsyncIterator[dict]:
+        """Iterate over entries in a Zarr archive's file listing."""
+        params: Dict[str, Any] = {}
+        if prefix is not None:
+            params["prefix"] = prefix
+        async for entry in self.paginate(
+            session, "/zarr/{}/files/".format(zarr_id), params
+        ):
+            yield entry

dandifs-0.1.0/dandifs/_consts.py

@@ -0,0 +1,26 @@
+# NOTICE
+#   Some values in this file were copied and modified from [dandi-cli]
+#   dandi/consts.py, which is distributed under the Apache 2.0 license.
+#   See: https://github.com/dandi/dandi-cli/blob/master/LICENSE
+"""Internal constants for :mod:`dandifs`."""
+
+#: Regular expression for a valid Dandiset identifier. Not anchored.
+DANDISET_ID_REGEX = r"[0-9]{6}"
+
+#: Regular expression for a valid published (non-draft) Dandiset version.
+PUBLISHED_VERSION_REGEX = r"[0-9]+\.[0-9]+\.[0-9]+"
+
+#: Regular expression for any valid Dandiset version identifier.
+VERSION_REGEX = r"(?:[0-9]+\.[0-9]+\.[0-9]+|draft)"
+
+#: The identifier used for draft Dandiset versions.
+DRAFT = "draft"
+
+#: HTTP response status codes that should be retried until retries run out.
+RETRY_STATUSES = (429, 500, 502, 503, 504)
+
+#: Number of attempts made for a single request before giving up.
+REQUEST_RETRIES = 6
+
+#: File extensions used to identify Zarr assets.
+ZARR_EXTENSIONS = (".zarr", ".ngff")

dandifs-0.1.0/dandifs/_exceptions.py

@@ -0,0 +1,45 @@
+# NOTICE
+#   Some names in this file were copied and modified from [dandi-cli]
+#   dandi/exceptions.py, which is distributed under the Apache 2.0 license.
+#   See: https://github.com/dandi/dandi-cli/blob/master/LICENSE
+"""Internal exceptions for :mod:`dandifs`."""
+
+from typing import Optional
+
+
+class UnknownURLError(ValueError):
+    """The given URL does not correspond to a known DANDI resource."""
+
+
+class NotFoundError(RuntimeError):
+    """An online resource we tried to reach was not found."""
+
+
+class FailedToConnectError(RuntimeError):
+    """Failed to connect to an online resource."""
+
+
+class DandiHTTPError(RuntimeError):
+    """An HTTP request to a DANDI API returned an error status."""
+
+    def __init__(
+        self,
+        status: int,
+        url: str,
+        message: Optional[str] = None,
+    ) -> None:
+        self.status = status
+        self.url = url
+        self.message = message or ""
+        super().__init__(
+            "HTTP {} for {}{}".format(
+                status, url, ": " + self.message if self.message else ""
+            )
+        )
+
+
+class HTTP404Error(DandiHTTPError):
+    """An HTTP request returned a 404 (Not Found) status."""
+
+    def __init__(self, url: str, message: Optional[str] = None) -> None:
+        super().__init__(404, url, message)