feat: Implement ZEP 8 URL syntax support for zarr-python #3369

jhamman · 2025-08-11T20:24:50Z

This PR implements support for the ZEP 8 URL syntax in Zarr Python.

Some examples of what now works:

import zarr

root = zarr.open_group('s3://bucket/data.zip|zip:|zarr3:')  # S3 → ZIP → Zarr v3
arr = zarr.create_array('memory:|zarr2:group/array', shape=(10, ), dtype='i4')  # Memory → Zarr v2

# custom adapter for icechunk
ds = xr.open_zarr('s3://icechunk-public-data/v1/glad|icechunk:')  # icechunk (from xarray)

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/*.rst
Changes documented as a new file in changes/
GitHub Actions have all passed
Test coverage is 100% (Codecov passes)

closes #2943
fixes #2831
xref: zarr-developers/zeps#48

cc @jbms

- Add comprehensive ZEP 8 URL parsing and resolution system - Implement StoreAdapter ABC for extensible storage adapters - Add built-in adapters for file, memory, S3, GCS, HTTPS schemes - Support pipe-chained URLs like s3://bucket/data.zip|zip:|zarr3: - Add URLSegment parsing with validation - Integrate with zarr.open_group and zarr.open_array APIs - Include demo script and comprehensive test suite - Pass all existing tests + 35 new ZEP 8-specific tests

…into feature/zep8-url-support

src/zarr/storage/_builtin_adapters.py

…into feature/zep8-url-support

jbms · 2025-09-11T16:40:50Z

One tricky thing about s3+https://endpoint/a/b is that it is ambiguous as to whether it is using "virtual host" syntax (i.e. endpoint refers to a single bucket and the path is "a/b") or "path" syntax (i.e. the bucket is "a" and the path is "b").

The "path" syntax is generally the default when running a regular s3-compatible server, but the "virtual host" syntax can commonly occur when someone defines a CNAME DNS entry to map their own domain or subdomain to an AWS S3 bucket.

When designing this syntax for Neuroglancer, it seemed like it would be annoying to require users to use separate syntax to disambiguate the two cases. Instead, for operations where it matters (namely List), Neuroglancer just automatically determines which of the two cases applies by trying both ways and seeing which one succeeds, and then caching the result so that subsequent list operations don't require two requests.

codecov · 2025-09-11T17:34:59Z

Codecov Report

❌ Patch coverage is 67.57246% with 179 lines in your changes missing coverage. Please review.
✅ Project coverage is 60.87%. Comparing base (ee9c182) to head (35526a5).
⚠️ Report is 42 commits behind head on main.

Files with missing lines	Patch %	Lines
src/zarr/storage/_builtin_adapters.py	58.36%	97 Missing ⚠️
src/zarr/storage/_zep8.py	83.95%	30 Missing ⚠️
src/zarr/abc/store_adapter.py	39.02%	25 Missing ⚠️
src/zarr/registry.py	60.00%	8 Missing ⚠️
src/zarr/storage/_zip.py	78.94%	8 Missing ⚠️
src/zarr/storage/_common.py	85.00%	3 Missing ⚠️
src/zarr/storage/_register_adapters.py	62.50%	3 Missing ⚠️
src/zarr/abc/__init__.py	0.00%	2 Missing ⚠️
src/zarr/api/asynchronous.py	0.00%	2 Missing ⚠️
src/zarr/storage/__init__.py	0.00%	1 Missing ⚠️

❗ There is a different number of reports uploaded between BASE (ee9c182) and HEAD (35526a5). Click for more details.

HEAD has 4 uploads less than BASE

Flag BASE (ee9c182) HEAD (35526a5)

14 10

Additional details and impacted files

@@             Coverage Diff             @@
##             main    #3369       +/-   ##
===========================================
- Coverage   94.92%   60.87%   -34.06%     
===========================================
  Files          79       86        +7     
  Lines        9500    10231      +731     
===========================================
- Hits         9018     6228     -2790     
- Misses        482     4003     +3521

Files with missing lines	Coverage Δ
src/zarr/storage/_logging.py	`61.94% <ø> (-38.06%)`	⬇️
src/zarr/storage/__init__.py	`9.52% <0.00%> (-85.48%)`	⬇️
src/zarr/abc/__init__.py	`0.00% <0.00%> (ø)`
src/zarr/api/asynchronous.py	`71.42% <0.00%> (-19.45%)`	⬇️
src/zarr/storage/_common.py	`68.57% <85.00%> (-21.96%)`	⬇️
src/zarr/storage/_register_adapters.py	`62.50% <62.50%> (ø)`
src/zarr/registry.py	`63.19% <60.00%> (-25.63%)`	⬇️
src/zarr/storage/_zip.py	`72.10% <78.94%> (-25.50%)`	⬇️
src/zarr/abc/store_adapter.py	`39.02% <39.02%> (ø)`
src/zarr/storage/_zep8.py	`83.95% <83.95%> (ø)`
... and 1 more

... and 64 files with indirect coverage changes

🚀 New features to boost your workflow:

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

laramiel · 2025-09-12T22:46:55Z

changes/3369.feature.rst

+Examples::
+
+    # Basic ZIP file storage
+    zarr.open_array("file:data.zip|zip", mode='w', shape=(10, 10), dtype="f4")


It seems like a bad idea to break file uris.

https://datatracker.ietf.org/doc/html/rfc8089

This is considered in the spec doc this PR is building on: zarr-developers/zeps#48

https://github.com/jbms/zeps/blob/92bc64111c7612083560358efdd4450e061f3746/draft/ZEP0008.md?plain=1#L115-L119

And later is says:

Implementations SHOULD not support `file://relative/path` since that is ambiguous with the `file://hostname/path` syntax defined by [RFC8089](https://datatracker.ietf.org/doc/html/rfc8089).

If you forsee serious issues here I'd encourage commenting on that PR on the standard.

ianhi

Partway through the code at this point (currently following the logic of store resolution). Posting some comments now so I don't lose them (i've been burned by this before)

ianhi · 2025-10-27T20:57:31Z

docs/user-guide/storage.rst

+**In-memory storage:**
+
+   >>> # Create array in memory
+   >>> z = zarr.open_array("memory:", mode='w', shape=(5, 5), dtype="f4")


Can I then access this from somewhere else using this syntax?

e.g. memory:aesr80s9e8ra?

ianhi · 2025-10-27T20:59:35Z

docs/user-guide/storage.rst

 .. warning::
   The :class:`zarr.storage.ObjectStore` class is experimental.

+URL-based Storage (ZEP 8)


I think what this section is missing is a showcasing of what the equivalent zarr-pyhthon code would be to put it in terms people are more familiar with.

So each section would be:

zarr.open_array("file:zep8-data.zip|zip" ....) # is equivalent to zarr.open_array(zarr.storage.ZipStore(...)...)

ianhi · 2025-10-27T21:01:21Z

docs/user-guide/storage.rst

+.. note::
+   When using ZEP 8 URLs with third-party libraries like xarray, the URL syntax allows
+   seamless integration without requiring zarr-specific store creation.


Suggested change

.. note::

When using ZEP 8 URLs with third-party libraries like xarray, the URL syntax allows

seamless integration without requiring zarr-specific store creation.

This is already effectively stated above.

ianhi · 2025-10-27T21:01:57Z

docs/quickstart.rst

+URL-based Storage (ZEP 8)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Zarr supports URL-based storage following the ZEP 8 specification, which allows you to specify storage locations using URLs with chained adapters::


Needs a link to the more extensive docs.

ianhi · 2025-10-27T21:02:23Z

docs/quickstart.rst

+
+- ``file:path.zip|zip`` - ZIP file on local filesystem
+- ``s3://bucket/data.zip|zip`` - ZIP file in S3 bucket
+- ``memory:`` - In-memory storage


Suggested change

- ``memory:`` - In-memory storage

not an example of piping

ianhi · 2025-10-27T21:21:38Z

src/zarr/storage/_builtin_adapters.py

+from zarr.abc.store_adapter import StoreAdapter
+from zarr.storage._local import LocalStore
+from zarr.storage._logging import LoggingStore
+from zarr.storage._memory import MemoryStore
+from zarr.storage._zep8 import URLStoreResolver
+from zarr.storage._zip import ZipStore


Is it worth considering makign these lazy, or not a big enough gain?

ianhi · 2025-10-27T21:33:53Z

src/zarr/storage/_zep8.py

+    >>> is_zep8_url("s3://bucket/data.zarr")
+    False
+    >>> is_zep8_url("file:///data.zarr")
+    False


I don't really follow these returning false. seems like a downgrade in functionality, also having looked a the spec a bit I don't see where this is explicitly disallowed (though very possible i misread or misunderstood)

ianhi · 2025-10-27T21:35:42Z

src/zarr/storage/_zep8.py

+        if not is_zep8_url(url):
+            # Check if it's a simple scheme URL that we can handle
+            if "://" in url or ((":" in url) and not url.startswith("/")):
+                # Parse as a single segment URL - the parser should handle this
+                try:
+                    segments = self.parser.parse(url)


Ahh I think this answers my question above. Since these are valid urls I think ideally is_zep8_url would handle these simple cases correctly.

ianhi · 2025-10-27T21:36:41Z

src/zarr/storage/_zep8.py

+                except Exception:
+                    raise ValueError(f"Not a valid URL: {url}") from None


What are the expected exception's we are catching here. As written this might silently quash an exception that is a real bug.

I think this whole section can be consolidated and simplified a bit, especially as we don't actually do anyhthing differently here then in the else branch that calls the same parse

ianhi · 2025-10-27T21:38:38Z

src/zarr/storage/_zep8.py

+        for i, segment in enumerate(segments):
+            if segment.adapter in ("zarr2", "zarr3"):
+                # Skip zarr format segments - they don't create stores
+                # TODO: these should propagate to the open call somehow


Calling out this TODO as importnat before merging

github-actions bot added the needs release notes Automatically applied to PRs which haven't added release notes label Aug 11, 2025

jhamman mentioned this pull request Aug 12, 2025

feature: implement zarr's zep8 adapter for icechunk earth-mover/icechunk#1161

Open

2 tasks

fixup

c5aefd3

rabernat mentioned this pull request Aug 15, 2025

icechunk to xarray using intake? intake/intake#874

Closed

jbusecke mentioned this pull request Aug 21, 2025

Possible Regression: 'Float32' object has no attribute 'value' raised when using zarr>3.0.10. #3396

Closed

rework remote adapter and add back zip adapter

26192cb

github-actions bot removed the needs release notes Automatically applied to PRs which haven't added release notes label Aug 24, 2025

jhamman added 4 commits August 25, 2025 12:12

add logging adapter

b67edcf

fix doc build

dc5acd3

Merge branch 'main' of https://github.com/zarr-developers/zarr-python …

227c214

…into feature/zep8-url-support

more test coverage

ebe9660

jsignell mentioned this pull request Aug 27, 2025

Add icechunk / virtualizarr NASA-IMPACT/pangeo-notebook-veda-image#42

Closed

martindurant reviewed Sep 3, 2025

View reviewed changes

src/zarr/storage/_builtin_adapters.py Outdated Show resolved Hide resolved

jbms reviewed Sep 3, 2025

View reviewed changes

src/zarr/storage/_builtin_adapters.py Show resolved Hide resolved

jbms reviewed Sep 3, 2025

View reviewed changes

src/zarr/storage/_builtin_adapters.py Show resolved Hide resolved

jhamman added 4 commits September 10, 2025 22:01

remove gcs scheme support

3b55281

add s3 compatible object store support with s3+https://...

c8941ba

Merge branch 'main' of https://github.com/zarr-developers/zarr-python …

2126a3b

…into feature/zep8-url-support

fix partial writes check in chained store

0cbeb72

skip for old fsspec versions

14c2817

jhamman added 6 commits September 11, 2025 13:47

windows fix

20a35f0

windows fix

7533d95

fixup + tests

542c3ec

fixup

4e8a925

fixup

0315e0b

fixup for win

5666478

jhamman marked this pull request as ready for review September 12, 2025 03:03

laramiel reviewed Sep 12, 2025

View reviewed changes

cleanup zep8 tests more

35526a5

ianhi reviewed Oct 27, 2025

View reviewed changes

	.. note::
	When using ZEP 8 URLs with third-party libraries like xarray, the URL syntax allows
	seamless integration without requiring zarr-specific store creation.

		except Exception:
		raise ValueError(f"Not a valid URL: {url}") from None

Uh oh!

Uh oh!

feat: Implement ZEP 8 URL syntax support for zarr-python #3369

Are you sure you want to change the base?

feat: Implement ZEP 8 URL syntax support for zarr-python #3369

Uh oh!

Conversation

jhamman commented Aug 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jbms commented Sep 11, 2025

Uh oh!

codecov bot commented Sep 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ianhi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

jhamman commented Aug 11, 2025 •

edited

Loading

codecov bot commented Sep 11, 2025 •

edited

Loading