Define ChunkNotFoundError; expose chunk key and chunk index in ChunkNotFoundError

Author: d-v-b

src/zarr/abc/codec.py

@@ -430,7 +430,9 @@ async def encode(
     @abstractmethod
     async def read(
         self,
-        batch_info: Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool]],
+        batch_info: Iterable[
+            tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool, str, tuple[int, ...]]
+        ],
         out: NDBuffer,
         drop_axes: tuple[int, ...] = (),
     ) -> None:
@@ -439,12 +441,14 @@ async def read(
 
         Parameters
         ----------
-        batch_info : Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple]]
+        batch_info : Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool, str, tuple[int, ...]]]
             Ordered set of information about the chunks.
             The first slice selection determines which parts of the chunk will be fetched.
             The second slice selection determines where in the output array the chunk data will be written.
             The ByteGetter is used to fetch the necessary bytes.
             The chunk spec contains information about the construction of an array from the bytes.
+            The string is the chunk key.
+            The tuple of ints is the chunk's grid coordinates.
 
             If the Store returns ``None`` for a chunk, then the chunk was not
             written and the implementation must set the values of that chunk (or

src/zarr/codecs/sharding.py

@@ -439,6 +439,8 @@ async def _decode_single(
                     chunk_selection,
                     out_selection,
                     is_complete_shard,
+                    "/".join(str(c) for c in chunk_coords),
+                    chunk_coords,
                 )
                 for chunk_coords, chunk_selection, out_selection, is_complete_shard in indexer
             ],
@@ -511,6 +513,8 @@ async def _decode_partial_single(
                     chunk_selection,
                     out_selection,
                     is_complete_shard,
+                    "/".join(str(c) for c in chunk_coords),
+                    chunk_coords,
                 )
                 for chunk_coords, chunk_selection, out_selection, is_complete_shard in indexer
             ],

src/zarr/core/array.py

@@ -5608,6 +5608,8 @@ async def _get_selection(
                     chunk_selection,
                     out_selection,
                     is_complete_chunk,
+                    metadata.encode_chunk_key(chunk_coords),
+                    chunk_coords,
                 )
                 for chunk_coords, chunk_selection, out_selection, is_complete_chunk in indexer
             ],

src/zarr/core/codec_pipeline.py

@@ -17,7 +17,7 @@
 from zarr.core.common import concurrent_map
 from zarr.core.config import config
 from zarr.core.indexing import SelectorTuple, is_scalar
-from zarr.errors import MissingChunkError, ZarrUserWarning
+from zarr.errors import ChunkNotFoundError, ZarrUserWarning
 from zarr.registry import register_pipeline
 
 if TYPE_CHECKING:
@@ -248,7 +248,9 @@ async def encode_partial_batch(
 
     async def read_batch(
         self,
-        batch_info: Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool]],
+        batch_info: Iterable[
+            tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool, str, tuple[int, ...]]
+        ],
         out: NDBuffer,
         drop_axes: tuple[int, ...] = (),
     ) -> None:
@@ -259,15 +261,17 @@ async def read_batch(
                     for byte_getter, chunk_spec, chunk_selection, *_ in batch_info
                 ]
             )
-            for chunk_array, (_, chunk_spec, _, out_selection, _) in zip(
+            for chunk_array, (_, chunk_spec, _, out_selection, _, chunk_key, chunk_coords) in zip(
                 chunk_array_batch, batch_info, strict=False
             ):
                 if chunk_array is not None:
                     out[out_selection] = chunk_array
                 elif chunk_spec.config.fill_missing_chunks:
                     out[out_selection] = fill_value_or_default(chunk_spec)
                 else:
-                    raise MissingChunkError
+                    raise ChunkNotFoundError(
+                        f"chunk '{chunk_key}' at grid position {chunk_coords} not found in store."
+                    )
         else:
             chunk_bytes_batch = await concurrent_map(
                 [(byte_getter, array_spec.prototype) for byte_getter, array_spec, *_ in batch_info],
@@ -282,9 +286,15 @@ async def read_batch(
                     )
                 ],
             )
-            for chunk_array, (_, chunk_spec, chunk_selection, out_selection, _) in zip(
-                chunk_array_batch, batch_info, strict=False
-            ):
+            for chunk_array, (
+                _,
+                chunk_spec,
+                chunk_selection,
+                out_selection,
+                _,
+                chunk_key,
+                chunk_coords,
+            ) in zip(chunk_array_batch, batch_info, strict=False):
                 if chunk_array is not None:
                     tmp = chunk_array[chunk_selection]
                     if drop_axes != ():
@@ -293,7 +303,9 @@ async def read_batch(
                 elif chunk_spec.config.fill_missing_chunks:
                     out[out_selection] = fill_value_or_default(chunk_spec)
                 else:
-                    raise MissingChunkError
+                    raise ChunkNotFoundError(
+                        f"chunk '{chunk_key}' at grid position {chunk_coords} not found in store"
+                    )
 
     def _merge_chunk_array(
         self,
@@ -470,7 +482,9 @@ async def encode(
 
     async def read(
         self,
-        batch_info: Iterable[tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool]],
+        batch_info: Iterable[
+            tuple[ByteGetter, ArraySpec, SelectorTuple, SelectorTuple, bool, str, tuple[int, ...]]
+        ],
         out: NDBuffer,
         drop_axes: tuple[int, ...] = (),
     ) -> None:

src/zarr/errors.py

@@ -146,4 +146,7 @@ class BoundsCheckError(IndexError): ...
 class ArrayIndexError(IndexError): ...
 
 
-class MissingChunkError(IndexError): ...
+class ChunkNotFoundError(BaseZarrError):
+    """
+    Raised when a chunk that was expected to exist in storage was not retrieved successfully.
+    """

tests/test_config.py

@@ -23,7 +23,7 @@
 from zarr.core.codec_pipeline import BatchedCodecPipeline
 from zarr.core.config import BadConfigError, config
 from zarr.core.indexing import SelectorTuple
-from zarr.errors import MissingChunkError, ZarrUserWarning
+from zarr.errors import ChunkNotFoundError, ZarrUserWarning
 from zarr.registry import (
     fully_qualified_name,
     get_buffer_class,
@@ -345,7 +345,7 @@ def test_config_fill_missing_chunks(store: Store, kwargs: dict[str, Any]) -> Non
 
     # with fill_missing_chunks=False, reading missing chunks raises an error
     with config.set({"array.fill_missing_chunks": False}):
-        with pytest.raises(MissingChunkError):
+        with pytest.raises(ChunkNotFoundError):
             zarr.open_array(store)[:]
 
     # after writing data, all chunks exist and no error is raised
@@ -381,7 +381,7 @@ def test_config_fill_missing_chunks_sharded_inner(store: Store) -> None:
         assert np.array_equal(result, expected)
 
         # second shard is entirely missing: raises an error
-        with pytest.raises(MissingChunkError):
+        with pytest.raises(ChunkNotFoundError):
             a[4:]
 
 
@@ -404,7 +404,7 @@ def test_config_fill_missing_chunks_write_empty_chunks(store: Store) -> None:
 
     # overwrite with fill_value: chunks are dropped by write_empty_chunks=False
     arr[:] = 0
-    with pytest.raises(MissingChunkError):
+    with pytest.raises(ChunkNotFoundError):
         arr[:]
 
     # with write_empty_chunks=True, chunks are kept and no error is raised