Remove deprecated API

changes/3325.removal.rst

@@ -0,0 +1,33 @@
+The deprecated ``zarr.convenience`` sub-module has been removed.
+All functions are available in the top-level `zarr` namespace.
+
+The following deprecated methods have been removed:
+
+- ``AsyncArray.create`` - use `zarr.api.asynchronous.create_array` instead.
+- ``Array.create`` - use `zarr.create_array` instead.
+
+The ``codecs`` argument on the removed methods corresponds to a combination of the ``compressors`` and ``serializer`` arguments on their replacements,
+and the ``chunk_shape`` argument on the removed methods corresponds to the ``chunks`` argument on their replacements.
+
+The following deprecated properties have been removed:
+
+- ``AsyncArray.compressor`` - use ``AsyncArray.compressors[0]`` instead for Zarr format 2 arrays.
+- ``Array.compressor`` - use ``Array.compressors[0]`` instead for Zarr format 2 arrays.
+- ``AsyncGroup.create_dataset`` - use `AsyncGroup.create_array` instead
+- ``AsyncGroup.require_dataset`` - use `AsyncGroup.require_array` instead
+- ``Group.create_dataset`` - use `Group.create_array` instead
+- ``Group.require_dataset`` - use `Group.require_array` instead
+- ``Group.array`` - use `Group.create_array` instead
+
+The following deprecated functions have been removed:
+
+- ``zarr.api.asynchronous.tree`` - use `AsyncGroup.tree` instead
+- ``zarr.api.synchronous.tree`` - use `Group.tree` instead
+- ``zarr.tree`` - use `Group.tree` instead
+
+
+Setting ``zarr.storage.default_compressor`` is deprecated, use `zarr.config` to configure ``array.v2_default_compressor``
+e.g. ``zarr.config.set({'codecs.zstd':'numcodecs.Zstd', 'array.v2_default_compressor.numeric': 'zstd'})``
+
+The ``zarr_version`` argument has been removed throughout the library.
+Use the equivalent ``zarr_format`` argument instead.

docs/user-guide/config.rst

@@ -26,7 +26,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``
 - Default filters, serializers and compressors, e.g. ``array.v3_default_filters``, ``array.v3_default_serializer``, ``array.v3_default_compressors``, ``array.v2_default_filters`` and ``array.v2_default_compressor``
 - Whether empty chunks are written to storage ``array.write_empty_chunks``

docs/user-guide/v3_migration.rst

@@ -105,7 +105,7 @@ The Array class
 
 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 :ref:`runtime configuration <user-guide-config>`.
+   or set ``default_zarr_format=2`` in Zarr's :ref:`runtime configuration <user-guide-config>`.
 
 The Group class
 ~~~~~~~~~~~~~~~
@@ -207,7 +207,7 @@ Miscellaneous
 
 - The keyword argument ``zarr_version`` available in most creation functions in :mod:`zarr`
   (e.g. :func:`zarr.create`, :func:`zarr.open`, :func:`zarr.group`, :func:`zarr.array`) has
-  been deprecated in favor of ``zarr_format``.
+  been removed in favor of ``zarr_format``.
 
 🚧 Work in Progress 🚧
 ----------------------

src/zarr/__init__.py

@@ -26,7 +26,6 @@
     save,
     save_array,
     save_group,
-    tree,
     zeros,
     zeros_like,
 )
@@ -119,7 +118,6 @@ def print_packages(packages: list[str]) -> None:
     "save",
     "save_array",
     "save_group",
-    "tree",
     "zeros",
     "zeros_like",
 ]

src/zarr/api/asynchronous.py

@@ -7,7 +7,6 @@
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import deprecated
 
 from zarr.abc.store import Store
 from zarr.core.array import (
@@ -42,7 +41,6 @@
 from zarr.errors import (
     GroupNotFoundError,
     NodeTypeValidationError,
-    ZarrDeprecationWarning,
     ZarrRuntimeWarning,
     ZarrUserWarning,
 )
@@ -89,7 +87,6 @@
     "save",
     "save_array",
     "save_group",
-    "tree",
     "zeros",
     "zeros_like",
 ]
@@ -158,22 +155,6 @@ def _like_args(a: ArrayLike, kwargs: dict[str, Any]) -> dict[str, Any]:
     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,
@@ -267,7 +248,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.
 
@@ -294,8 +274,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):
         return await obj.getitem(slice(None))
@@ -307,7 +285,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,
@@ -341,7 +318,6 @@ 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"
@@ -390,7 +366,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
@@ -410,7 +385,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")
@@ -424,7 +398,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,
@@ -449,10 +422,7 @@ async def save_array(
     **kwargs
         Passed through to :func:`create`, e.g., compressor.
     """
-    zarr_format = (
-        _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
-        or _default_zarr_format()
-    )
+    zarr_format = zarr_format or _default_zarr_format()
     if not isinstance(arr, NDArrayLike):
         raise TypeError("arr argument must be numpy or other NDArrayLike array")
 
@@ -479,7 +449,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,
@@ -507,13 +476,7 @@ 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()
-    )
+    zarr_format = zarr_format or _default_zarr_format()
 
     for arg in args:
         if not isinstance(arg, NDArrayLike):
@@ -542,31 +505,6 @@ async def save_group(
     await asyncio.gather(*aws)
 
 
-@deprecated("Use AsyncGroup.tree instead.", category=ZarrDeprecationWarning)
-async def tree(grp: AsyncGroup, expand: bool | None = None, level: int | None = None) -> Any:
-    """Provide a rich display of the hierarchy.
-
-    .. deprecated:: 3.0.0
-        `zarr.tree()` is deprecated and will be removed in a future release.
-        Use `group.tree()` instead.
-
-    Parameters
-    ----------
-    grp : Group
-        Zarr or h5py group.
-    expand : bool, optional
-        Only relevant for HTML representation. If True, tree will be fully expanded.
-    level : int, optional
-        Maximum depth to descend into hierarchy.
-
-    Returns
-    -------
-    TreeRepr
-        A pretty-printable object displaying the hierarchy.
-    """
-    return await grp.tree(expand=expand, level=level)
-
-
 async def array(
     data: npt.ArrayLike | Array, **kwargs: Any
 ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
@@ -629,7 +567,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,
@@ -670,8 +607,6 @@ async def group(
         The new group.
     """
 
-    zarr_format = _handle_zarr_version_or_format(zarr_version=zarr_version, zarr_format=zarr_format)
-
     mode: AccessModeLiteral
     if overwrite:
         mode = "w"
@@ -762,7 +697,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,
@@ -830,8 +764,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:
@@ -884,7 +816,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,
@@ -1011,10 +942,7 @@ 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()
-    )
+    zarr_format = zarr_format or _default_zarr_format()
 
     if synchronizer is not None:
         warnings.warn("synchronizer is not yet implemented", ZarrRuntimeWarning, stacklevel=2)
@@ -1217,7 +1145,6 @@ async def ones_like(
 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,
@@ -1229,8 +1156,6 @@ async def open_array(
     ----------
     store : Store or str
         Store or path to directory in file system or name of zip file.
-    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
@@ -1250,8 +1175,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()