Raise informative error on Zarr V2 parsing with Zarr-Python<3.1.3 (#829)

* Add back supports_partial_writes property, returning False

* Raise informative error if using Zarr V2 parser with Zarr-Python<3.1.3

* Add test

* Reduce code duplication

Author: maxrjones

virtualizarr/parsers/zarr.py

@@ -180,7 +180,14 @@ async def get_chunk_mapping(
     def get_metadata(self, zarr_array: ZarrArrayType) -> ArrayV3Metadata:
         """Convert V2 metadata to V3 format."""
         from zarr.core.metadata import ArrayV2Metadata
-        from zarr.metadata.migrate_v3 import _convert_array_metadata
+
+        try:
+            from zarr.metadata.migrate_v3 import _convert_array_metadata
+        except (ImportError, AttributeError):
+            raise ImportError(
+                f"Zarr-Python>=3.1.3 is required for parsing Zarr V2 into Zarr V3. "
+                f"Found Zarr version '{zarr.__version__}'"
+            )
 
         v2_metadata = zarr_array.metadata
         assert isinstance(v2_metadata, ArrayV2Metadata)

virtualizarr/tests/test_parsers/test_zarr.py

@@ -3,6 +3,7 @@
 import xarray as xr
 import zarr
 from obstore.store import LocalStore
+from packaging import version
 from zarr.api.asynchronous import open_array
 
 from virtualizarr import open_virtual_dataset
@@ -13,18 +14,36 @@
 
 ZarrArrayType = zarr.AsyncArray | zarr.Array
 
+SKIP_OLDER_ZARR_PYTHON = pytest.mark.skipif(
+    version.parse(zarr.__version__) < version.parse("3.1.3"),
+    reason="Zarr V2 requires zarr>=3.1.3",
+)
 
-@pytest.mark.parametrize(
-    "zarr_store",
-    [
-        pytest.param(
-            2,
-            id="Zarr V2",
-        ),
-        pytest.param(3, id="Zarr V3"),
-    ],
-    indirect=True,
+SKIP_NEWER_ZARR_PYTHON = pytest.mark.skipif(
+    version.parse(zarr.__version__) >= version.parse("3.1.3"),
+    reason="Test only relevant for zarr<3.1.3",
 )
+
+
+def zarr_versions(param_name="zarr_format", indirect=False):
+    """
+    Reusable parametrize decorator for Zarr V2 and V3 versions.
+
+    Args:
+        param_name: Name of the parameter ('zarr_format' or 'zarr_store')
+        indirect: Whether to use indirect parametrization (True for fixtures)
+    """
+    return pytest.mark.parametrize(
+        param_name,
+        [
+            pytest.param(2, id="Zarr V2", marks=SKIP_OLDER_ZARR_PYTHON),
+            pytest.param(3, id="Zarr V3"),
+        ],
+        indirect=indirect,
+    )
+
+
+@zarr_versions(param_name="zarr_store", indirect=True)
 class TestOpenVirtualDatasetZarr:
     def test_loadable_variables(self, zarr_store, loadable_variables=["time", "air"]):
         # check loadable variables
@@ -106,7 +125,7 @@ def test_virtual_dataset_zarr_attrs(self, zarr_store):
                     assert list(expected["dimension_names"]) == list(vds[array].dims)
 
 
-@pytest.mark.parametrize("zarr_format", [2, 3])
+@zarr_versions()
 def test_scalar_chunk_mapping(tmpdir, zarr_format):
     """Test that scalar arrays produce correct chunk mappings for both V2 and V3."""
     import asyncio
@@ -153,7 +172,7 @@ def test_unsupported_zarr_format():
         get_strategy(mock_array)
 
 
-@pytest.mark.parametrize("zarr_format", [2, 3])
+@zarr_versions()
 def test_empty_array_chunk_mapping(tmpdir, zarr_format):
     """Test chunk mapping for arrays with no chunks written yet."""
     import asyncio
@@ -178,6 +197,7 @@ async def get_chunk_map():
     assert chunk_map == {}
 
 
+@SKIP_OLDER_ZARR_PYTHON
 def test_v2_metadata_without_dimensions():
     """Test V2 metadata conversion when array has no _ARRAY_DIMENSIONS attribute."""
     import asyncio
@@ -199,6 +219,30 @@ async def get_meta():
     assert len(metadata.dimension_names) == 2
 
 
+@SKIP_NEWER_ZARR_PYTHON
+def test_v2_metadata_raises_import_error_on_old_zarr():
+    """Test that V2 metadata conversion raises ImportError with zarr<3.1.3."""
+    import asyncio
+
+    # Create a V2 array without dimension attributes
+    store = zarr.storage.MemoryStore()
+    _ = zarr.create(
+        shape=(5, 10), chunks=(5, 5), dtype="int32", store=store, zarr_format=2
+    )
+
+    async def get_meta():
+        zarr_array = await open_array(store=store, mode="r")
+        return get_metadata(zarr_array)
+
+    # Should raise ImportError with helpful message
+    with pytest.raises(
+        ImportError,
+        match=r"Zarr-Python>=3\.1\.3 is required for parsing Zarr V2 into Zarr V3.*Found Zarr version",
+    ):
+        asyncio.run(get_meta())
+
+
+@SKIP_OLDER_ZARR_PYTHON
 def test_v2_metadata_with_dimensions():
     """Test V2 metadata conversion when array has _ARRAY_DIMENSIONS attribute."""
     import asyncio
@@ -219,6 +263,7 @@ async def get_meta():
     assert metadata.dimension_names == ("x", "y")
 
 
+@SKIP_OLDER_ZARR_PYTHON
 def test_v2_metadata_with_none_fill_value():
     """Test V2 metadata conversion when fill_value is None."""
     import asyncio
@@ -260,7 +305,7 @@ async def get_manifest():
     assert manifest.shape_chunk_grid == (2, 2)  # 10/5 = 2 chunks per dimension
 
 
-@pytest.mark.parametrize("zarr_format", [2, 3])
+@zarr_versions()
 def test_sparse_array_with_missing_chunks(tmpdir, zarr_format):
     """Test that arrays with some missing chunks (sparse arrays) are handled correctly.
 
@@ -317,7 +362,7 @@ async def get_manifest():
     assert manifest.shape_chunk_grid == (3, 3), "Chunk grid should be 3x3"
 
 
-@pytest.mark.parametrize("zarr_format", [2, 3])
+@zarr_versions()
 def test_parser_roundtrip_matches_xarray(tmpdir, zarr_format):
     """Roundtrip a small dataset through the ZarrParser and compare with xarray."""
     import numpy as _np