feat(indexing): make LazyArray indexing lazy by default

[d-v-b]

🤖 AI text below 🤖

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

Adds synchronous view.write(values) and assignment through the composed view. These update the original source, snapshot the RHS before mutation, and apply repeated destinations in C order with the last value winning. Affine writes use ascending basic slices; more general selections use scalar assignments. Writes are not transactional, and backend errors can leave partial writes. No asynchronous execution engine is introduced.

A separate EagerArrayAdapter supplies eager indexing for consumers such as Dask's from_array. Documentation, examples, and existing tests use the revised interface. 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.

Stack

Depends on #4345, #4346, #4347, #4348, and #4349. Their current heads are included in this branch. GitHub targets main because the prerequisite branches live in the fork; the full PR diff therefore includes those prerequisites. Rebase after they merge.

Focused LazyArray implementation commit

Validation

• Full zarr-indexing suite, including doctests: 1,681 passed.
• Recording-source tests verify indexing and iteration defer reads.
• Write tests cover NumPy and Zarr, composed selections, negative strides, duplicate destinations, broadcasting, source aliases, masks, empty selections, and randomized selection chains checked against an independent coordinate oracle.
• Documentation examples and strict MkDocs build passed.
• Pyright: zero errors (100 warnings); applicable repository hooks passed.

[read-the-docs-community]

Documentation build overview

📚 zarr-indexing | 🛠️ Build #34538729 | 📁 Comparing a6f9949 against latest (ba883a5)

  🔍 Preview build  

24 files changed · ± 24 modified

± 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 (ba883a5) to head (a6f9949).

Additional details and impacted files

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

🚀 New features to boost your workflow:

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