revert changes to .chunks property / chunks-type

Author: jhamman

docs/user-guide/arrays.md

@@ -617,13 +617,13 @@ print(f"Slice [10:30, 50:75]: {z[10:30, 50:75].shape}")
 ### Accessing chunk information
 
 With variable chunking, the standard `.chunks` property is not available since chunks
-have different sizes. Instead, access chunk information through the chunk grid:
+have different sizes. Instead, access chunk information through the `.chunk_grid` property:
 
 ```python exec="true" session="arrays" source="above" result="ansi"
 from zarr.core.chunk_grids import RectilinearChunkGrid
 
 # Access the chunk grid
-chunk_grid = z.metadata.chunk_grid
+chunk_grid = z.chunk_grid
 print(f"Chunk grid type: {type(chunk_grid).__name__}")
 
 # Get chunk shapes for each dimension
@@ -659,8 +659,8 @@ z_timeseries = zarr.create_array(
     zarr_format=3
 )
 print(f"Created array with shape {z_timeseries.shape}")
-print(f"Chunk shapes: {z_timeseries.metadata.chunk_grid.chunk_shapes}")
-print(f"Number of chunks: {len(z_timeseries.metadata.chunk_grid.chunk_shapes[0])} months")
+print(f"Chunk shapes: {z_timeseries.chunk_grid.chunk_shapes}")
+print(f"Number of chunks: {len(z_timeseries.chunk_grid.chunk_shapes[0])} months")
 ```
 
 ### Limitations
@@ -678,8 +678,7 @@ Variable chunking has some important limitations:
    to partition the input data, which requires regular chunk sizes.
 
 4. **No `.chunks` property**: For arrays with variable chunking, accessing the `.chunks`
-   property will raise a `NotImplementedError`. Use `.metadata.chunk_grid.chunk_shapes`
-   instead.
+   property will raise a `NotImplementedError`. Use `.chunk_grid.chunk_shapes` instead.
 
 ## Missing features in 3.0
 

pyproject.toml

@@ -410,7 +410,8 @@ addopts = [
 filterwarnings = [
     "error",
     "ignore:Unclosed client session <aiohttp.client.ClientSession.*:ResourceWarning",
-    "ignore:Numcodecs codecs are not in the Zarr version 3 specification.*:UserWarning"
+    "ignore:Numcodecs codecs are not in the Zarr version 3 specification.*:UserWarning",
+    "ignore:Array.chunks is deprecated and will be removed in a future version.*:FutureWarning"
 ]
 markers = [
     "asyncio: mark test as asyncio test",

src/zarr/__init__.py

@@ -35,7 +35,6 @@
     zeros_like,
 )
 from zarr.core.array import Array, AsyncArray
-from zarr.core.chunk_grids import ChunksType, RectilinearChunks, RegularChunks
 from zarr.core.config import config
 from zarr.core.group import AsyncGroup, Group
 
@@ -148,10 +147,7 @@ def set_format(log_format: str) -> None:
     "Array",
     "AsyncArray",
     "AsyncGroup",
-    "ChunksType",
     "Group",
-    "RectilinearChunks",
-    "RegularChunks",
     "__version__",
     "array",
     "config",

src/zarr/core/array.py

@@ -43,9 +43,8 @@
 from zarr.core.chunk_grids import (
     ChunkGrid,
     ChunksLike,
-    ChunksType,
+    RectilinearChunkGrid,
     RegularChunkGrid,
-    RegularChunks,
     _auto_partition,
     _normalize_chunks,
     resolve_chunk_spec,
@@ -1052,34 +1051,52 @@ def shape(self) -> tuple[int, ...]:
         return self.metadata.shape
 
     @property
-    def chunks(self) -> ChunksType:
-        """Returns the chunk specification of the Array.
+    def chunk_grid(self) -> ChunkGrid:
+        """Returns the chunk grid of the Array.
 
-        Returns either RegularChunks (for uniform chunk sizes) or RectilinearChunks
-        (for variable chunk sizes per dimension). Both types behave like tuples but
-        provide richer semantics including named access when dimension_names are available.
+        Returns
+        -------
+        ChunkGrid
+            The chunk grid (RegularChunkGrid or RectilinearChunkGrid)
+        """
+        return self.metadata.chunk_grid
+
+    @property
+    def chunks(self) -> tuple[int, ...]:
+        """Returns the chunk shape of the Array.
+
+        .. deprecated::
+            The `chunks` property is deprecated and will be removed in a future version.
+            Use `chunk_grid` instead to access chunk information.
 
-        For arrays using RegularChunkGrid: returns RegularChunks with uniform chunk sizes.
+        For arrays using RegularChunkGrid: returns a tuple of ints with uniform chunk sizes.
         If sharding is used, the inner chunk shape is returned.
 
-        For arrays using RectilinearChunkGrid: returns RectilinearChunks where each
-        element is a tuple containing the chunk sizes along that dimension (not RLE encoded).
+        For arrays using RectilinearChunkGrid: raises NotImplementedError as variable chunks
+        cannot be represented as a simple tuple.
 
         Returns
         -------
-        ChunksType
-            RegularChunks for regular chunks or RectilinearChunks for variable chunks
+        tuple[int, ...]
+            The chunk shape for regular chunk grids
 
-        Examples
-        --------
-        >>> arr = zarr.create_array(shape=(100, 200), chunks=(10, 20))
-        >>> arr.chunks
-        RegularChunks((10, 20))
-        >>> isinstance(arr.chunks, RegularChunks)
-        True
-        >>> tuple(arr.chunks)
-        (10, 20)
+        Raises
+        ------
+        NotImplementedError
+            If the array uses RectilinearChunkGrid (variable chunks)
         """
+        if isinstance(self.metadata.chunk_grid, RectilinearChunkGrid):
+            msg = (
+                "The `chunks` property is not supported for arrays with variable chunk sizes "
+                "(RectilinearChunkGrid). Use `chunk_grid` instead to access chunk information."
+            )
+            raise NotImplementedError(msg)
+        warnings.warn(
+            "Array.chunks is deprecated and will be removed in a future version. "
+            "Use Array.chunk_grid.chunk_shape instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
         return self.metadata.chunks
 
     @property
@@ -1285,15 +1302,16 @@ def _chunk_grid_shape(self) -> tuple[int, ...]:
         tuple[int, ...]
             The shape of the chunk grid for this array.
         """
-        chunks = self.chunks
+        # For RectilinearChunkGrid, use the chunk_grid method
+        if isinstance(self.metadata.chunk_grid, RectilinearChunkGrid):
+            return self.metadata.chunk_grid.get_chunk_grid_shape(self.shape)
+        # For RegularChunkGrid (including sharded), use metadata.chunks which
+        # correctly returns the inner chunk shape for sharded arrays
+        chunk_shape = self.metadata.chunks
         # Handle 0-dimensional arrays
-        if len(chunks) == 0:
+        if len(chunk_shape) == 0:
             return ()
-        # For RegularChunkGrid (or sharded), use RegularChunks type check
-        if isinstance(chunks, RegularChunks):
-            return tuple(starmap(ceildiv, zip(self.shape, chunks, strict=True)))
-        # For RectilinearChunkGrid, use the chunk_grid method
-        return self.metadata.chunk_grid.get_chunk_grid_shape(self.shape)
+        return tuple(starmap(ceildiv, zip(self.shape, chunk_shape, strict=True)))
 
     @property
     def _shard_grid_shape(self) -> tuple[int, ...]:
@@ -1308,7 +1326,7 @@ def _shard_grid_shape(self) -> tuple[int, ...]:
             The shape of the shard grid for this array.
         """
         if self.shards is None:
-            shard_shape: tuple[int, ...] | ChunksType = self.chunks
+            shard_shape = self.metadata.chunk_grid.chunk_shape
         else:
             shard_shape = self.shards
         return tuple(starmap(ceildiv, zip(self.shape, shard_shape, strict=True)))
@@ -2396,20 +2414,39 @@ def shape(self, value: tuple[int, ...]) -> None:
         self.resize(value)
 
     @property
-    def chunks(self) -> tuple[int, ...] | tuple[tuple[int, ...], ...]:
-        """Returns the chunk specification of the Array.
+    def chunk_grid(self) -> ChunkGrid:
+        """Returns the chunk grid of the Array.
+
+        Returns
+        -------
+        ChunkGrid
+            The chunk grid (RegularChunkGrid or RectilinearChunkGrid)
+        """
+        return self.async_array.chunk_grid
+
+    @property
+    def chunks(self) -> tuple[int, ...]:
+        """Returns the chunk shape of the Array.
 
-        For arrays using RegularChunkGrid: returns a tuple of ints representing
-        the uniform chunk shape. If sharding is used, the inner chunk shape is returned.
+        .. deprecated::
+            The `chunks` property is deprecated and will be removed in a future version.
+            Use `chunk_grid` instead to access chunk information.
 
-        For arrays using RectilinearChunkGrid: returns a tuple of tuples, where
-        each inner tuple contains the chunk sizes along that dimension (not RLE encoded).
+        For arrays using RegularChunkGrid: returns a tuple of ints with uniform chunk sizes.
+        If sharding is used, the inner chunk shape is returned.
+
+        For arrays using RectilinearChunkGrid: raises NotImplementedError as variable chunks
+        cannot be represented as a simple tuple.
 
         Returns
         -------
-        tuple[int, ...] | tuple[tuple[int, ...], ...]
-            For regular chunks: (chunk_size_dim0, chunk_size_dim1, ...)
-            For rectilinear chunks: ((sizes_dim0), (sizes_dim1), ...)
+        tuple[int, ...]
+            The chunk shape for regular chunk grids
+
+        Raises
+        ------
+        NotImplementedError
+            If the array uses RectilinearChunkGrid (variable chunks)
         """
         return self.async_array.chunks
 
@@ -5664,16 +5701,14 @@ def _iter_shard_regions(
         If the array uses RectilinearChunkGrid (variable-sized chunks).
         when no shards are present.
     """
-    chunks = array.chunks
-    if not isinstance(chunks, RegularChunks):
+    if isinstance(array.metadata.chunk_grid, RectilinearChunkGrid):
         raise NotImplementedError(
             "_iter_shard_regions is not supported for arrays with variable-sized chunks "
             "(RectilinearChunkGrid). Use the chunk_grid API directly for variable chunk access."
         )
 
-    # Type narrowing: chunks is now RegularChunks (subclass of tuple[int, ...])
     if array.shards is None:
-        shard_shape: Sequence[int] = chunks
+        shard_shape: Sequence[int] = array.metadata.chunk_grid.chunk_shape
     else:
         shard_shape = array.shards
 
@@ -5712,17 +5747,15 @@ def _iter_chunk_regions(
     NotImplementedError
         If the array uses RectilinearChunkGrid (variable-sized chunks).
     """
-    chunks = array.chunks
-    if not isinstance(chunks, RegularChunks):
+    if isinstance(array.metadata.chunk_grid, RectilinearChunkGrid):
         raise NotImplementedError(
             "_iter_chunk_regions is not supported for arrays with variable-sized chunks "
             "(RectilinearChunkGrid). Use the chunk_grid API directly for variable chunk access."
         )
 
-    # Type narrowing: chunks is now RegularChunks (subclass of tuple[int, ...])
     return _iter_regions(
         array.shape,
-        chunks,
+        array.metadata.chunk_grid.chunk_shape,
         origin=origin,
         selection_shape=selection_shape,
         trim_excess=True,