(bug): `get_block_selection` semantics

[ilan-gold]

Zarr version

v3.0.6

Numcodecs version

0.15.1

Python Version

3.12

Operating System

Linux/Max

Installation

uv

Description

The below, based on https://zarr.readthedocs.io/en/latest/user-guide/arrays.html#block-indexing, would make me think that (0,5) should refer to a chunk not a shard, but the reverse is true judging by the out-of-bounds error (similarly, z.get_block_selection((0, 4)).shape gives (200,200)).

Steps to reproduce

import zarr

z = zarr.create_array('data/test.zarr', shape=(1000, 1000), shards=(200, 200), chunks=(100,100), dtype="uint8")
z.get_block_selection((0, 5))

---------------------------------------------------------------------------
BoundsCheckError                          Traceback (most recent call last)
Cell In[4], line 1
----> 1 z.get_block_selection((0, 5))

File /mnt/volume/zarr_benchmarks/venv/lib/python3.12/site-packages/zarr/_compat.py:43, in _deprecate_positional_args.<locals>._inner_deprecate_positional_args.<locals>.inner_f(*args, **kwargs)
     41 extra_args = len(args) - len(all_args)
     42 if extra_args <= 0:
---> 43     return f(*args, **kwargs)
     45 # extra_args > 0
     46 args_msg = [
     47     f"{name}={arg}"
     48     for name, arg in zip(kwonly_args[:extra_args], args[-extra_args:], strict=False)
     49 ]

File /mnt/volume/zarr_benchmarks/venv/lib/python3.12/site-packages/zarr/core/array.py:3426, in Array.get_block_selection(self, selection, out, fields, prototype)
   3424 if prototype is None:
   3425     prototype = default_buffer_prototype()
-> 3426 indexer = BlockIndexer(selection, self.shape, self.metadata.chunk_grid)
   3427 return sync(
   3428     self._async_array._get_selection(
   3429         indexer=indexer, out=out, fields=fields, prototype=prototype
   3430     )
   3431 )

File /mnt/volume/zarr_benchmarks/venv/lib/python3.12/site-packages/zarr/core/indexing.py:1026, in BlockIndexer.__init__(self, selection, shape, chunk_grid)
   1023     dim_indexers.append(dim_indexer)
   1025     if start >= dim_len or start < 0:
-> 1026         raise BoundsCheckError(dim_len)
   1028 shape = tuple(s.nitems for s in dim_indexers)
   1030 object.__setattr__(self, "dim_indexers", dim_indexers)

BoundsCheckError: 1000

Additional output

No response

[ilan-gold]

@LDeakin has informed me that this changed with #2463 so maybe just updating the docs at https://zarr.readthedocs.io/en/latest/user-guide/arrays.html#block-indexing would be nice?