Skip to content

adjust docstrings for _iter_shard methods / functions #3615

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
melonora wants to merge 1 commit into
base: main
Choose a base branch
from
Open

adjust docstrings for _iter_shard methods / functions #3615

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 39 additions & 13 deletions src/zarr/core/array.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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, ...]
Expand Down Expand Up @@ -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)

Expand Down Expand Up @@ -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`.
Expand All @@ -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,
Expand All @@ -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
Expand All @@ -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(
Expand Down Expand Up @@ -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
Expand All @@ -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)

Expand Down Expand Up @@ -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
Expand All @@ -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)

Expand Down Expand Up @@ -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
----------
Expand All @@ -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)

Expand Down Expand Up @@ -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
----------
Expand All @@ -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
-------
Expand Down Expand Up @@ -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
----------
Expand All @@ -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)

Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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
----------
Expand All @@ -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
Expand Down