feature: support zep8 strings when opening groups and arrays

Author: jhamman

examples/zep8_url_demo.py

@@ -0,0 +1,241 @@
+"""
+ZEP 8 URL Syntax Demo
+
+This script demonstrates ZEP 8 URL syntax for chained store access in zarr-python.
+ZEP 8 URLs allow you to chain different storage adapters using pipe (|) syntax.
+
+Examples of ZEP 8 URLs:
+    - "memory:" - Simple in-memory store
+    - "file:/path/data.zip|zip:" - ZIP file access
+    - "s3://bucket/data.zip|zip:|zarr3:" - Cloud ZIP with zarr3 format
+    - "file:/path/repo|icechunk:branch:main" - Icechunk repository (if available)
+
+For comprehensive Icechunk integration examples, see the icechunk repository tests.
+"""
+
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+import zarr
+from zarr.core.url_syntax import URLParser, is_zep8_url
+from zarr.registry import get_store_adapter
+from zarr.storage import ZipStore
+
+
+def demo_basic_zep8() -> None:
+    """Demonstrate basic ZEP 8 URL syntax features."""
+    print("=== Basic ZEP 8 URL Demo ===")
+
+    try:
+        print("📝 Testing basic ZEP 8 URL formats")
+
+        # Memory store
+        print("\n1. Memory store:")
+        memory_url = "memory:"
+        root = zarr.open_group(memory_url, mode="w")
+        arr = root.create_array("test_data", shape=(10,), dtype="f4")
+        arr[:] = np.random.random(10)
+        print(f"✅ Created array via {memory_url}")
+        print(f"   Data shape: {arr.shape}, dtype: {arr.dtype}")
+
+        # File store
+        print("\n2. File store:")
+        with tempfile.TemporaryDirectory() as tmpdir:
+            file_url = f"file:{tmpdir}/test.zarr"
+            root2 = zarr.open_group(file_url, mode="w")
+            arr2 = root2.create_array("persistent_data", shape=(20,), dtype="i4")
+            arr2[:] = range(20)
+            print(f"✅ Created array via {file_url}")
+            print(f"   Data: {list(arr2[:5])}... (first 5 elements)")
+
+    except Exception as e:
+        print(f"❌ Demo failed: {e}")
+
+
+def demo_zip_chaining() -> None:
+    """Demonstrate ZIP file chaining with ZEP 8 URLs."""
+    print("\n=== ZIP Chaining Demo ===")
+
+    try:
+        print("📝 Creating ZIP file with zarr data, then accessing via ZEP 8 URL")
+
+        with tempfile.TemporaryDirectory() as tmpdir:
+            zip_path = Path(tmpdir) / "data.zip"
+
+            # Step 1: Create ZIP file with zarr data
+            print(f"Creating ZIP file at: {zip_path}")
+            with ZipStore(str(zip_path), mode="w") as zip_store:
+                root = zarr.open_group(zip_store, mode="w")
+
+                # Create sample datasets
+                temps = root.create_array("temperatures", shape=(365,), dtype="f4")
+                temps[:] = (
+                    20 + 10 * np.sin(np.arange(365) * 2 * np.pi / 365) + np.random.normal(0, 2, 365)
+                )
+                temps.attrs["units"] = "celsius"
+                temps.attrs["description"] = "Daily temperature readings"
+
+                metadata = root.create_group("metadata")
+                info = metadata.create_array("info", shape=(1,), dtype="U50")
+                info[0] = "Weather data from ZIP demo"
+
+                print("✅ Created temperature data in ZIP file")
+                print(f"   Temperature range: {temps[:].min():.1f}°C to {temps[:].max():.1f}°C")
+
+            # Step 2: Access via ZEP 8 URL syntax
+            print("\nAccessing ZIP data via ZEP 8 URL")
+            zip_url = f"file:{zip_path}|zip:"
+            root_read = zarr.open_group(zip_url, mode="r")
+
+            temps_read = root_read["temperatures"]
+            info_read = root_read["metadata/info"]
+
+            print(f"✅ Successfully read via URL: {zip_url}")
+            print(f"   Temperature units: {temps_read.attrs['units']}")
+            print(f"   Description: {temps_read.attrs['description']}")
+            print(f"   Metadata: {info_read[0]}")
+            print(f"   Data integrity: {np.array_equal(temps[:], temps_read[:])}")
+
+    except ImportError as e:
+        print(f"❌ Required dependencies missing: {e}")
+    except Exception as e:
+        print(f"❌ Demo failed: {e}")
+
+
+def demo_adapter_registry() -> None:
+    """Show available store adapters and their usage."""
+    print("\n=== Store Adapter Registry Demo ===")
+
+    try:
+        print("📋 Testing common store adapters:")
+
+        # Test builtin adapters
+        builtin_adapters = ["memory", "file", "zip"]
+
+        for adapter_name in builtin_adapters:
+            try:
+                adapter_cls = get_store_adapter(adapter_name)
+                print(f"✅ {adapter_name}: {adapter_cls.__name__}")
+            except KeyError:
+                print(f"❌ {adapter_name}: Not registered")
+
+        # Test optional adapters
+        optional_adapters = ["icechunk", "ic", "s3", "gcs"]
+        print("\n📋 Testing optional adapters:")
+
+        for adapter_name in optional_adapters:
+            try:
+                adapter_cls = get_store_adapter(adapter_name)
+                print(f"✅ {adapter_name}: {adapter_cls.__name__}")
+            except KeyError:
+                print(f"i  {adapter_name}: Not available (requires additional packages)")
+
+    except Exception as e:
+        print(f"❌ Demo failed: {e}")
+
+
+def demo_url_parsing() -> None:
+    """Demonstrate ZEP 8 URL parsing and validation."""
+    print("\n=== URL Parsing Demo ===")
+
+    try:
+        parser = URLParser()
+
+        test_urls = [
+            "memory:",
+            "file:/tmp/data.zarr",
+            "file:/tmp/data.zip|zip:",
+            "s3://bucket/data.zip|zip:|zarr3:",
+            "memory:|icechunk:branch:main",  # This would be rejected by icechunk adapter
+            "/regular/file/path",  # Not a ZEP 8 URL
+        ]
+
+        print("📝 Testing URL parsing:")
+
+        for url in test_urls:
+            is_zep8 = is_zep8_url(url)
+            print(f"\n  URL: {url}")
+            print(f"  ZEP 8: {is_zep8}")
+
+            if is_zep8:
+                try:
+                    segments = parser.parse(url)
+                    print(f"  Segments: {len(segments)}")
+                    for i, seg in enumerate(segments):
+                        scheme_part = f"scheme={seg.scheme}" if seg.scheme else ""
+                        adapter_part = f"adapter={seg.adapter}" if seg.adapter else ""
+                        path_part = f"path='{seg.path}'" if seg.path else ""
+                        parts = [p for p in [scheme_part, adapter_part, path_part] if p]
+                        print(f"    {i}: {', '.join(parts)}")
+                except Exception as e:
+                    print(f"    Parse error: {e}")
+
+    except Exception as e:
+        print(f"❌ Demo failed: {e}")
+
+
+def demo_error_cases() -> None:
+    """Demonstrate common error cases and their handling."""
+    print("\n=== Error Handling Demo ===")
+
+    try:
+        print("🚫 Testing error cases:")
+
+        # Test 1: Invalid URL format
+        print("\n1. Invalid URL formats:")
+        invalid_urls = [
+            "|invalid:start",  # Starts with pipe
+            "memory:|",  # Ends with pipe
+            "memory:||zip:",  # Double pipe
+            "",  # Empty URL
+        ]
+
+        for url in invalid_urls:
+            try:
+                zarr.open_group(url, mode="r")
+                print(f"❌ Should have failed: {url}")
+            except Exception as e:
+                print(f"✅ Correctly rejected: {url} -> {type(e).__name__}")
+
+        # Test 2: Unknown adapters
+        print("\n2. Unknown adapters:")
+        try:
+            zarr.open_group("memory:|unknown_adapter:", mode="r")
+            print("❌ Should have failed: unknown adapter")
+        except Exception as e:
+            print(f"✅ Correctly rejected unknown adapter -> {type(e).__name__}")
+
+        # Test 3: Fallback behavior
+        print("\n3. Fallback to regular stores:")
+        regular_urls = ["memory:", f"file:{tempfile.mkdtemp()}/fallback.zarr"]
+
+        for url in regular_urls:
+            try:
+                root = zarr.open_group(url, mode="w")
+                arr = root.create_array("data", shape=(5,), dtype="i4")
+                arr[:] = [1, 2, 3, 4, 5]
+                print(f"✅ Fallback works: {url}")
+            except Exception as e:
+                print(f"❌ Fallback failed: {url} -> {e}")
+
+    except Exception as e:
+        print(f"❌ Demo failed: {e}")
+
+
+if __name__ == "__main__":
+    print("ZEP 8 URL Syntax Demo")
+    print("=" * 30)
+
+    demo_basic_zep8()
+    demo_zip_chaining()
+    demo_adapter_registry()
+    demo_url_parsing()
+    demo_error_cases()
+
+    print("\n" + "=" * 30)
+    print("Demo completed!")
+    print("\nZEP 8 URL syntax enables flexible chaining of storage adapters.")
+    print("For adapter-specific examples (like Icechunk), see the respective")
+    print("package repositories and their test suites.")

pyproject.toml

@@ -428,3 +428,12 @@ ignore-words-list = "astroid"
 
 [project.entry-points.pytest11]
 zarr = "zarr.testing"
+
+[project.entry-points."zarr.stores"]
+file = "zarr.storage.builtin_adapters:FileSystemAdapter"
+memory = "zarr.storage.builtin_adapters:MemoryAdapter"
+https = "zarr.storage.builtin_adapters:HttpsAdapter"
+s3 = "zarr.storage.builtin_adapters:S3Adapter"
+gcs = "zarr.storage.builtin_adapters:GCSAdapter"
+gs = "zarr.storage.builtin_adapters:GSAdapter"
+zip = "zarr.storage._zip:ZipStoreAdapter"