chore: expunge deprecated zarr_version parameter (#3901)

* chore: expunge deprecated `zarr_version` parameter

- remove `zarr_version` from functions
- remove special function for handling `zarr_format` and `zarr_version` parameters
- correct references in the docs to `zarr_version`
- correct references in the docs to configuration for the default zarr format

* docs: changelog

Author: d-v-b

changes/3901.misc.md

@@ -0,0 +1 @@
+Remove the deprecated `zarr_version` parameter from several functions and methods. That parameter is replaced with `zarr_format`.

docs/user-guide/config.md

@@ -27,7 +27,7 @@ For more information, see the
 
 Configuration options include the following:
 
-- Default Zarr format `default_zarr_version`
+- Default Zarr format `default_zarr_format`
 - Default array order in memory `array.order`
 - Whether empty chunks are written to storage `array.write_empty_chunks`
 - Enable experimental rectilinear chunks `array.rectilinear_chunks`

docs/user-guide/v3_migration.md

@@ -97,7 +97,7 @@ The following sections provide details on breaking changes in Zarr-Python 3.
 
 2. Defaulting to `zarr_format=3` - newly created arrays will use the version 3 of the
    Zarr specification. To continue using version 2, set `zarr_format=2` when creating arrays
-   or set `default_zarr_version=2` in Zarr's runtime configuration.
+   or set `default_zarr_format=2` in Zarr's runtime configuration.
 
 3. Function signature change to [`zarr.Array.resize`][] - the `resize` function now takes a
    `zarr.core.common.ShapeLike` input rather than separate arguments for each dimension.
@@ -195,9 +195,9 @@ When installing using `pip`:
 
 ### Miscellaneous
 
-- The keyword argument `zarr_version` available in most creation functions in `zarr`
+- The keyword argument `zarr_version` in most creation functions in `zarr`
   (e.g. [`zarr.create`][], [`zarr.open`][], [`zarr.group`][], [`zarr.array`][]) has
-  been deprecated in favor of `zarr_format`.
+  been removed. Use `zarr_format` instead.
 
 ## 🚧 Work in Progress 🚧
 

src/zarr/api/asynchronous.py

@@ -169,22 +169,6 @@ def _like_args(a: ArrayLike) -> _LikeArgs:
     return new
 
 
-def _handle_zarr_version_or_format(
-    *, zarr_version: ZarrFormat | None, zarr_format: ZarrFormat | None
-) -> ZarrFormat | None:
-    """Handle the deprecated zarr_version kwarg and return zarr_format"""
-    if zarr_format is not None and zarr_version is not None and zarr_format != zarr_version:
-        raise ValueError(
-            f"zarr_format {zarr_format} does not match zarr_version {zarr_version}, please only set one"
-        )
-    if zarr_version is not None:
-        warnings.warn(
-            "zarr_version is deprecated, use zarr_format", ZarrDeprecationWarning, stacklevel=2
-        )
-        return zarr_version
-    return zarr_format
-
-
 async def consolidate_metadata(
     store: StoreLike,
     path: str | None = None,
@@ -289,7 +273,6 @@ async def load(
     store: StoreLike,
     path: str | None = None,
     zarr_format: ZarrFormat | None = None,
-    zarr_version: ZarrFormat | None = None,
 ) -> NDArrayLikeOrScalar | dict[str, NDArrayLikeOrScalar]:
     """Load data from an array or group into memory.
 
@@ -318,7 +301,6 @@ async def load(
     If loading data from a group of arrays, data will not be immediately loaded into
     memory. Rather, arrays will be loaded into memory as they are requested.
     """
-    zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
 
     obj = await open(store=store, path=path, zarr_format=zarr_format)
     if isinstance(obj, AsyncArray):
@@ -331,7 +313,6 @@ async def open(
     *,
     store: StoreLike | None = None,
     mode: AccessModeLiteral | None = None,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     storage_options: dict[str, Any] | None = None,
@@ -367,7 +348,7 @@ async def open(
     z : array or group
         Return type depends on what exists in the given store.
     """
-    zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
+
     if mode is None:
         if isinstance(store, (Store, StorePath)) and store.read_only:
             mode = "r"
@@ -418,7 +399,6 @@ async def open_consolidated(
 async def save(
     store: StoreLike,
     *args: NDArrayLike,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     **kwargs: Any,  # TODO: type kwargs as valid args to save
@@ -440,7 +420,6 @@ async def save(
     **kwargs
         NumPy arrays with data to save.
     """
-    zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
 
     if len(args) == 0 and len(kwargs) == 0:
         raise ValueError("at least one array must be provided")
@@ -454,7 +433,6 @@ async def save_array(
     store: StoreLike,
     arr: NDArrayLike,
     *,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     storage_options: dict[str, Any] | None = None,
@@ -482,10 +460,8 @@ async def save_array(
     **kwargs
         Passed through to [`create`][zarr.api.asynchronous.create], e.g., compressor.
     """
-    zarr_format = (
-        _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
-        or _default_zarr_format()
-    )
+    if zarr_format is None:
+        zarr_format = _default_zarr_format()
     if not isinstance(arr, NDArrayLike):
         raise TypeError("arr argument must be numpy or other NDArrayLike array")
 
@@ -512,7 +488,6 @@ async def save_array(
 async def save_group(
     store: StoreLike,
     *args: NDArrayLike,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     storage_options: dict[str, Any] | None = None,
@@ -542,13 +517,8 @@ async def save_group(
 
     store_path = await make_store_path(store, path=path, mode="w", storage_options=storage_options)
 
-    zarr_format = (
-        _handle_zarr_version_or_format(
-            zarr_version=zarr_version,
-            zarr_format=zarr_format,
-        )
-        or _default_zarr_format()
-    )
+    if zarr_format is None:
+        zarr_format = _default_zarr_format()
 
     for arg in args:
         if not isinstance(arg, NDArrayLike):
@@ -662,7 +632,6 @@ async def group(
     cache_attrs: bool | None = None,  # not used, default changed
     synchronizer: Any | None = None,  # not used
     path: str | None = None,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     meta_array: Any | None = None,  # not used
     attributes: dict[str, JSON] | None = None,
@@ -715,7 +684,6 @@ async def group(
         cache_attrs=cache_attrs,
         synchronizer=synchronizer,
         path=path,
-        zarr_version=zarr_version,
         zarr_format=zarr_format,
         meta_array=meta_array,
         attributes=attributes,
@@ -784,7 +752,6 @@ async def open_group(
     path: str | None = None,
     chunk_store: StoreLike | None = None,  # not used
     storage_options: dict[str, Any] | None = None,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     meta_array: Any | None = None,  # not used
     attributes: dict[str, JSON] | None = None,
@@ -846,8 +813,6 @@ async def open_group(
         The new group.
     """
 
-    zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
-
     if cache_attrs is not None:
         warnings.warn("cache_attrs is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
     if synchronizer is not None:
@@ -901,7 +866,6 @@ async def create(
     object_codec: Codec | None = None,  # TODO: type has changed
     dimension_separator: Literal[".", "/"] | None = None,
     write_empty_chunks: bool | None = None,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     meta_array: Any | None = None,  # TODO: need type
     attributes: dict[str, JSON] | None = None,
@@ -1043,10 +1007,8 @@ async def create(
     z : array
         The array.
     """
-    zarr_format = (
-        _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
-        or _default_zarr_format()
-    )
+    if zarr_format is None:
+        zarr_format = _default_zarr_format()
 
     if synchronizer is not None:
         warnings.warn("synchronizer is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
@@ -1238,7 +1200,6 @@ async def ones_like(a: ArrayLike, **kwargs: Any) -> AnyAsyncArray:
 async def open_array(
     *,  # note: this is a change from v2
     store: StoreLike | None = None,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: PathLike = "",
     storage_options: dict[str, Any] | None = None,
@@ -1252,8 +1213,6 @@ async def open_array(
         StoreLike object to open. See the
         [storage documentation in the user guide][user-guide-store-like]
         for a description of all valid StoreLike values.
-    zarr_version : {2, 3, None}, optional
-        The zarr format to use when saving. Deprecated in favor of zarr_format.
     zarr_format : {2, 3, None}, optional
         The zarr format to use when saving.
     path : str, optional
@@ -1273,8 +1232,6 @@ async def open_array(
     mode = kwargs.pop("mode", None)
     store_path = await make_store_path(store, path=path, mode=mode, storage_options=storage_options)
 
-    zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
-
     if "write_empty_chunks" in kwargs:
         _warn_write_empty_chunks_kwarg()
 

src/zarr/api/synchronous.py

@@ -140,7 +140,6 @@ def load(
     store: StoreLike,
     path: str | None = None,
     zarr_format: ZarrFormat | None = None,
-    zarr_version: ZarrFormat | None = None,
 ) -> NDArrayLikeOrScalar | dict[str, NDArrayLikeOrScalar]:
     """Load data from an array or group into memory.
 
@@ -169,16 +168,13 @@ def load(
     If loading data from a group of arrays, data will not be immediately loaded into
     memory. Rather, arrays will be loaded into memory as they are requested.
     """
-    return sync(
-        async_api.load(store=store, zarr_version=zarr_version, zarr_format=zarr_format, path=path)
-    )
+    return sync(async_api.load(store=store, zarr_format=zarr_format, path=path))
 
 
 def open(
     store: StoreLike | None = None,
     *,
     mode: AccessModeLiteral | None = None,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     storage_options: dict[str, Any] | None = None,
@@ -218,7 +214,6 @@ def open(
         async_api.open(
             store=store,
             mode=mode,
-            zarr_version=zarr_version,
             zarr_format=zarr_format,
             path=path,
             storage_options=storage_options,
@@ -243,7 +238,6 @@ def open_consolidated(*args: Any, use_consolidated: Literal[True] = True, **kwar
 def save(
     store: StoreLike,
     *args: NDArrayLike,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     **kwargs: Any,  # TODO: type kwargs as valid args to async_api.save
@@ -265,18 +259,13 @@ def save(
     **kwargs
         NumPy arrays with data to save.
     """
-    return sync(
-        async_api.save(
-            store, *args, zarr_version=zarr_version, zarr_format=zarr_format, path=path, **kwargs
-        )
-    )
+    return sync(async_api.save(store, *args, zarr_format=zarr_format, path=path, **kwargs))
 
 
 def save_array(
     store: StoreLike,
     arr: NDArrayLike,
     *,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     storage_options: dict[str, Any] | None = None,
@@ -309,7 +298,6 @@ def save_array(
         async_api.save_array(
             store=store,
             arr=arr,
-            zarr_version=zarr_version,
             zarr_format=zarr_format,
             path=path,
             storage_options=storage_options,
@@ -321,7 +309,6 @@ def save_array(
 def save_group(
     store: StoreLike,
     *args: NDArrayLike,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     path: str | None = None,
     storage_options: dict[str, Any] | None = None,
@@ -354,7 +341,6 @@ def save_group(
         async_api.save_group(
             store,
             *args,
-            zarr_version=zarr_version,
             zarr_format=zarr_format,
             path=path,
             storage_options=storage_options,
@@ -416,7 +402,6 @@ def group(
     cache_attrs: bool | None = None,  # not used, default changed
     synchronizer: Any | None = None,  # not used
     path: str | None = None,
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     meta_array: Any | None = None,  # not used
     attributes: dict[str, JSON] | None = None,
@@ -466,7 +451,6 @@ def group(
                 cache_attrs=cache_attrs,
                 synchronizer=synchronizer,
                 path=path,
-                zarr_version=zarr_version,
                 zarr_format=zarr_format,
                 meta_array=meta_array,
                 attributes=attributes,
@@ -485,7 +469,6 @@ def open_group(
     path: str | None = None,
     chunk_store: StoreLike | None = None,  # not used in async api
     storage_options: dict[str, Any] | None = None,  # not used in async api
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     meta_array: Any | None = None,  # not used in async api
     attributes: dict[str, JSON] | None = None,
@@ -556,7 +539,6 @@ def open_group(
                 path=path,
                 chunk_store=chunk_store,
                 storage_options=storage_options,
-                zarr_version=zarr_version,
                 zarr_format=zarr_format,
                 meta_array=meta_array,
                 attributes=attributes,
@@ -637,7 +619,6 @@ def create(
     object_codec: Codec | None = None,  # TODO: type has changed
     dimension_separator: Literal[".", "/"] | None = None,
     write_empty_chunks: bool | None = None,  # TODO: default has changed
-    zarr_version: ZarrFormat | None = None,  # deprecated
     zarr_format: ZarrFormat | None = None,
     meta_array: Any | None = None,  # TODO: need type
     attributes: dict[str, JSON] | None = None,
@@ -800,7 +781,6 @@ def create(
                 object_codec=object_codec,
                 dimension_separator=dimension_separator,
                 write_empty_chunks=write_empty_chunks,
-                zarr_version=zarr_version,
                 zarr_format=zarr_format,
                 meta_array=meta_array,
                 attributes=attributes,
@@ -1365,7 +1345,6 @@ def ones_like(a: ArrayLike, **kwargs: Any) -> AnyArray:
 def open_array(
     store: StoreLike | None = None,
     *,
-    zarr_version: ZarrFormat | None = None,
     zarr_format: ZarrFormat | None = None,
     path: PathLike = "",
     storage_options: dict[str, Any] | None = None,
@@ -1379,8 +1358,6 @@ def open_array(
         StoreLike object to open. See the
         [storage documentation in the user guide][user-guide-store-like]
         for a description of all valid StoreLike values.
-    zarr_version : {2, 3, None}, optional
-        The zarr format to use when saving. Deprecated in favor of zarr_format.
     zarr_format : {2, 3, None}, optional
         The zarr format to use when saving.
     path : str, optional
@@ -1401,7 +1378,6 @@ def open_array(
         sync(
             async_api.open_array(
                 store=store,
-                zarr_version=zarr_version,
                 zarr_format=zarr_format,
                 path=path,
                 storage_options=storage_options,

src/zarr/core/common.py

@@ -240,7 +240,7 @@ def _warn_order_kwarg() -> None:
 
 
 def _default_zarr_format() -> ZarrFormat:
-    """Return the default zarr_version"""
+    """Return the default zarr_format."""
     return cast("ZarrFormat", int(zarr_config.get("default_zarr_format", 3)))