Surface mode in vz.to_icechunk, keeping current defaults

[aaronspring]

Closes #1001.

Exposes mode in vz.to_icechunk

claude

What this does

Adds a mode parameter to vds.vz.to_icechunk and dt.vz.to_icechunk (and the underlying virtual_dataset_to_icechunk / virtual_datatree_to_icechunk writers) controlling how a pre-existing group at the target path is handled:

• "w-": create the group, raising ContainsGroupError if it already exists — the previous and still-default behaviour (mode=None).
• "w": create the group, overwriting any existing contents at that path.
• "a": open the group if it exists (keeping existing arrays), otherwise create it. This enables e.g. splitting a large virtual dataset across commits by variable, and writing a parent group after a child group — both scenarios from vz.to_icechunk throws ContainsGroupError when group already exists and doesn't surface mode #1001.

mode="w"/"w-" combined with append_dim or region raises a ValueError, since those require opening an existing group.

Implementation

Internally, a _resolve_mode helper validates mode and resolves it to the effective zarr group-open mode ("r+" when append_dim/region are given), and both writers now open groups through a single unconditional zarr.open_group(...) call instead of branching between Group.open and Group.from_store.

A side effect of that unification: writing a virtual DataTree with region/append_dim forwarded to each node previously always failed with ContainsGroupError (every node group was unconditionally created); existing groups are now opened instead, and the previously-xfailing test_write_datatree_region passes, so its xfail marker is removed.

Tests & docs

• New tests: default/"w-" still raising on existing groups (regression guard), variable-split across commits with mode="a" (the exact vz.to_icechunk throws ContainsGroupError when group already exists and doesn't surface mode #1001 workflow), parent-group-after-child with mode="a", mode="w" overwrite, invalid mode values, mode × append_dim conflicts, and a DataTree mode="a" write.
• Release notes entry and a note in the scaling guide's variable-splitting section.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 90.36%. Comparing base (a8eb06d) to head (54cff4a).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1035      +/-   ##
==========================================
+ Coverage   90.33%   90.36%   +0.03%     
==========================================
  Files          37       37              
  Lines        2235     2242       +7     
==========================================
+ Hits         2019     2026       +7     
  Misses        216      216              

Files with missing lines	Coverage Δ
virtualizarr/accessor.py	95.74% <ø> (ø)
virtualizarr/writers/icechunk.py	92.00% <100.00%> (+0.33%)	⬆️

🚀 New features to boost your workflow:

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

[aaronspring]

Split the DataTree region/append_dim ContainsGroupError fix out into #1036, since it's an independent bug and backportable on its own. This PR is now stacked on top of #1036 — until that merges, the diff here includes its one commit; once #1036 lands on main, this PR reduces to the mode feature only.

[aaronspring]

CI note: the 3 red build jobs (test-py312, test-py313, minimum-versions) fail only on test_parsers/test_grib.py (test_grib_virtual_dataset, test_grib_only_variables, test_grib_chunk_decodes_via_codec) — the GRIB/gribberish parser returning empty data_vars / a NodeTypeValidationError. These are pre-existing and unrelated to this PR: it touches only the icechunk writer/accessor and doesn't go near GRIB, and all 560 other tests pass (including the new mode tests). The same 3 failures show up on #1034 (a pre-commit.ci autoupdate that changes no source), #1032, #1033, and on scheduled main runs. codecov/* is just coverage thresholds, not test failures.

[aaronspring]

should I also allow r+ if region and a-?

[TomNicholas]

let's not bother for now

[TomNicholas]

Thank you very much @aaronspring !