Return scalar when accessing zero dimensional array

changes/2718.bugfix.rst

@@ -0,0 +1,3 @@
+0-dimensional arrays are now returning a scalar. Therefore, the return type of ``__getitem__`` changed
+to NDArrayLikeOrScalar. This change is to make the behavior of 0-dimensional arrays consistent with
+``numpy`` scalars.

src/zarr/api/asynchronous.py

@@ -33,6 +33,7 @@
     from collections.abc import Iterable
 
     from zarr.abc.codec import Codec
+    from zarr.core.buffer import NDArrayLikeOrScalar
     from zarr.core.chunk_key_encodings import ChunkKeyEncoding
     from zarr.storage import StoreLike
 
@@ -232,7 +233,7 @@ async def load(
     path: str | None = None,
     zarr_format: ZarrFormat | None = None,
     zarr_version: ZarrFormat | None = None,
-) -> NDArrayLike | dict[str, NDArrayLike]:
+) -> NDArrayLikeOrScalar | dict[str, NDArrayLikeOrScalar]:
     """Load data from an array or group into memory.
 
     Parameters

src/zarr/api/synchronous.py

@@ -26,7 +26,7 @@
         ShardsLike,
     )
     from zarr.core.array_spec import ArrayConfigLike
-    from zarr.core.buffer import NDArrayLike
+    from zarr.core.buffer import NDArrayLike, NDArrayLikeOrScalar
     from zarr.core.chunk_key_encodings import ChunkKeyEncoding, ChunkKeyEncodingLike
     from zarr.core.common import (
         JSON,
@@ -119,7 +119,7 @@ def load(
     path: str | None = None,
     zarr_format: ZarrFormat | None = None,
     zarr_version: ZarrFormat | None = None,
-) -> NDArrayLike | dict[str, NDArrayLike]:
+) -> NDArrayLikeOrScalar | dict[str, NDArrayLikeOrScalar]:
     """Load data from an array or group into memory.
 
     Parameters

src/zarr/core/array.py

@@ -35,6 +35,7 @@
 from zarr.core.buffer import (
     BufferPrototype,
     NDArrayLike,
+    NDArrayLikeOrScalar,
     NDBuffer,
     default_buffer_prototype,
 )
@@ -1256,7 +1257,7 @@
         prototype: BufferPrototype,
         out: NDBuffer | None = None,
         fields: Fields | None = None,
-    ) -> NDArrayLike:
+    ) -> NDArrayLikeOrScalar:
         # check fields are sensible
         out_dtype = check_fields(fields, self.dtype)
 
@@ -1298,14 +1299,16 @@
                 out_buffer,
                 drop_axes=indexer.drop_axes,
             )
+        if isinstance(indexer, BasicIndexer) and indexer.shape == ():
+            return out_buffer.as_scalar()
         return out_buffer.as_ndarray_like()
 
     async def getitem(
         self,
         selection: BasicSelection,
         *,
         prototype: BufferPrototype | None = None,
-    ) -> NDArrayLike:
+    ) -> NDArrayLikeOrScalar:
         """
         Asynchronous function that retrieves a subset of the array's data based on the provided selection.
 
@@ -1318,7 +1321,7 @@
 
         Returns
         -------
-        NDArrayLike
+        NDArrayLikeOrScalar
             The retrieved subset of the array's data.
 
         Examples
@@ -2270,14 +2273,15 @@
             msg = "`copy=False` is not supported. This method always creates a copy."
             raise ValueError(msg)
 
-        arr_np = self[...]
+        arr = self[...]
+        arr_np: NDArrayLike = np.array(arr, dtype=dtype)
 
         if dtype is not None:
             arr_np = arr_np.astype(dtype)
 
         return arr_np
 
-    def __getitem__(self, selection: Selection) -> NDArrayLike:
+    def __getitem__(self, selection: Selection) -> NDArrayLikeOrScalar:
         """Retrieve data for an item or region of the array.
 
         Parameters
@@ -2288,8 +2292,8 @@
 
         Returns
         -------
-        NDArrayLike
-             An array-like containing the data for the requested region.
+        NDArrayLikeOrScalar
+             An array-like or scalar containing the data for the requested region.
 
         Examples
         --------
@@ -2535,7 +2539,7 @@
         out: NDBuffer | None = None,
         prototype: BufferPrototype | None = None,
         fields: Fields | None = None,
-    ) -> NDArrayLike:
+    ) -> NDArrayLikeOrScalar:
         """Retrieve data for an item or region of the array.
 
         Parameters
@@ -2553,8 +2557,8 @@
 
         Returns
         -------
-        NDArrayLike
-            An array-like containing the data for the requested region.
+        NDArrayLikeOrScalar
+            An array-like or scalar containing the data for the requested region.
 
         Examples
         --------
@@ -2755,7 +2759,7 @@
         out: NDBuffer | None = None,
         fields: Fields | None = None,
         prototype: BufferPrototype | None = None,
-    ) -> NDArrayLike:
+    ) -> NDArrayLikeOrScalar:
         """Retrieve data by making a selection for each dimension of the array. For
         example, if an array has 2 dimensions, allows selecting specific rows and/or
         columns. The selection for each dimension can be either an integer (indexing a
@@ -2777,8 +2781,8 @@
 
         Returns
         -------
-        NDArrayLike
-            An array-like containing the data for the requested selection.
+        NDArrayLikeOrScalar
+            An array-like or scalar containing the data for the requested selection.
 
         Examples
         --------
@@ -2991,7 +2995,7 @@
         out: NDBuffer | None = None,
         fields: Fields | None = None,
         prototype: BufferPrototype | None = None,
-    ) -> NDArrayLike:
+    ) -> NDArrayLikeOrScalar:
         """Retrieve a selection of individual items, by providing a Boolean array of the
         same shape as the array against which the selection is being made, where True
         values indicate a selected item.
@@ -3011,8 +3015,8 @@
 
         Returns
         -------
-        NDArrayLike
-            An array-like containing the data for the requested selection.
+        NDArrayLikeOrScalar
+            An array-like or scalar containing the data for the requested selection.
 
         Examples
         --------
@@ -3153,7 +3157,7 @@
         out: NDBuffer | None = None,
         fields: Fields | None = None,
         prototype: BufferPrototype | None = None,
-    ) -> NDArrayLike:
+    ) -> NDArrayLikeOrScalar:
         """Retrieve a selection of individual items, by providing the indices
         (coordinates) for each selected item.
 
@@ -3171,8 +3175,8 @@
 
         Returns
         -------
-        NDArrayLike
-            An array-like containing the data for the requested coordinate selection.
+        NDArrayLikeOrScalar
+            An array-like or scalar containing the data for the requested coordinate selection.
 
         Examples
         --------
@@ -3341,7 +3345,7 @@
         out: NDBuffer | None = None,
         fields: Fields | None = None,
         prototype: BufferPrototype | None = None,
-    ) -> NDArrayLike:
+    ) -> NDArrayLikeOrScalar:
         """Retrieve a selection of individual items, by providing the indices
         (coordinates) for each selected item.
 
@@ -3359,8 +3363,8 @@
 
         Returns
         -------
-        NDArrayLike
-            An array-like containing the data for the requested block selection.
+        NDArrayLikeOrScalar
+            An array-like or scalar containing the data for the requested block selection.
 
         Examples
         --------

src/zarr/core/buffer/__init__.py

@@ -3,6 +3,7 @@
     Buffer,
     BufferPrototype,
     NDArrayLike,
+    NDArrayLikeOrScalar,
     NDBuffer,
     default_buffer_prototype,
 )
@@ -13,6 +14,7 @@
     "Buffer",
     "BufferPrototype",
     "NDArrayLike",
+    "NDArrayLikeOrScalar",
     "NDBuffer",
     "default_buffer_prototype",
     "numpy_buffer_prototype",

src/zarr/core/buffer/core.py

@@ -105,6 +105,10 @@
         """
 
 
+ScalarType = int | float | complex | bytes | str | bool | np.generic
+NDArrayLikeOrScalar = ScalarType | NDArrayLike
+
+
 def check_item_key_is_1d_contiguous(key: Any) -> None:
     """Raises error if `key` isn't a 1d contiguous slice"""
     if not isinstance(key, slice):
@@ -419,6 +423,21 @@
         """
         ...
 
+    def as_scalar(self) -> ScalarType:
+        """Returns the buffer as a scalar value"""
+        if self._data.size != 1:
+            raise ValueError("Buffer does not contain a single scalar value")
+        item = self.as_numpy_array().item()
+        scalar: ScalarType
+
+        if np.issubdtype(self.dtype, np.datetime64):
+            unit: str = np.datetime_data(self.dtype)[0]  # Extract the unit (e.g., 'Y', 'D', etc.)
+            scalar = np.datetime64(item, unit)
+        else:
+            scalar = self.dtype.type(item)  # Regular conversion for non-datetime types
+
+        return scalar
+
     @property
     def dtype(self) -> np.dtype[Any]:
         return self._data.dtype

src/zarr/core/indexing.py

@@ -29,7 +29,7 @@
 
 if TYPE_CHECKING:
     from zarr.core.array import Array
-    from zarr.core.buffer import NDArrayLike
+    from zarr.core.buffer import NDArrayLikeOrScalar
     from zarr.core.chunk_grids import ChunkGrid
     from zarr.core.common import ChunkCoords
 
@@ -937,7 +937,7 @@ class OIndex:
     array: Array
 
     # TODO: develop Array generic and move zarr.Array[np.intp] | zarr.Array[np.bool_] to ArrayOfIntOrBool
-    def __getitem__(self, selection: OrthogonalSelection | Array) -> NDArrayLike:
+    def __getitem__(self, selection: OrthogonalSelection | Array) -> NDArrayLikeOrScalar:
         from zarr.core.array import Array
 
         # if input is a Zarr array, we materialize it now.
@@ -1046,7 +1046,7 @@ def __iter__(self) -> Iterator[ChunkProjection]:
 class BlockIndex:
     array: Array
 
-    def __getitem__(self, selection: BasicSelection) -> NDArrayLike:
+    def __getitem__(self, selection: BasicSelection) -> NDArrayLikeOrScalar:
         fields, new_selection = pop_fields(selection)
         new_selection = ensure_tuple(new_selection)
         new_selection = replace_lists(new_selection)
@@ -1236,7 +1236,9 @@ class VIndex:
     array: Array
 
     # TODO: develop Array generic and move zarr.Array[np.intp] | zarr.Array[np.bool_] to ArrayOfIntOrBool
-    def __getitem__(self, selection: CoordinateSelection | MaskSelection | Array) -> NDArrayLike:
+    def __getitem__(
+        self, selection: CoordinateSelection | MaskSelection | Array
+    ) -> NDArrayLikeOrScalar:
         from zarr.core.array import Array
 
         # if input is a Zarr array, we materialize it now.

tests/test_api.py

@@ -23,6 +23,7 @@
     save_array,
     save_group,
 )
+from zarr.core.buffer import NDArrayLike
 from zarr.core.common import JSON, MemoryOrder, ZarrFormat
 from zarr.errors import MetadataValidationError
 from zarr.storage import MemoryStore
@@ -236,7 +237,9 @@ def test_open_with_mode_r(tmp_path: pathlib.Path) -> None:
     z2 = zarr.open(store=tmp_path, mode="r")
     assert isinstance(z2, Array)
     assert z2.fill_value == 1
-    assert (z2[:] == 1).all()
+    result = z2[:]
+    assert isinstance(result, NDArrayLike)
+    assert (result == 1).all()
     with pytest.raises(ValueError):
         z2[:] = 3
 
@@ -248,7 +251,9 @@ def test_open_with_mode_r_plus(tmp_path: pathlib.Path) -> None:
     zarr.ones(store=tmp_path, shape=(3, 3))
     z2 = zarr.open(store=tmp_path, mode="r+")
     assert isinstance(z2, Array)
-    assert (z2[:] == 1).all()
+    result = z2[:]
+    assert isinstance(result, NDArrayLike)
+    assert (result == 1).all()
     z2[:] = 3
 
 
@@ -264,7 +269,9 @@ async def test_open_with_mode_a(tmp_path: pathlib.Path) -> None:
     arr[...] = 1
     z2 = zarr.open(store=tmp_path, mode="a")
     assert isinstance(z2, Array)
-    assert (z2[:] == 1).all()
+    result = z2[:]
+    assert isinstance(result, NDArrayLike)
+    assert (result == 1).all()
     z2[:] = 3
 
 
@@ -276,7 +283,9 @@ def test_open_with_mode_w(tmp_path: pathlib.Path) -> None:
     arr[...] = 3
     z2 = zarr.open(store=tmp_path, mode="w", shape=(3, 3))
     assert isinstance(z2, Array)
-    assert not (z2[:] == 3).all()
+    result = z2[:]
+    assert isinstance(result, NDArrayLike)
+    assert not (result == 3).all()
     z2[:] = 3
 
 
@@ -1120,7 +1129,9 @@ def test_open_array_with_mode_r_plus(store: Store) -> None:
     zarr.ones(store=store, shape=(3, 3))
     z2 = zarr.open_array(store=store, mode="r+")
     assert isinstance(z2, Array)
-    assert (z2[:] == 1).all()
+    result = z2[:]
+    assert isinstance(result, NDArrayLike)
+    assert (result == 1).all()
     z2[:] = 3