feat(indexing): make LazyArray indexing lazy by default

[d-v-b]

This PR applies a range of improvements to the lazy indexing API, bringing it into closer alignment with tensorstore, although we still use relative indexing when indexing with plain python objects.

🤖 AI text below 🤖

LazyArray currently requires .lazy at each selection step; ordinary indexing materializes immediately. This PR makes the wrapper lazy by default, matching TensorStore: view[...], view.oindex[...], and view.vindex[...] return composed views, and iteration yields lazy first-axis views. result() and NumPy conversion materialize values. The .lazy accessor is removed.

Writes

Adds synchronous view.write(values) and assignment through composed views (view[...] = , view.oindex[...] = , view.vindex[...] = ). Writes update the original source, snapshot the RHS before mutation, and apply repeated destinations in C order with the last value winning, the same contract TensorStore uses. Out-of-range coordinates raise before anything is written.

Writes are planned against the source's write grid, discovered from write_chunk_sizes and then chunks, so sharded arrays are written by shard:

• an independent affine selection is one basic slice assignment;
• a NumPy source receives one fancy assignment;
• any other readable source is written one grid cell at a time: the cell's touched hull is read once, updated in memory, and written back with one basic slice;
• a source with no advertised grid, a source that cannot be read, or a transform the planner cannot factor falls back to one integer assignment per element, which never reads.

Storage round trips therefore scale with touched chunks rather than selected elements. On a 1000×1000 int64 zarr array with 100×100 chunks:

write	native zarr	per-element fallback	this PR
vindex, 2,000 points	100 chunk writes	1,999	100
oindex, 50 rows	100 chunk writes, 10 ms	49,999, 27 s	100, 82 ms
basic strided slab	60 chunk writes	60	60

Writes bypass the reader, so a caching reader is not invalidated; this is documented and pinned by a test. Writes are not transactional, and backend errors can leave partial writes. No asynchronous execution engine is introduced.

Literal domains, relative keys

Views keep their literal domain instead of re-zeroing after every selection, as TensorStore views do: a[10:20] has domain [10, 20), a[10:20][2:5] has [12, 15), and a reversed view carries the negative origin the algebra already produced. NumPy keys stay positional, normalized against the domain's origin, so a[10:20][0] is still the first element.

The type of a key decides whether it is relative or absolute. NumPy keys (slices, integers, ..., None, index arrays, masks) are positions relative to the view. An IndexDomain key names absolute coordinates of the view's domain, restricted to a box; empty intervals outside the view are refused too. An IndexTransform key composes onto the view, so any selection can be spelled in absolute coordinates by indexing the identity over the view's domain. No key type has two readings, and whichever key produced a view, view.transform.domain is absolute. This is documented in a new guide section with a runnable snippet, in the module docstring, and in the README.

Box partitions keep the request's coordinates, so a part view's domain is a sub-domain of its parent's; a part placed by index arrays keeps a fresh zero-origin domain, and out_selection is the placement in both cases. Two frames stay zero-origin by construction so no consumer subtracts an origin: ReadContext re-bases its transform, and parts() re-bases each projection's cell_transform to positions in the view's result buffer. A table-driven test states the expected literal domain for every indexing form and nested chain.

Eager adapter

A separate EagerArrayAdapter supplies eager indexing for consumers such as Dask's from_array. It delegates shape, rank, dtype, NumPy conversion, and tokenization to the view and materializes each indexed block. Documentation, examples, and existing tests use the revised interface. The unreleased LazyArray changelog fragment now describes the shipped surface.

This changes the experimental zarr-indexing wrapper; it does not add or change a zarr.Array.lazy accessor or claim full NumPy advanced-indexing compatibility.

Validation

• Full zarr-indexing suite with Dask installed, including doctests: 1,692 passed.
• Recording-source tests verify indexing and iteration defer reads.
• Write tests cover NumPy and Zarr sources, composed selections, negative strides, duplicate destinations, broadcasting, source aliases, masks, empty selections, and randomized selection chains checked against an independent coordinate oracle. New tests count chunk-store round trips for orthogonal, vectorized, and duplicate writes on plain and sharded zarr arrays, a write grid coarser than the read grid, and every fallback path.
• Independent review ran 2,500 API-level and 3,000 direct transform trials plus an exhaustive 1,536-case sweep of the affine fast path with no failures.
• A second independent review of the literal-domain change ran about 4,000 randomized views (840 with nonzero origins, 380 negative) over numpy, masked, and zarr sources, checking reads, part assembly, nested parts, writes, the eager adapter, and tokens against the previous behavior, with no failures.
• Strict MkDocs build, pre-commit hooks, and Pyright (zero errors) pass.

🤖 Generated with Claude Code

[read-the-docs-community]

Documentation build overview

📚 zarr-indexing | 🛠️ Build #34587459 | 📁 Comparing 65d1afb against latest (ba883a5)

  🔍 Preview build  

26 files changed · + 2 added · ± 24 modified

+ Added

• api/eager/index.html
• api/writer/index.html

± Modified

• index.html
• api/index.html
• design-notes/index.html
• guide/index.html
• ndsel/index.html
• api/boundary/index.html
• api/chunk_resolution/index.html
• api/domain/index.html
• api/errors/index.html
• api/grid/index.html
• and 14 more...

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.34%. Comparing base (2a704a7) to head (65d1afb).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #4350   +/-   ##
=======================================
  Coverage   94.34%   94.34%           
=======================================
  Files          92       92           
  Lines       12948    12948           
=======================================
  Hits        12216    12216           
  Misses        732      732           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.