merge

.gitignore

@@ -51,7 +51,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
-docs/_autoapi
+docs/api
 docs/data
 data
 data.zip

docs/Makefile

@@ -52,7 +52,7 @@ help:
 .PHONY: clean
 clean:
 	rm -rf $(BUILDDIR)/*
-	rm -rf $(BUILDDIR)/../_autoapi
+	rm -rf $(BUILDDIR)/../api
 
 .PHONY: html
 html:

docs/conf.py

@@ -57,7 +57,7 @@
 autoapi_add_toctree_entry = False
 autoapi_generate_api_docs = True
 autoapi_member_order = "groupwise"
-autoapi_root = "_autoapi"
+autoapi_root = "api"
 autoapi_keep_files = True
 autoapi_options = [ 'members', 'undoc-members', 'show-inheritance', 'show-module-summary', 'imported-members', ]
 
@@ -108,6 +108,7 @@ def skip_submodules(
      "release": "developers/release.html",
      "roadmap": "developers/roadmap.html",
      "installation": "user-guide/installation.html",
+     "api": "api/zarr/index"
 }
 
 # The language for content autogenerated by Sphinx. Refer to documentation

docs/index.rst

@@ -10,7 +10,7 @@ Zarr-Python
 
     quickstart
     user-guide/index
-    api/index
+    API reference <api/zarr/index>
     developers/index
     developers/release
     about
@@ -25,7 +25,7 @@ Zarr-Python
 
 Zarr-Python is a Python library for reading and writing Zarr groups and arrays. Highlights include:
 
-* Specification support for both Zarr v2 and v3.
+* Specification support for both Zarr format 2 and 3.
 * Create and read from N-dimensional arrays using NumPy-like semantics.
 * Flexible storage enables reading and writing from local, cloud and in-memory stores.
 * High performance: Enables fast I/O with support for asynchronous I/O and multi-threading.
@@ -81,12 +81,12 @@ Zarr-Python is a Python library for reading and writing Zarr groups and arrays.
 
         +++
 
-        .. button-ref:: api/index
+        .. button-ref:: api/zarr/index
             :expand:
             :color: dark
             :click-parent:
 
-            To the API reference guide
+            To the API reference
 
     .. grid-item-card::
         :img-top: _static/index_contribute.svg

docs/user-guide/arrays.rst

@@ -188,6 +188,7 @@ which can be used to print useful diagnostics, e.g.::
    Order              : C
    Read-only          : False
    Store type         : LocalStore
+   Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (BloscCodec(typesize=4, cname=<BloscCname.zstd: 'zstd'>, clevel=3, shuffle=<BloscShuffle.bitshuffle: 'bitshuffle'>, blocksize=0),)
    No. bytes          : 400000000 (381.5M)
@@ -204,6 +205,7 @@ prints additional diagnostics, e.g.::
    Order              : C
    Read-only          : False
    Store type         : LocalStore
+   Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (BloscCodec(typesize=4, cname=<BloscCname.zstd: 'zstd'>, clevel=3, shuffle=<BloscShuffle.bitshuffle: 'bitshuffle'>, blocksize=0),)
    No. bytes          : 400000000 (381.5M)
@@ -605,6 +607,7 @@ Sharded arrays can be created by providing the ``shards`` parameter to :func:`za
   Order              : C
   Read-only          : False
   Store type         : LocalStore
+  Filters            : ()
   Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
   Compressors        : (ZstdCodec(level=0, checksum=False),)
   No. bytes          : 100000000 (95.4M)

docs/user-guide/extending.rst

@@ -10,8 +10,8 @@ Custom codecs
 -------------
 
 .. note::
-    This section explains how custom codecs can be created for Zarr version 3 data. For Zarr
-    version 2, codecs should subclass the
+    This section explains how custom codecs can be created for Zarr format 3 arrays. For Zarr
+    format 2, codecs should subclass the
     `numcodecs.abc.Codec <https://numcodecs.readthedocs.io/en/stable/abc.html#numcodecs.abc.Codec>`_
     base class and register through
     `numcodecs.registry.register_codec <https://numcodecs.readthedocs.io/en/stable/registry.html#numcodecs.registry.register_codec>`_.
@@ -66,7 +66,7 @@ strongly recommended to prefix the codec identifier with a unique name. For exam
 the codecs from ``numcodecs`` are prefixed with ``numcodecs.``, e.g. ``numcodecs.delta``.
 
 .. note::
-    Note that the extension mechanism for the Zarr version 3 is still under development.
+    Note that the extension mechanism for the Zarr format 3 is still under development.
     Requirements for custom codecs including the choice of codec identifiers might
     change in the future.
 

docs/user-guide/groups.rst

@@ -109,6 +109,7 @@ property. E.g.::
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
+   Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 8000000 (7.6M)
@@ -124,6 +125,7 @@ property. E.g.::
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
+   Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 4000000 (3.8M)

docs/user-guide/performance.rst

@@ -98,6 +98,7 @@ To use sharding, you need to specify the ``shards`` parameter when creating the
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
+   Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 100000000000 (93.1G)
@@ -126,6 +127,7 @@ ratios, depending on the correlation structure within the data. E.g.::
    Order              : C
    Read-only          : False
    Store type         : MemoryStore
+   Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 400000000 (381.5M)
@@ -144,6 +146,7 @@ ratios, depending on the correlation structure within the data. E.g.::
    Order              : F
    Read-only          : False
    Store type         : MemoryStore
+   Filters            : ()
    Serializer         : BytesCodec(endian=<Endian.little: 'little'>)
    Compressors        : (ZstdCodec(level=0, checksum=False),)
    No. bytes          : 400000000 (381.5M)

docs/user-guide/v3_migration.rst

@@ -4,7 +4,7 @@
 Zarr-Python 3 represents a major refactor of the Zarr-Python codebase. Some of the
 goals motivating this refactor included:
 
-* adding support for the Zarr V3 specification (along with the Zarr V2 specification)
+* adding support for the Zarr format 3 specification (along with the Zarr format 2 specification)
 * cleaning up internal and user facing APIs
 * improving performance (particularly in high latency storage environments like
   cloud object stores)

pyproject.toml

@@ -380,7 +380,7 @@ filterwarnings = [
     "ignore:The loop argument is deprecated since Python 3.8.*:DeprecationWarning",
     "ignore:Creating a zarr.buffer.gpu.*:UserWarning",
     "ignore:Duplicate name:UserWarning",  # from ZipFile
-    "ignore:.*is currently not part in the Zarr version 3 specification.*:UserWarning",
+    "ignore:.*is currently not part in the Zarr format 3 specification.*:UserWarning",
 ]
 markers = [
     "gpu: mark a test as requiring CuPy and GPU"

src/zarr/api/asynchronous.py

@@ -198,7 +198,7 @@ async def consolidate_metadata(
 
     if any(m.zarr_format == 3 for m in members_metadata.values()):
         warnings.warn(
-            "Consolidated metadata is currently not part in the Zarr version 3 specification. It "
+            "Consolidated metadata is currently not part in the Zarr format 3 specification. It "
             "may not be supported by other zarr implementations and may change in the future.",
             category=UserWarning,
             stacklevel=1,
@@ -770,16 +770,16 @@ async def open_group(
         Whether to use consolidated metadata.
 
         By default, consolidated metadata is used if it's present in the
-        store (in the ``zarr.json`` for Zarr v3 and in the ``.zmetadata`` file
-        for Zarr v2).
+        store (in the ``zarr.json`` for Zarr format 3 and in the ``.zmetadata`` file
+        for Zarr format 2).
 
         To explicitly require consolidated metadata, set ``use_consolidated=True``,
         which will raise an exception if consolidated metadata is not found.
 
         To explicitly *not* use consolidated metadata, set ``use_consolidated=False``,
         which will fall back to using the regular, non consolidated metadata.
 
-        Zarr v2 allowed configuring the key storing the consolidated metadata
+        Zarr format 2 allowed configuring the key storing the consolidated metadata
         (``.zmetadata`` by default). Specify the custom key as ``use_consolidated``
         to load consolidated metadata from a non-default key.
 
@@ -870,21 +870,21 @@ async def create(
         Array shape.
     chunks : int or tuple of ints, optional
         The shape of the array's chunks.
-        V2 only. V3 arrays should use `chunk_shape` instead.
+        Zarr format 2 only. Zarr format 3 arrays should use `chunk_shape` instead.
         If not specified, default values are guessed based on the shape and dtype.
     dtype : str or dtype, optional
         NumPy dtype.
     chunk_shape : int or tuple of ints, optional
         The shape of the Array's chunks (default is None).
-        V3 only. V2 arrays should use `chunks` instead.
+        Zarr format 3 only. Zarr format 2 arrays should use `chunks` instead.
     chunk_key_encoding : ChunkKeyEncoding, optional
         A specification of how the chunk keys are represented in storage.
-        V3 only. V2 arrays should use `dimension_separator` instead.
+        Zarr format 3 only. Zarr format 2 arrays should use `dimension_separator` instead.
         Default is ``("default", "/")``.
     codecs : Sequence of Codecs or dicts, optional
         An iterable of Codec or dict serializations of Codecs. The elements of
         this collection specify the transformation from array values to stored bytes.
-        V3 only. V2 arrays should use ``filters`` and ``compressor`` instead.
+        Zarr format 3 only. Zarr format 2 arrays should use ``filters`` and ``compressor`` instead.
 
         If no codecs are provided, default codecs will be used:
 
@@ -896,7 +896,7 @@ async def create(
         ``array.v3_default_serializer`` and ``array.v3_default_compressors`` in :mod:`zarr.core.config`.
     compressor : Codec, optional
         Primary compressor to compress chunk data.
-        V2 only. V3 arrays should use ``codecs`` instead.
+        Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead.
 
         If neither ``compressor`` nor ``filters`` are provided, a default compressor will be used:
 
@@ -926,7 +926,7 @@ async def create(
         for storage of both chunks and metadata.
     filters : sequence of Codecs, optional
         Sequence of filters to use to encode chunk data prior to compression.
-        V2 only. If no ``filters`` are provided, a default set of filters will be used.
+        Zarr format 2 only. If no ``filters`` are provided, a default set of filters will be used.
         These defaults can be changed by modifying the value of ``array.v2_default_filters`` in :mod:`zarr.core.config`.
     cache_metadata : bool, optional
         If True, array configuration metadata will be cached for the
@@ -943,7 +943,7 @@ async def create(
         A codec to encode object arrays, only needed if dtype=object.
     dimension_separator : {'.', '/'}, optional
         Separator placed between the dimensions of a chunk.
-        V2 only. V3 arrays should use ``chunk_key_encoding`` instead.
+        Zarr format 2 only. Zarr format 3 arrays should use ``chunk_key_encoding`` instead.
         Default is ".".
     write_empty_chunks : bool, optional
         Deprecated in favor of the ``config`` keyword argument.

src/zarr/api/synchronous.py

@@ -502,16 +502,16 @@ def open_group(
         Whether to use consolidated metadata.
 
         By default, consolidated metadata is used if it's present in the
-        store (in the ``zarr.json`` for Zarr v3 and in the ``.zmetadata`` file
-        for Zarr v2).
+        store (in the ``zarr.json`` for Zarr format 3 and in the ``.zmetadata`` file
+        for Zarr format 2).
 
         To explicitly require consolidated metadata, set ``use_consolidated=True``,
         which will raise an exception if consolidated metadata is not found.
 
         To explicitly *not* use consolidated metadata, set ``use_consolidated=False``,
         which will fall back to using the regular, non consolidated metadata.
 
-        Zarr v2 allowed configuring the key storing the consolidated metadata
+        Zarr format 2 allows configuring the key storing the consolidated metadata
         (``.zmetadata`` by default). Specify the custom key as ``use_consolidated``
         to load consolidated metadata from a non-default key.
 
@@ -785,15 +785,15 @@ def create_array(
         Iterable of filters to apply to each chunk of the array, in order, before serializing that
         chunk to bytes.
 
-        For Zarr v3, a "filter" is a codec that takes an array and returns an array,
+        For Zarr format 3, a "filter" is a codec that takes an array and returns an array,
         and these values must be instances of ``ArrayArrayCodec``, or dict representations
         of ``ArrayArrayCodec``.
         If no ``filters`` are provided, a default set of filters will be used.
         These defaults can be changed by modifying the value of ``array.v3_default_filters``
         in :mod:`zarr.core.config`.
         Use ``None`` to omit default filters.
 
-        For Zarr v2, a "filter" can be any numcodecs codec; you should ensure that the
+        For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the
         the order if your filters is consistent with the behavior of each filter.
         If no ``filters`` are provided, a default set of filters will be used.
         These defaults can be changed by modifying the value of ``array.v2_default_filters``
@@ -803,32 +803,32 @@ def create_array(
         List of compressors to apply to the array. Compressors are applied in order, and after any
         filters are applied (if any are specified) and the data is serialized into bytes.
 
-        For Zarr v3, a "compressor" is a codec that takes a bytestrea, and
-        returns another bytestream. Multiple compressors my be provided for Zarr v3.
+        For Zarr format 3, a "compressor" is a codec that takes a bytestrea, and
+        returns another bytestream. Multiple compressors my be provided for Zarr format 3.
         If no ``compressors`` are provided, a default set of compressors will be used.
         These defaults can be changed by modifying the value of ``array.v3_default_compressors``
         in :mod:`zarr.core.config`.
         Use ``None`` to omit default compressors.
 
-        For Zarr v2, a "compressor" can be any numcodecs codec. Only a single compressor may
-        be provided for Zarr v2.
+        For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
+        be provided for Zarr format 2.
         If no ``compressor`` is provided, a default compressor will be used.
         in :mod:`zarr.core.config`.
         Use ``None`` to omit the default compressor.
     serializer : dict[str, JSON] | ArrayBytesCodec, optional
         Array-to-bytes codec to use for encoding the array data.
-        Zarr v3 only. Zarr v2 arrays use implicit array-to-bytes conversion.
+        Zarr format 3 only. Zarr format 2 arrays use implicit array-to-bytes conversion.
         If no ``serializer`` is provided, a default serializer will be used.
         These defaults can be changed by modifying the value of ``array.v3_default_serializer``
         in :mod:`zarr.core.config`.
     fill_value : Any, optional
         Fill value for the array.
     order : {"C", "F"}, optional
         The memory of the array (default is "C").
-        For Zarr v2, this parameter sets the memory order of the array.
-        For Zarr v3, this parameter is deprecated, because memory order
-        is a runtime parameter for Zarr v3 arrays. The recommended way to specify the memory
-        order for Zarr v3 arrays is via the ``config`` parameter, e.g. ``{'config': 'C'}``.
+        For Zarr format 2, this parameter sets the memory order of the array.
+        For Zarr format 3, this parameter is deprecated, because memory order
+        is a runtime parameter for Zarr format 3 arrays. The recommended way to specify the memory
+        order for Zarr format 3 arrays is via the ``config`` parameter, e.g. ``{'config': 'C'}``.
         If no ``order`` is provided, a default order will be used.
         This default can be changed by modifying the value of ``array.order`` in :mod:`zarr.core.config`.
     zarr_format : {2, 3}, optional
@@ -837,11 +837,11 @@ def create_array(
         Attributes for the array.
     chunk_key_encoding : ChunkKeyEncoding, optional
         A specification of how the chunk keys are represented in storage.
-        For Zarr v3, the default is ``{"name": "default", "separator": "/"}}``.
-        For Zarr v2, the default is ``{"name": "v2", "separator": "."}}``.
+        For Zarr format 3, the default is ``{"name": "default", "separator": "/"}}``.
+        For Zarr format 2, the default is ``{"name": "v2", "separator": "."}}``.
     dimension_names : Iterable[str], optional
         The names of the dimensions (default is None).
-        Zarr v3 only. Zarr v2 arrays should not use this parameter.
+        Zarr format 3 only. Zarr format 2 arrays should not use this parameter.
     storage_options : dict, optional
         If using an fsspec URL to create the store, these will be passed to the backend implementation.
         Ignored otherwise.

src/zarr/codecs/vlen_utf8.py

@@ -28,7 +28,7 @@
 class VLenUTF8Codec(ArrayBytesCodec):
     def __init__(self) -> None:
         warn(
-            "The codec `vlen-utf8` is currently not part in the Zarr version 3 specification. It "
+            "The codec `vlen-utf8` is currently not part in the Zarr format 3 specification. It "
             "may not be supported by other zarr implementations and may change in the future.",
             category=UserWarning,
             stacklevel=2,
@@ -83,7 +83,7 @@ def compute_encoded_size(self, input_byte_length: int, _chunk_spec: ArraySpec) -
 class VLenBytesCodec(ArrayBytesCodec):
     def __init__(self) -> None:
         warn(
-            "The codec `vlen-bytes` is currently not part in the Zarr version 3 specification. It "
+            "The codec `vlen-bytes` is currently not part in the Zarr format 3 specification. It "
             "may not be supported by other zarr implementations and may change in the future.",
             category=UserWarning,
             stacklevel=2,

src/zarr/core/_info.py

@@ -116,12 +116,12 @@ def __repr__(self) -> str:
             # for non-regular chunk grids
             kwargs["chunk_shape"] = "<variable>"
 
-        if len(self._filters) > 0:
-            template += "\nFilters            : {_filters}"
+        template += "\nFilters            : {_filters}"
+
         if self._serializer is not None:
             template += "\nSerializer         : {_serializer}"
-        if len(self._compressors) > 0:
-            template += "\nCompressors        : {_compressors}"
+
+        template += "\nCompressors        : {_compressors}"
 
         if self._count_bytes is not None:
             template += "\nNo. bytes          : {_count_bytes}"