Merge branch 'master' into enh-lad-framework

Author: CodyCBakerPhD

CHANGELOG.md

@@ -1,3 +1,23 @@
+# 0.74.3 (Sat Feb 14 2026)
+
+#### 🐛 Bug Fix
+
+- bf: pass aiohttp timeouts to fsspec to fix test hang [#1795](https://github.com/dandi/dandi-cli/pull/1795) ([@yarikoptic](https://github.com/yarikoptic))
+- Enhance dandiset metadata error messages [#1790](https://github.com/dandi/dandi-cli/pull/1790) ([@yarikoptic](https://github.com/yarikoptic) [@yarikoptic-gitmate](https://github.com/yarikoptic-gitmate))
+- Fix type annotation in upload sync path prefix calculation [#1794](https://github.com/dandi/dandi-cli/pull/1794) ([@yarikoptic](https://github.com/yarikoptic) [@yarikoptic-gitmate](https://github.com/yarikoptic-gitmate))
+- Fix macOS-15-intel CI failures: h5py and opencv-python regressions [#1783](https://github.com/dandi/dandi-cli/pull/1783) ([@yarikoptic](https://github.com/yarikoptic))
+
+#### 📝 Documentation
+
+- Add module docstrings to validation and NWB utilities [#1789](https://github.com/dandi/dandi-cli/pull/1789) ([@yarikoptic](https://github.com/yarikoptic) [@yarikoptic-gitmate](https://github.com/yarikoptic-gitmate))
+
+#### Authors: 2
+
+- GitMate for @yarikoptic ([@yarikoptic-gitmate](https://github.com/yarikoptic-gitmate))
+- Yaroslav Halchenko ([@yarikoptic](https://github.com/yarikoptic))
+
+---
+
 # 0.74.2 (Fri Jan 30 2026)
 
 #### 🐛 Bug Fix

dandi/consts.py

@@ -1,3 +1,12 @@
+"""Constants and configuration for DANDI CLI.
+
+This module defines constants used throughout the DANDI CLI including:
+- Metadata field definitions for NWB files
+- Known DANDI Archive instances and their configurations
+- File organization patterns and BIDS-related constants
+- Request timeouts and retry settings
+"""
+
 from __future__ import annotations
 
 from collections.abc import Iterator

dandi/dandiapi.py

@@ -1,3 +1,15 @@
+"""REST API client for interacting with DANDI Archive instances.
+
+This module provides client classes for communicating with DANDI Archive API
+servers, including asset management, dandiset operations, and authentication.
+
+The main classes are:
+- DandiAPIClient: High-level client for DANDI API operations
+- RESTFullAPIClient: Base HTTP client with retry and authentication
+- RemoteDandiset: Represents a dandiset on the server
+- RemoteAsset: Represents an asset (file) on the server
+"""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -435,7 +447,11 @@ def __init__(
                 dandi_instance = get_instance(instance_name)
             api_url = dandi_instance.api
         elif dandi_instance is not None:
-            raise ValueError("api_url and dandi_instance are mutually exclusive")
+            raise ValueError(
+                "api_url and dandi_instance are mutually exclusive. "
+                "Use either 'api_url' to specify a custom API URL, "
+                "or 'dandi_instance' to use a registered DANDI instance, but not both."
+            )
         else:
             dandi_instance = get_instance(api_url)
         super().__init__(api_url)
@@ -562,7 +578,10 @@ def get_dandiset(
                     self, self.get(f"/dandisets/{dandiset_id}/")
                 )
             except HTTP404Error:
-                raise NotFoundError(f"No such Dandiset: {dandiset_id!r}")
+                raise NotFoundError(
+                    f"No such Dandiset: {dandiset_id!r}. "
+                    "Verify the Dandiset ID is correct and that you have access. "
+                )
             if version_id is not None and version_id != d.version_id:
                 if version_id == DRAFT:
                     return d.for_version(d.draft_version)
@@ -732,7 +751,11 @@ def get_asset(self, asset_id: str) -> BaseRemoteAsset:
         try:
             info = self.get(f"/assets/{asset_id}/info/")
         except HTTP404Error:
-            raise NotFoundError(f"No such asset: {asset_id!r}")
+            raise NotFoundError(
+                f"No such asset: {asset_id!r}. "
+                "Verify the asset ID is correct. "
+                "Use 'dandi ls' to list available assets."
+            )
         metadata = info.pop("metadata", None)
         return BaseRemoteAsset.from_base_data(self, info, metadata)
 
@@ -1306,7 +1329,11 @@ def get_asset_by_path(self, path: str) -> RemoteAsset:
                 a for a in self.get_assets_with_path_prefix(path) if a.path == path
             )
         except ValueError:
-            raise NotFoundError(f"No asset at path {path!r}")
+            raise NotFoundError(
+                f"No asset at path {path!r} in version {self.version_id}. "
+                "Verify the path is correct and the asset exists in this version. "
+                "Use 'dandi ls' to list available assets."
+            )
         else:
             return asset
 

dandi/dandiset.py

@@ -42,7 +42,11 @@ def __init__(
         if not allow_empty and not os.path.lexists(
             self.path_obj / dandiset_metadata_file
         ):
-            raise ValueError(f"No dandiset at {path}")
+            raise ValueError(
+                f"No dandiset at {path}. "
+                f"The directory does not contain a '{dandiset_metadata_file}' file. "
+                "Use 'dandi download' to download a dandiset or check the path."
+            )
         self.metadata: dict | None = None
         self._metadata_file_obj = self.path_obj / dandiset_metadata_file
         self._load_metadata()
@@ -139,11 +143,17 @@ def _get_identifier(metadata: dict) -> str | None:
     @property
     def identifier(self) -> str:
         if self.metadata is None:
-            raise ValueError("No metadata record found in Dandiset")
+            raise ValueError(
+                f"No metadata record found in Dandiset at {self.path}. "
+                f"The '{dandiset_metadata_file}' file may be empty or corrupted. "
+                "Use 'dandi download' to re-download the dandiset metadata."
+            )
         id_ = self._get_identifier(self.metadata)
         if not id_:
             raise ValueError(
-                f"Found no dandiset.identifier in metadata record: {self.metadata}"
+                f"Found no dandiset.identifier in metadata record. "
+                f"The '{dandiset_metadata_file}' file must contain an 'identifier' field. "
+                f"Metadata: {self.metadata}"
             )
         return id_
 

dandi/delete.py

@@ -1,3 +1,13 @@
+"""Delete assets and dandisets from DANDI Archive.
+
+This module provides functionality for deleting assets and entire dandisets
+from DANDI Archive instances. It supports:
+- Single and batch asset deletion
+- Dandiset deletion with confirmation
+- URL-based and path-based deletion
+- Skip-missing option for non-existent resources
+"""
+
 from __future__ import annotations
 
 from collections.abc import Iterable, Iterator

dandi/download.py

@@ -1,3 +1,13 @@
+"""Download assets from DANDI Archive.
+
+This module provides functionality for downloading files and Zarr archives
+from DANDI Archive instances. It supports:
+- Individual file downloads with integrity verification
+- Zarr archive downloads with parallel entry handling
+- Resume capability for interrupted downloads
+- Progress tracking and error recovery
+"""
+
 from __future__ import annotations
 
 from collections import Counter, deque

dandi/exceptions.py

@@ -1,3 +1,10 @@
+"""Custom exceptions for DANDI CLI operations.
+
+This module defines exception classes used throughout the DANDI CLI for
+handling various error conditions including network errors, validation
+failures, and version incompatibilities.
+"""
+
 from __future__ import annotations
 
 import requests

dandi/misctypes.py

@@ -345,10 +345,27 @@ def open(self) -> IO[bytes]:
         # Optional dependency:
         import fsspec
 
+        from aiohttp import ClientTimeout
+
         # We need to call open() on the return value of fsspec.open() because
         # otherwise the filehandle will only be opened when used to enter a
         # context manager.
-        return cast(IO[bytes], fsspec.open(self.url, mode="rb").open())
+        #
+        # Pass explicit timeouts to aiohttp to prevent indefinite hangs in
+        # fsspec's sync() wrapper.  Without these, a stalled connection to S3
+        # (or minio in tests) causes fsspec's background IO thread to block
+        # forever, which in turn blocks the calling thread in
+        # threading.Event.wait() — see https://github.com/fsspec/filesystem_spec/issues/1666
+        return cast(
+            IO[bytes],
+            fsspec.open(
+                self.url,
+                mode="rb",
+                client_kwargs={
+                    "timeout": ClientTimeout(total=120, sock_read=60, sock_connect=30)
+                },
+            ).open(),
+        )
 
     def get_size(self) -> int:
         return self.size

dandi/move.py

@@ -1,3 +1,14 @@
+"""Move and rename assets in DANDI Archive.
+
+This module provides functionality for moving and renaming assets both
+locally and remotely in DANDI Archive instances. Features include:
+- Local file reorganization
+- Remote asset path changes
+- Combined local and remote moves
+- Conflict resolution (skip, overwrite, error)
+- Validation of move operations
+"""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
@@ -13,7 +24,7 @@
 from typing import NewType
 
 from . import get_logger
-from .consts import DandiInstance
+from .consts import DandiInstance, dandiset_metadata_file
 from .dandiapi import DandiAPIClient, RemoteAsset, RemoteDandiset
 from .dandiarchive import DandisetURL, parse_dandi_url
 from .dandiset import Dandiset
@@ -233,7 +244,11 @@ def resolve(self, path: str) -> tuple[AssetPath, bool]:
             posixpath.normpath(posixpath.join(self.subpath.as_posix(), path))
         )
         if p.parts and p.parts[0] == os.pardir:
-            raise ValueError(f"{path!r} is outside of Dandiset")
+            raise ValueError(
+                f"{path!r} is outside of Dandiset. "
+                "Paths cannot use '..' to navigate above the Dandiset root. "
+                "All assets must remain within the Dandiset directory structure."
+            )
         return (AssetPath(str(p)), path.endswith("/"))
 
     def calculate_moves(
@@ -472,11 +487,17 @@ def get_path(self, path: str, is_src: bool = True) -> File | Folder:
         rpath, needs_dir = self.resolve(path)
         p = self.dandiset_path / rpath
         if not os.path.lexists(p):
-            raise NotFoundError(f"No asset at local path {path!r}")
+            raise NotFoundError(
+                f"No asset at local path {path!r}. "
+                "Verify the path is correct and the file exists locally."
+            )
         if p.is_dir():
             if is_src:
                 if p == self.dandiset_path / self.subpath:
-                    raise ValueError("Cannot move current working directory")
+                    raise ValueError(
+                        "Cannot move current working directory. "
+                        "Change to a different directory before moving this location."
+                    )
                 files = [
                     df.filepath.relative_to(p).as_posix()
                     for df in find_dandi_files(
@@ -488,7 +509,10 @@ def get_path(self, path: str, is_src: bool = True) -> File | Folder:
                 files = []
             return Folder(rpath, files)
         elif needs_dir:
-            raise ValueError(f"Local path {path!r} is a file")
+            raise ValueError(
+                f"Local path {path!r} is a file but a directory was expected. "
+                "Use a path ending with '/' for directories."
+            )
         else:
             return File(rpath)
 
@@ -612,7 +636,10 @@ def get_path(self, path: str, is_src: bool = True) -> File | Folder:
         file_found = False
         if rpath == self.subpath.as_posix():
             if is_src:
-                raise ValueError("Cannot move current working directory")
+                raise ValueError(
+                    "Cannot move current working directory. "
+                    "Change to a different directory before moving this location."
+                )
             else:
                 return Folder(rpath, [])
         for p in self.assets.keys():
@@ -629,7 +656,10 @@ def get_path(self, path: str, is_src: bool = True) -> File | Folder:
         if relcontents:
             return Folder(rpath, relcontents)
         if needs_dir and file_found:
-            raise ValueError(f"Remote path {path!r} is a file")
+            raise ValueError(
+                f"Remote path {path!r} is a file but a directory was expected. "
+                "Use a path ending with '/' for directories."
+            )
         elif (
             not needs_dir
             and not is_src
@@ -641,7 +671,11 @@ def get_path(self, path: str, is_src: bool = True) -> File | Folder:
             # remote directory.
             return Folder(rpath, [])
         else:
-            raise NotFoundError(f"No asset at remote path {path!r}")
+            raise NotFoundError(
+                f"No asset at remote path {path!r}. "
+                "Verify the path is correct and the asset exists on the server. "
+                "Use 'dandi ls' to list available assets."
+            )
 
     def is_dir(self, path: AssetPath) -> bool:
         """Returns true if the given path points to a directory"""
@@ -891,7 +925,11 @@ def find_dandiset_and_subpath(path: Path) -> tuple[Dandiset, Path]:
     path = path.absolute()
     ds = Dandiset.find(path)
     if ds is None:
-        raise ValueError(f"{path}: not a Dandiset")
+        raise ValueError(
+            f"{path}: not a Dandiset. "
+            f"The directory does not contain a '{dandiset_metadata_file}' file. "
+            "Use 'dandi download' to download a dandiset first."
+        )
     return (ds, path.relative_to(ds.path))
 
 

dandi/organize.py

@@ -1,5 +1,12 @@
-"""
-ATM primarily a sandbox for some functionality for dandi organize
+"""Organize and structure NWB files according to DANDI conventions.
+
+This module provides functionality for organizing neuroscience data files
+according to DANDI's file organization schema. Features include:
+- Automatic path generation from metadata
+- BIDS-like subject/session organization
+- Metadata-driven file naming
+- Validation of organized paths
+- Support for videos and generic files
 """
 
 from __future__ import annotations