feat: read-only builtin zip: URL pipeline adapter

[jhamman]

(not ready for review yet)

Summary

Adds a builtin, read-only zip: URL pipeline adapter
(schemes/zip.md). This makes
the headline example from #2943 work:

zarr.open_group("/data/my-archive.zip|zip:inner-dir|zarr3:subgroup", mode="r")
zarr.open_group("s3://bucket/data.zip|zip:path/in/archive", storage_options={"anon": True})
zarr.open_array("file:/data/outer.zip|zip:inner.zip|zip:x")          # nested archives

How it works (src/zarr/storage/_url_adapters/_zip.py):

• The adapter resolves the preceding pipeline with context.resolve_preceding(mode="r").
  The archive is the value at preceding.path in preceding.store, or the store's root
  object when the path is empty (a local file or an fsspec object).
• ZipReaderStore is a thin, read-only store over that resource. It uses async byte-range
  requests only:
  • At open, it reads the archive's size and the last 64 KiB + 22 bytes. It parses the
    central directory with the stdlib zipfile in asyncio.to_thread, over a sparse
    in-memory view; any range the view lacks is fetched and the parse retried. This handles
    central directories larger than the initial read.
  • On get, it reads the member's local header once (the offset is cached) and then the
    member's data.
  • Stored (uncompressed) members get true range reads. Deflate and bzip2 members are fetched
    whole and decompressed, in a thread above 1 MiB. CRC-32 is verified. Other methods (for
    example LZMA) and encrypted members raise NotImplementedError.
  • Directory entries (dir/) are not keys.
  • close() closes the preceding store, which the reader owns.
• Body: one leading / is ignored, and //... is invalid. A query, . or .. segments
  raise URLPipelineError. The body becomes the residual path, and every other preceding
  field (for example zarr_format) is carried forward with dataclasses.replace.
• Modes: "w", "w-" and "r+" raise URLPipelineError("zip: is read-only until writable ZIP support lands; ..."). "r", None and "a" open read-only; "a" (the zarr.open
  default) serves the "open" half, per the contract from feat: url-pipeline core — parser, adapter ABC, registry, store hooks #4192.
• Errors: a resource that is not a ZIP archive, a directory, or an unreadable root raises
  URLPipelineError chained from the original exception, and the preceding store is closed.
• zip is an adapter-only scheme, like zarr* in feat: builtin zarr:, zarr2: and zarr3: URL pipeline adapters #4476. A string without |, such as
  fsspec's zip://... or zip::file://..., behaves exactly as before.

Why not ZipStore?

The adapter must work for local and remote (fsspec) roots and must not block zarr's I/O
event loop. ZipStore needs a local path or a sync file object, and it does blocking
zipfile I/O inside its async methods. Over an fsspec root that means either downloading the
archive or making sync, loop-blocking reads through an fsspec file object. The reader here
uses only the preceding store's async get(..., byte_range=...) and getsize. So one code
path serves local files, fsspec objects, memory: entries, and archives nested in other
archives. For an uncompressed archive (ZipStore's default), a chunk read is a single range
request.

The get("") quirk (F2)

Reading an archive that is the pipeline root relies on LocalStore / FsspecStore treating
the empty key as the root object. That reliance is isolated in two helpers,
_read_resource_range and _resource_size. The file-resource primitive in the next PR
replaces both.

Depends on

• feat: url-pipeline core — parser, adapter ABC, registry, store hooks #4192 (URL pipeline core) and feat: builtin zarr:, zarr2: and zarr3: URL pipeline adapters #4476 (zarr*: adapters). This branch is stacked on
  feature/url-pipeline-format-adapters, so review only the commits after 37b2f490.

Closes

• The read-only zip: half of follow-up F9 and roadmap row Z2.
• Part of Support ZEP 8 URL Syntax #2943 (headline example with a local or fsspec root).

Decision needed

• Thin range-reading reader vs. ZipStore. Implemented: the thin reader described above.
  Alternative: open ZipStore on a local path (in a thread) for local roots, and on an fsspec
  file object for remote roots. That is less code, but it blocks the event loop and does not
  compose with nested archives.
• Mode "a" on zip:. Implemented: open read-only, following the open-or-create
  contract. Alternative: reject every mode except "r" until writes are supported. That is
  stricter, but zarr.open(url) (default "a") would then fail on a perfectly readable
  archive.

For reviewers

• _SparseFile / _parse_central_directory: is lazily fetching ranges into the stdlib
  zipfile parser robust enough? It raises a private exception on a missing range and
  retries after fetching it.
• Compressed members are not cached. A compressed nested archive is therefore decompressed
  once per read of the inner archive. Stored members, the common case for Zarr ZIP stores,
  are read with ranges.

Tests

uv sync --frozen
uv run --frozen ruff check src tests
uv run --frozen mypy src
uv run --frozen --with pytest-examples pytest -n auto tests
pre-commit run --all-files

Full suite: 13053 passed, 1295 skipped, 9 xfailed. ruff, mypy and pre-commit are clean.

New tests are in tests/test_url_pipeline/test_zip_adapter.py:

• archives written by ZipStore, opened as file:/…/a.zip|zip:, file://…,
  file://localhost… and schemeless paths;
• /…/a.zip|zip:inner|zarr3:sub and the headline example;
• fsspec roots: local:// and an in-memory fsspec filesystem standing in for a remote
  object store;
• a memory: entry, and nested zip: (stored and deflated outer archives);
• stored, deflate and bzip2 members; directory entries; a central directory larger than the
  first read; byte ranges; a CRC mismatch;
• mode rules, malformed bodies, non-archives, and closing the preceding store on error and on
  close().

Author attestation

• I am a human, these are my changes, and I have reviewed and understood every change and can explain why each is correct.

TODO

• Add unit tests and/or doctests in docstrings
• Add docstrings and API docs for any new/modified user-facing classes and functions
• New/modified features documented in docs/user-guide/*.md
• Changes documented as a new file in changes/
• GitHub Actions have all passed
• Test coverage is 100% (Codecov passes)

🤖 Generated with Claude Code