From becdfbb8be1eca28d930b742c71cbe0339e1f91c Mon Sep 17 00:00:00 2001 From: Wouter-Michiel Vierdag Date: Thu, 4 Dec 2025 18:30:53 +0100 Subject: [PATCH] adjust docstrings --- src/zarr/core/array.py | 52 +++++++++++++++++++++++++++++++----------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 6b20ee950d..e6600c1b9b 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -1256,6 +1256,8 @@ def _shard_grid_shape(self) -> tuple[int, ...]: """ The shape of the shard grid for this array. + When no shards are present this will automatically fall back to the chunk grid. + Returns ------- tuple[int, ...] @@ -1287,10 +1289,12 @@ def _nshards(self) -> int: """ The number of shards in this array. + If no shards are present this will fall back to giving the number of chunks + Returns ------- int - The total number of shards in the array. + The total number of shards or if absent, chunks in the array. """ return product(self._shard_grid_shape) @@ -1418,6 +1422,8 @@ def _iter_shard_coords( """ Create an iterator over the coordinates of shards in shard grid space. + This will fall back to chunk grid space in case no shards are present. + Note that If the `origin` keyword is used, iteration will start at the shard index specified by `origin`. @@ -1436,7 +1442,7 @@ def _iter_shard_coords( Yields ------ chunk_coords: tuple[int, ...] - The coordinates of each shard in the selection. + The coordinates of each shard in the selection or chunk in case of no shard being present. """ return _iter_shard_coords( array=self, @@ -1450,6 +1456,9 @@ def _iter_shard_keys( """ Iterate over the keys of the stored objects supporting this array. + Although only stored objects, e.g. shards should have keys, in case no + shards are present this automatically falls back to chunks. + Parameters ---------- origin : Sequence[int] | None, default=None @@ -1460,7 +1469,8 @@ def _iter_shard_keys( Yields ------ key: str - The storage key of each chunk in the selection. + The storage key of each shard in the selection or in case of no shard + present of each chunk although the latter case as technically incorrect. """ # Iterate over the coordinates of chunks in chunk grid space. return _iter_shard_keys( @@ -1499,6 +1509,8 @@ def _iter_shard_regions( """ Iterate over the regions spanned by each shard. + This will automatically fall back to chunks if no shards are present. + Parameters ---------- origin : Sequence[int] | None, default=None @@ -1509,7 +1521,8 @@ def _iter_shard_regions( Yields ------ region: tuple[slice, ...] - A tuple of slice objects representing the region spanned by each shard in the selection. + A tuple of slice objects representing the region spanned by each shard in the selection or chunk in the + absence of shards. """ return _iter_shard_regions(array=self, origin=origin, selection_shape=selection_shape) @@ -2591,6 +2604,9 @@ def _iter_shard_keys( Iterate over the storage keys of each shard, relative to an optional origin, and optionally limited to a contiguous region in chunk grid coordinates. + If no shards are present this falls back to chunks, though in this case these are then actually + not storage keys. + Parameters ---------- origin : Sequence[int] | None, default=None @@ -2601,7 +2617,8 @@ def _iter_shard_keys( Yields ------ str - The storage key of each shard in the selection. + The storage key of each shard in the selection or chunk though chunks technically do not have + storage keys. """ return self.async_array._iter_shard_keys(origin=origin, selection_shape=selection_shape) @@ -2681,7 +2698,7 @@ def _iter_shard_regions( self, origin: Sequence[int] | None = None, selection_shape: Sequence[int] | None = None ) -> Iterator[tuple[slice, ...]]: """ - Iterate over the regions spanned by each shard. + Iterate over the regions spanned by each shard or chunk if no shard is present. Parameters ---------- @@ -2693,7 +2710,8 @@ def _iter_shard_regions( Yields ------ tuple[slice, ...] - A tuple of slice objects representing the region spanned by each chunk in the selection. + A tuple of slice objects representing the region spanned by each shard or if no shard is present, + chunk in the selection. """ return self.async_array._iter_shard_regions(origin=origin, selection_shape=selection_shape) @@ -4226,7 +4244,9 @@ async def _shards_initialized( array: AnyAsyncArray, ) -> tuple[str, ...]: """ - Return the keys of the chunks that have been persisted to the storage backend. + Return the keys of the shards that have been persisted to the storage backend. + + This will fall back to chunks in case no shards are present. Parameters ---------- @@ -4236,7 +4256,7 @@ async def _shards_initialized( Returns ------- chunks_initialized : tuple[str, ...] - The keys of the chunks that have been initialized. + The keys of the shards or if these are not present, chunks that have been initialized. Related ------- @@ -5381,6 +5401,8 @@ def _iter_shard_coords( If the `selection_shape` keyword is used, iteration will be bounded over a contiguous region ranging from `[origin, origin selection_shape]`, where the upper bound is exclusive as per python indexing conventions. + If no shards are present this will iterate over the coordinates of chunks in chunk grid space + instead. Parameters ---------- @@ -5394,7 +5416,7 @@ def _iter_shard_coords( Yields ------ chunk_coords: tuple[int, ...] - The coordinates of each shard in the selection. + The coordinates of each shard in the selection or chunks if no shards are present. """ return _iter_grid(array._shard_grid_shape, origin=origin, selection_shape=selection_shape) @@ -5409,6 +5431,8 @@ def _iter_shard_keys( Iterate over the storage keys of each shard, relative to an optional origin, and optionally limited to a contiguous region in shard grid coordinates. + This automatically falls back to chunks when no shards are present. + Parameters ---------- array : Array | AsyncArray @@ -5421,7 +5445,7 @@ def _iter_shard_keys( Yields ------ key: str - The storage key of each chunk in the selection. + The storage key of each shard in the selection or chunk when no shards are present. """ # Iterate over the coordinates of chunks in chunk grid space. _iter = _iter_grid(array._shard_grid_shape, origin=origin, selection_shape=selection_shape) @@ -5437,7 +5461,8 @@ def _iter_shard_regions( """ Iterate over the regions spanned by each shard. - These are the smallest regions of the array that are safe to write concurrently. + These are the smallest regions of the array that are safe to write concurrently. When + no shards are present this will fall back to chunks. Parameters ---------- @@ -5451,7 +5476,8 @@ def _iter_shard_regions( Yields ------ region: tuple[slice, ...] - A tuple of slice objects representing the region spanned by each shard in the selection. + A tuple of slice objects representing the region spanned by each shard in the selection or chunk + when no shards are present. """ if array.shards is None: shard_shape = array.chunks