Skip to content

Commit 26558e0

Browse files
authored
docs: state the rectilinear-flag consequence of #4272 and qualify nchunks_initialized (#4323)
The 4272 changelog fragment omitted the one effect visible to users who never enable rectilinear chunks: a uniform nested chunk sequence such as `((4,), (4,))` was accepted as a regular grid in 3.3.0 and now raises the "experimental and disabled by default" error again, as in 3.2.x. Say so, and point at the integer-per-dimension form. The nchunks_initialized docstrings rewritten in #4218 read as an exact count, but every initialized shard is counted at its full declared size, so edge shards that overhang the array can push the result above nchunks. That is unchanged behavior; the docstrings now describe it. Assisted-by: ClaudeCode:claude-fable-5-1
1 parent 4998618 commit 26558e0

2 files changed

Lines changed: 34 additions & 13 deletions

File tree

‎changes/4272.bugfix.md‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,17 @@ regular grid, nested sequences produce a rectilinear grid. Rectilinear grids
1010
remain gated behind `zarr.config.set({"array.rectilinear_chunks": True})`.
1111
See #4174 for the accompanying O(1) chunk normalization change.
1212

13+
One consequence for users who never enable rectilinear chunks: because a
14+
nested sequence now always requests a rectilinear grid, a per-dimension
15+
sequence of edge lengths that happens to be uniform — for example the
16+
`((4,), (4,))` or `[[3, 3, 1]]` form that a dask array's `.chunks` attribute
17+
produces — is no longer quietly accepted as a regular grid when the
18+
`array.rectilinear_chunks` option is off. Such input raises
19+
`ValueError: Rectilinear chunk grids are experimental and disabled by default`,
20+
exactly as it did in 3.2.x; the silent acceptance existed only in 3.3.0. Pass
21+
one integer per dimension (e.g. `chunks=(4, 4)`, or a dask array's
22+
`.chunksize`) to request a regular grid.
23+
1324
`zarr.from_array` with the default `chunks="keep"` / `shards="keep"` now
1425
reproduces the source's stored grid exactly: a rectilinear grid is passed
1526
through in O(number of dimensions), with uniform dimensions keeping their
@@ -21,7 +32,7 @@ a rectilinear shard grid `Array.info` no longer raises — it reports the shard
2132
shape as `<variable>` — while `Array.nchunks_initialized` counts the chunks of
2233
each initialized shard individually instead of raising.
2334

24-
Everything described here concerns rectilinear chunk grids, which remain an
25-
experimental feature gated behind
26-
`zarr.config.set({"array.rectilinear_chunks": True})`; arrays with regular
27-
chunk grids are unaffected.
35+
Apart from the nested-sequence input form noted above, everything described
36+
here concerns rectilinear chunk grids, which remain an experimental feature
37+
gated behind `zarr.config.set({"array.rectilinear_chunks": True})`; arrays
38+
with regular chunk grids are unaffected.

‎src/zarr/core/array.py‎

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1224,9 +1224,12 @@ async def nchunks_initialized(self) -> int:
12241224
Calculate the number of chunks that have been initialized in storage.
12251225
12261226
This value is calculated as the sum of the number of chunks in every initialized shard
1227-
(shard sizes can vary when the shard grid is rectilinear). For arrays that do not use
1228-
sharding, each stored object holds one chunk, so the number of chunks initialized is the
1229-
same as the number of stored objects associated with an array.
1227+
(shard sizes can vary when the shard grid is rectilinear). Each initialized shard is
1228+
counted at its full declared size, so for an edge shard that extends beyond the array
1229+
extent this includes chunks that lie entirely outside the array, and the result can
1230+
exceed `nchunks`. For arrays that do not use sharding, each stored object holds one
1231+
chunk, so the number of chunks initialized is the same as the number of stored objects
1232+
associated with an array.
12301233
12311234
Returns
12321235
-------
@@ -2347,9 +2350,13 @@ def nchunks_initialized(self) -> int:
23472350
Calculate the number of chunks that have been initialized in storage.
23482351
23492352
This value is calculated as the sum of the number of chunks in every initialized shard
2350-
(shard sizes can vary when the shard grid is rectilinear). For arrays that do not use sharding,
2351-
each stored object holds one chunk, so the number of chunks initialized is the same as the number
2352-
of stored objects associated with an array. For a direct count of the number of initialized stored objects, see `nshards_initialized`.
2353+
(shard sizes can vary when the shard grid is rectilinear). Each initialized shard is
2354+
counted at its full declared size, so for an edge shard that extends beyond the array
2355+
extent this includes chunks that lie entirely outside the array, and the result can
2356+
exceed `nchunks`. For arrays that do not use sharding, each stored object holds one
2357+
chunk, so the number of chunks initialized is the same as the number of stored objects
2358+
associated with an array. For a direct count of the number of initialized stored
2359+
objects, see `nshards_initialized`.
23532360
23542361
Returns
23552362
-------
@@ -5423,9 +5430,12 @@ async def _nchunks_initialized(
54235430
Calculate the number of chunks that have been initialized in storage.
54245431
54255432
This value is calculated as the sum of the number of chunks in every initialized shard
5426-
(shard sizes can vary when the shard grid is rectilinear). For arrays that do not use
5427-
sharding, each stored object holds one chunk, so the number of chunks initialized is the
5428-
same as the number of stored objects associated with an array.
5433+
(shard sizes can vary when the shard grid is rectilinear). Each initialized shard is
5434+
counted at its full declared size, so for an edge shard that extends beyond the array
5435+
extent this includes chunks that lie entirely outside the array, and the result can
5436+
exceed `nchunks`. For arrays that do not use sharding, each stored object holds one
5437+
chunk, so the number of chunks initialized is the same as the number of stored objects
5438+
associated with an array.
54295439
54305440
Parameters
54315441
----------

0 commit comments

Comments
 (0)