doc notes about this being experimental until 3.3

Author: jhamman

changes/3534.feature.md

@@ -1 +1,3 @@
 Adds support for `RectilinearChunkGrid`, enabling arrays with variable chunk sizes along each dimension in Zarr v3. Users can now specify irregular chunking patterns using nested sequences: `chunks=[[10, 20, 30], [25, 25, 25, 25]]` creates an array with 3 chunks of sizes 10, 20, and 30 along the first dimension, and 4 chunks of size 25 along the second dimension. This feature is useful for data with non-uniform structure or when aligning chunks with existing data partitions. Note that `RectilinearChunkGrid` is only supported in Zarr format 3 and cannot be used with sharding or when creating arrays from existing data via `from_array()`.
+
+Note: `RectilinearChunkGrid` is an experimental feature and may change in future releases. This feature is expected to stabilize in version 3.3.

docs/user-guide/arrays.md

@@ -568,6 +568,10 @@ Without the `shards` argument, there would be 10,000 chunks stored as individual
 
 ## Variable Chunking (Zarr v3)
 
+!!! warning "Experimental Feature"
+    Variable chunking with `RectilinearChunkGrid` is an experimental feature and may change
+    in future releases. This feature is expected to stabilize in Zarr version 3.3.
+
 In addition to regular chunking where all chunks have the same size, Zarr v3 supports
 **variable chunking** (also called rectilinear chunking), where chunks can have different
 sizes along each dimension. This is useful when your data has non-uniform structure or

src/zarr/api/asynchronous.py

@@ -929,7 +929,8 @@ async def create(
         Chunk shape. If True, will be guessed from ``shape`` and ``dtype``. If
         False, will be set to ``shape``, i.e., single chunk for the whole array.
         If an int, the chunk size in each dimension will be given by the value
-        of ``chunks``. Default is True.
+        of ``chunks``. Default is True. Also supports nested sequences for
+        variable-sized chunks (Zarr format 3 only, experimental until 3.3).
     dtype : str or dtype, optional
         NumPy dtype.
     compressor : Codec, optional

src/zarr/api/synchronous.py

@@ -665,7 +665,8 @@ def create(
         Chunk shape. If True, will be guessed from ``shape`` and ``dtype``. If
         False, will be set to ``shape``, i.e., single chunk for the whole array.
         If an int, the chunk size in each dimension will be given by the value
-        of ``chunks``. Default is True.
+        of ``chunks``. Default is True. Also supports nested sequences for
+        variable-sized chunks (Zarr format 3 only, experimental until 3.3).
     dtype : str or dtype, optional
         NumPy dtype.
     compressor : Codec, optional
@@ -863,7 +864,8 @@ def create_array(
         Chunk shape of the array. Several formats are supported:
 
         - tuple of ints: Creates a RegularChunkGrid with uniform chunks, e.g., ``(10, 10)``
-        - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks (Zarr format 3 only),
+        - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks
+          (Zarr format 3 only, experimental until 3.3),
           e.g., ``[[10, 20, 30], [5, 5]]`` creates variable chunks along each dimension
         - ChunkGrid instance: Uses the provided chunk grid directly (Zarr format 3 only)
         - "auto": Automatically determines chunk shape based on array shape and dtype

src/zarr/core/array.py

@@ -4986,7 +4986,8 @@ async def create_array(
         Chunk shape of the array. Several formats are supported:
 
         - tuple of ints: Creates a RegularChunkGrid with uniform chunks, e.g., ``(10, 10)``
-        - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks (Zarr format 3 only),
+        - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks
+          (Zarr format 3 only, experimental until 3.3),
           e.g., ``[[10, 20, 30], [5, 5]]`` creates variable chunks along each dimension
         - ChunkGrid instance: Uses the provided chunk grid directly (Zarr format 3 only)
         - "auto": Automatically determines chunk shape based on array shape and dtype

src/zarr/core/chunk_grids.py

@@ -195,6 +195,10 @@ class RectilinearChunks(ChunksType):
     """
     Chunk specification for arrays with variable chunk sizes per dimension.
 
+    .. warning::
+        This is an experimental feature and may change in future releases.
+        Expected to stabilize in Zarr version 3.3.
+
     Behaves like a tuple of tuples, where each inner tuple contains the
     chunk sizes along that dimension. Provides named access and additional
     methods for introspection when dimension_names are available.
@@ -866,6 +870,10 @@ class RectilinearChunkGrid(ChunkGrid):
     """
     A rectilinear chunk grid where chunk sizes vary along each axis.
 
+    .. warning::
+        This is an experimental feature and may change in future releases.
+        Expected to stabilize in Zarr version 3.3.
+
     Attributes
     ----------
     chunk_shapes : tuple[tuple[int, ...], ...]

src/zarr/core/group.py

@@ -1056,7 +1056,8 @@ async def create_array(
             Chunk shape of the array. Several formats are supported:
 
             - tuple of ints: Creates a RegularChunkGrid with uniform chunks, e.g., ``(10, 10)``
-            - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks (Zarr format 3 only),
+            - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks
+              (Zarr format 3 only, experimental until 3.3),
               e.g., ``[[10, 20, 30], [5, 5]]`` creates variable chunks along each dimension
             - ChunkGrid instance: Uses the provided chunk grid directly (Zarr format 3 only)
             - "auto": Automatically determines chunk shape based on array shape and dtype
@@ -2490,7 +2491,8 @@ def create(
             Chunk shape of the array. Several formats are supported:
 
             - tuple of ints: Creates a RegularChunkGrid with uniform chunks, e.g., ``(10, 10)``
-            - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks (Zarr format 3 only),
+            - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks
+              (Zarr format 3 only, experimental until 3.3),
               e.g., ``[[10, 20, 30], [5, 5]]`` creates variable chunks along each dimension
             - ChunkGrid instance: Uses the provided chunk grid directly (Zarr format 3 only)
             - "auto": Automatically determines chunk shape based on array shape and dtype
@@ -2639,7 +2641,8 @@ def create_array(
             Chunk shape of the array. Several formats are supported:
 
             - tuple of ints: Creates a RegularChunkGrid with uniform chunks, e.g., ``(10, 10)``
-            - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks (Zarr format 3 only),
+            - nested sequence: Creates a RectilinearChunkGrid with variable-sized chunks
+              (Zarr format 3 only, experimental until 3.3),
               e.g., ``[[10, 20, 30], [5, 5]]`` creates variable chunks along each dimension
             - ChunkGrid instance: Uses the provided chunk grid directly (Zarr format 3 only)
             - "auto": Automatically determines chunk shape based on array shape and dtype