add nshards, nshards_initialized

Author: d-v-b

src/zarr/core/array.py

@@ -1227,15 +1227,32 @@ def shard_grid_shape(self) -> ChunkCoords:
     @property
     def nchunks(self) -> int:
         """
-        The number of chunks in the stored representation of this array.
+        The number of chunks in this array.
+
+        Note that if a sharding codec is used, then the number of chunks may exceed the number of
+        stored objects supporting this array. To find out the number of stored objects that support
+        this array, see :func:`nshards`.
 
         Returns
         -------
         int
             The total number of chunks in the array.
         """
+        return product(self.chunk_grid_shape)
+
+    @property
+    def nshards(self) -> int:
+        """
+        The number of shards in this array.
+
+        Returns
+        -------
+        int
+            The total number of shards in the array.
+        """
         return product(self.shard_grid_shape)
 
+    @deprecated("Use nshards_initialized instead")
     async def nchunks_initialized(self) -> int:
         """
         Calculate the number of chunks that have been initialized, i.e. the number of chunks that have
@@ -1262,6 +1279,32 @@ async def nchunks_initialized(self) -> int:
         """
         return len(await shards_initialized(self))
 
+    async def nshards_initialized(self) -> int:
+        """
+        Calculate the number of shards that have been initialized, i.e. the number of shards that have
+        been persisted to the storage backend.
+
+        Returns
+        -------
+        nshards_initialized : int
+            The number of shards that have been initialized.
+
+        Notes
+        -----
+        On :class:`AsyncArray` this is an asynchronous method, unlike the (synchronous)
+        property :attr:`Array.nshards_initialized`.
+
+        Examples
+        --------
+        >>> arr = await zarr.api.asynchronous.create(shape=(10,), chunks=(2,))
+        >>> await arr.nshards_initialized()
+        0
+        >>> await arr.setitem(slice(5), 1)
+        >>> await arr.nshards_initialized()
+        3
+        """
+        return len(await shards_initialized(self))
+
     async def nbytes_stored(self) -> int:
         return await self.store_path.store.getsize_prefix(self.store_path.path)
 
@@ -1860,7 +1903,7 @@ async def info_complete(self) -> Any:
             A property giving just the statically known information about an array.
         """
         return self._info(
-            await self.nchunks_initialized(),
+            await self.nshards_initialized(),
             await self.store_path.store.getsize_prefix(self.store_path.path),
         )
 
@@ -2327,10 +2370,21 @@ def shard_grid_shape(self) -> ChunkCoords:
     @property
     def nchunks(self) -> int:
         """
-        The number of chunks in the stored representation of this array.
+        The number of chunks in this array.
+
+        Note that if a sharding codec is used, then the number of chunks may exceed the number of
+        stored objects supporting this array. To find out the number of stored objects that support
+        this array, see :func:`nshards`.
         """
         return self._async_array.nchunks
 
+    @property
+    def nshards(self) -> int:
+        """
+        The number of shards in the stored representation of this array.
+        """
+        return self._async_array.nshards
+
     @property
     def nbytes(self) -> int:
         """
@@ -2347,6 +2401,7 @@ def nbytes(self) -> int:
         return self._async_array.nbytes
 
     @property
+    @deprecated("Use nshards_initialized instead.")
     def nchunks_initialized(self) -> int:
         """
         Calculate the number of chunks that have been initialized, i.e. the number of chunks that have
@@ -2373,6 +2428,28 @@ def nchunks_initialized(self) -> int:
         """
         return sync(self._async_array.nchunks_initialized())
 
+    @property
+    def nshards_initialized(self) -> int:
+        """
+        Calculate the number of shards that have been initialized, i.e. the number of shards that have
+        been persisted to the storage backend.
+
+        Returns
+        -------
+        nshards_initialized : int
+            The number of shards that have been initialized.
+
+        Examples
+        --------
+        >>> arr = await zarr.create(shape=(10,), chunks=(2,))
+        >>> arr.nshards_initialized
+        0
+        >>> arr[:5] = 1
+        >>> arr.nshard_initialized
+        3
+        """
+        return sync(self._async_array.nshards_initialized())
+
     def nbytes_stored(self) -> int:
         """
         Determine the size, in bytes, of the array actually written to the store.

tests/test_array.py

@@ -395,19 +395,27 @@ async def test_nchunks_initialized(
         arr[region] = 1
         expected = idx + 1
         if test_cls == Array:
-            observed = arr.nchunks_initialized
+            with pytest.warns(DeprecationWarning, match="Use nshards_initialized instead"):
+                observed = arr.nchunks_initialized
+            assert observed == arr.nshards_initialized
         else:
-            observed = await arr._async_array.nchunks_initialized()
+            with pytest.warns(DeprecationWarning, match="Use nshards_initialized instead"):
+                observed = await arr._async_array.nchunks_initialized()
+            assert observed == await arr._async_array.nshards_initialized()
         assert observed == expected
 
     # delete chunks
     for idx, key in enumerate(arr._iter_shard_keys()):
         sync(arr.store_path.store.delete(key))
         if test_cls == Array:
-            observed = arr.nchunks_initialized
+            with pytest.warns(DeprecationWarning, match="Use nshards_initialized instead"):
+                observed = arr.nchunks_initialized
+            assert observed == arr.nshards_initialized
         else:
-            observed = await arr._async_array.nchunks_initialized()
-        expected = arr.nchunks - idx - 1
+            with pytest.warns(DeprecationWarning, match="Use nshards_initialized instead"):
+                observed = await arr._async_array.nchunks_initialized()
+            assert observed == await arr._async_array.nshards_initialized()
+        expected = arr.nshards - idx - 1
         assert observed == expected
 
 
@@ -876,14 +884,14 @@ def test_write_empty_chunks_behavior(
 
     # initialize the store with some non-fill value chunks
     arr[:] = fill_value + 1
-    assert arr.nchunks_initialized == arr.nchunks
+    assert arr.nshards_initialized == arr.nshards
 
     arr[:] = fill_value
 
     if not write_empty_chunks:
-        assert arr.nchunks_initialized == 0
+        assert arr.nshards_initialized == 0
     else:
-        assert arr.nchunks_initialized == arr.nchunks
+        assert arr.nshards_initialized == arr.nshards
 
 
 @pytest.mark.parametrize(