friendlier error messages for missing chunk managers

doc/whats-new.rst

@@ -21,6 +21,8 @@ v.2024.11.1 (unreleased)
 
 New Features
 ~~~~~~~~~~~~
+- Improve the error message raised when using chunked-array methods if no chunk manager is available or if the requested chunk manager is missing (:pull:`9676`)
+  By `Justus Magin <https://github.com/keewis>`_.
 
 
 Breaking changes

xarray/backends/zarr.py

@@ -1415,7 +1415,7 @@ def open_zarr(
             )  # attempt to import that parallel backend
 
             chunks = {}
-        except ValueError:
+        except (ValueError, ImportError):
             chunks = None
 
     if kwargs:

xarray/namedarray/parallelcompat.py

@@ -46,6 +46,12 @@ def compute(
 
 T_ChunkedArray = TypeVar("T_ChunkedArray", bound=ChunkedArrayMixinProtocol)
 
+known_chunkmanagers = {
+    "dask": "dask",
+    "cubed": "cubed-xarray",
+    "arkouda": "arkouda-xarray",
+}
+
 
 @functools.lru_cache(maxsize=1)
 def list_chunkmanagers() -> dict[str, ChunkManagerEntrypoint[Any]]:
@@ -106,7 +112,16 @@ def guess_chunkmanager(
             manager = OPTIONS["chunk_manager"]
 
     if isinstance(manager, str):
-        if manager not in chunkmanagers:
+        if manager not in chunkmanagers and manager in known_chunkmanagers:
+            raise ImportError(
+                f"chunk manager {manager!r} is not available."
+                f" Please make sure {known_chunkmanagers[manager]} is installed and importable."
+            )
+        elif len(chunkmanagers) == 0:
+            raise ImportError(
+                "no chunk managers available. Try installing `dask` or another package that provides a chunk manager."
+            )
+        elif manager not in chunkmanagers:
             raise ValueError(
                 f"unrecognized chunk manager {manager} - must be one of: {list(chunkmanagers)}"
             )

xarray/tests/test_parallelcompat.py

@@ -14,10 +14,11 @@
     ChunkManagerEntrypoint,
     get_chunked_array_type,
     guess_chunkmanager,
+    known_chunkmanagers,
     list_chunkmanagers,
     load_chunkmanagers,
 )
-from xarray.tests import has_dask, requires_dask
+from xarray.tests import requires_dask
 
 
 class DummyChunkedArray(np.ndarray):
@@ -158,7 +159,18 @@ def test_get_chunkmanger_via_set_options(self, register_dummy_chunkmanager) -> N
             chunkmanager = guess_chunkmanager(None)
             assert isinstance(chunkmanager, DummyChunkManager)
 
-    def test_fail_on_nonexistent_chunkmanager(self) -> None:
+    def test_fail_on_known_but_missing_chunkmanager(
+        self, register_dummy_chunkmanager, monkeypatch
+    ) -> None:
+        monkeypatch.setitem(known_chunkmanagers, "test", "test-package")
+        with pytest.raises(
+            ImportError, match="chunk manager 'test' is not available.+test-package"
+        ):
+            guess_chunkmanager("test")
+
+    def test_fail_on_nonexistent_chunkmanager(
+        self, register_dummy_chunkmanager
+    ) -> None:
         with pytest.raises(ValueError, match="unrecognized chunk manager foo"):
             guess_chunkmanager("foo")
 
@@ -167,9 +179,16 @@ def test_get_dask_if_installed(self) -> None:
         chunkmanager = guess_chunkmanager(None)
         assert isinstance(chunkmanager, DaskManager)
 
-    @pytest.mark.skipif(has_dask, reason="requires dask not to be installed")
-    def test_dont_get_dask_if_not_installed(self) -> None:
-        with pytest.raises(ValueError, match="unrecognized chunk manager dask"):
+    def test_no_chunk_manager_available(self, monkeypatch) -> None:
+        monkeypatch.setattr("xarray.namedarray.parallelcompat.list_chunkmanagers", dict)
+        with pytest.raises(ImportError, match="no chunk managers available"):
+            guess_chunkmanager("foo")
+
+    def test_no_chunk_manager_available_but_known_manager_requested(
+        self, monkeypatch
+    ) -> None:
+        monkeypatch.setattr("xarray.namedarray.parallelcompat.list_chunkmanagers", dict)
+        with pytest.raises(ImportError, match="chunk manager 'dask' is not available"):
             guess_chunkmanager("dask")
 
     @requires_dask