From b840c5cf89860478e42c7dee9a78d065a7fc4f6f Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Tue, 19 Aug 2025 23:01:59 +0200 Subject: [PATCH 01/23] make docs more consistent, and remove outdated references to configuration values that no longer work --- docs/user-guide/config.rst | 1 - pyproject.toml | 1 + src/zarr/api/asynchronous.py | 98 +++++++++++-------- src/zarr/api/synchronous.py | 125 ++++++++++++++++------- src/zarr/core/array.py | 185 +++++++++++++++++------------------ src/zarr/core/group.py | 69 ++++++------- 6 files changed, 274 insertions(+), 205 deletions(-) diff --git a/docs/user-guide/config.rst b/docs/user-guide/config.rst index 0ae8017ca9..681f3a1ca6 100644 --- a/docs/user-guide/config.rst +++ b/docs/user-guide/config.rst @@ -28,7 +28,6 @@ Configuration options include the following: - Default Zarr format ``default_zarr_version`` - 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`` - Async and threading options, e.g. ``async.concurrency`` and ``threading.max_workers`` - Selections of implementations of codecs, codec pipelines and buffers diff --git a/pyproject.toml b/pyproject.toml index 5a1d60485d..cafce5ec66 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -78,6 +78,7 @@ test = [ "pytest-accept", "rich", "mypy", + 'numpydoc', "hypothesis", "pytest-xdist", "packaging", diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index d3613f7c05..5692da2d59 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -328,8 +328,8 @@ async def open( path : str or None, optional The path within the store to open. storage_options : dict - If the store is backed by an fsspec-based implementation, then this dict will be passed to - the Store constructor for that implementation. Ignored otherwise. + If using an fsspec URL to create the store, these will be passed to + the backend implementation. Ignored otherwise. **kwargs Additional parameters are passed through to :func:`zarr.creation.open_array` or :func:`zarr.hierarchy.open_group`. @@ -440,7 +440,8 @@ async def save_array( arr : ndarray NumPy array with data to save. zarr_format : {2, 3, None}, optional - The zarr format to use when saving (default is 3 if not specified). + The zarr format to use when saving. The default is ``None``, which will + use the default Zarr format defined in the global configuration object. path : str or None, optional The path within the store where the array will be saved. storage_options : dict @@ -909,42 +910,20 @@ async def create( shape : int or tuple of ints Array shape. chunks : int or tuple of ints, optional - The shape of the array's chunks. - 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. + Chunk shape. If True, will be guessed from `shape` and `dtype`. If + False, will be set to `shape`, i.e., single chunk for the whole array. + If an int, the chunk size in each dimension will be given by the value + of `chunks`. Default is True. 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). - 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. - 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. - Zarr format 3 only. Zarr format 2 arrays should use ``filters`` and ``compressor`` instead. - - If no codecs are provided, default codecs will be used: - - - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``. - - For Unicode strings, the default is ``VLenUTF8Codec`` and ``ZstdCodec``. - - For bytes or objects, the default is ``VLenBytesCodec`` and ``ZstdCodec``. - - These defaults can be changed by modifying the value of ``array.v3_default_filters``, - ``array.v3_default_serializer`` and ``array.v3_default_compressors`` in :mod:`zarr.core.config`. compressor : Codec, optional Primary compressor to compress chunk data. 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: - - - For numeric arrays, the default is ``ZstdCodec``. - - For Unicode strings, the default is ``VLenUTF8Codec``. - - For bytes or objects, the default is ``VLenBytesCodec``. + If neither ``compressor`` nor ``filters`` are provided, the default compressor + :class:`zarr.codecs.ZstdCodec`is used. - These defaults can be changed by modifying the value of ``array.v2_default_compressor`` in :mod:`zarr.core.config`. + If ``compressor`` is set to ``None``, no compression is used. fill_value : object Default value to use for uninitialized portions of the array. order : {'C', 'F'}, optional @@ -964,10 +943,25 @@ async def create( chunk_store : MutableMapping, optional Separate storage for chunks. If not provided, `store` will be used for storage of both chunks and metadata. - filters : sequence of Codecs, optional - Sequence of filters to use to encode chunk data prior to compression. - 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`. + filters : Iterable[Codec] | Literal["auto"], optional + Iterable of filters to apply to each chunk of the array, in order, before serializing that + chunk to bytes. + + For Zarr format 3, a "filter" is a codec that takes an array and returns an array, + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. + + 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. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. cache_metadata : bool, optional If True, array configuration metadata will be cached for the lifetime of the object. If False, array metadata will be reloaded @@ -984,7 +978,6 @@ async def create( dimension_separator : {'.', '/'}, optional Separator placed between the dimensions of a chunk. 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. Pass ``{'write_empty_chunks': }`` to ``create`` instead of using this parameter. @@ -994,15 +987,36 @@ async def create( that chunk is not be stored, and the store entry for that chunk's key is deleted. zarr_format : {2, 3, None}, optional - The zarr format to use when saving. - Default is 3. + The Zarr format to use when creating an array. The default is ``None``, + which instructs Zarr to choose the default Zarr format value defined in the + runtime configuration. meta_array : array-like, optional - An array instance to use for determining arrays to create and return - to users. Use `numpy.empty(())` by default. + Not implemented. + attributes : dict[str, JSON], optional + A dictionary of user attributes to store with the array. + chunk_shape : int or tuple of ints, optional + The shape of the Array's chunks (default is None). + 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. + 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. Zarr V3 only. + + The elements of ``codecs`` specify the transformation from array values to stored bytes. + Zarr format 3 only. Zarr format 2 arrays should use ``filters`` and ``compressor`` instead. + + If no codecs are provided, default codecs will be used based on the data type of the array. + For most data types, the default codecs are the tuple ``(BytesCodec(), ZstdCodec())``; + data types that require a special :class:`zarr.abc.codec.ArrayBytesCodec`, like variable-length strings or bytes, + will use the :class:`zarr.abc.codec.ArrayBytesCodec` required for the data type instead of :class:`zarr.codecs.BytesCodec`. + dimension_names : Iterable[str | None] | None = None + An iterable of dimension names. Zarr format 3 only. storage_options : dict If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise. - config : ArrayConfig or ArrayConfigLike, optional + config : ArrayConfig | ArrayConfigLike, optional Runtime configuration of the array. If provided, will override the default values from `zarr.config.array`. diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index 1146a6876f..62e6a47147 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -189,8 +189,8 @@ def open( If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise. **kwargs - Additional parameters are passed through to :func:`zarr.api.asynchronous.open_array` or - :func:`zarr.api.asynchronous.open_group`. + Additional parameters are passed through to :func:`zarr.creation.open_array` or + :func:`zarr.hierarchy.open_group`. Returns ------- @@ -274,7 +274,8 @@ def save_array( arr : ndarray NumPy array with data to save. zarr_format : {2, 3, None}, optional - The zarr format to use when saving. + The zarr format to use when saving. The default is ``None``, which will + use the default Zarr format defined in the global configuration object. path : str or None, optional The path within the store where the array will be saved. storage_options : dict @@ -518,7 +519,7 @@ def open_group( To explicitly *not* use consolidated metadata, set ``use_consolidated=False``, which will fall back to using the regular, non consolidated metadata. - Zarr format 2 allows 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. @@ -648,7 +649,13 @@ def create( dtype : str or dtype, optional NumPy dtype. compressor : Codec, optional - Primary compressor. + Primary compressor to compress chunk data. + Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. + + If neither ``compressor`` nor ``filters`` are provided, the default compressor + :class:`zarr.codecs.ZstdCodec`is used. + + If ``compressor`` is set to ``None``, no compression is used. fill_value : object Default value to use for uninitialized portions of the array. order : {'C', 'F'}, optional @@ -668,8 +675,25 @@ def create( chunk_store : MutableMapping, optional Separate storage for chunks. If not provided, `store` will be used for storage of both chunks and metadata. - filters : sequence of Codecs, optional - Sequence of filters to use to encode chunk data prior to compression. + filters : Iterable[Codec] | Literal["auto"], optional + Iterable of filters to apply to each chunk of the array, in order, before serializing that + chunk to bytes. + + For Zarr format 3, a "filter" is a codec that takes an array and returns an array, + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. + + 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. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. cache_metadata : bool, optional If True, array configuration metadata will be cached for the lifetime of the object. If False, array metadata will be reloaded @@ -685,6 +709,7 @@ def create( A codec to encode object arrays, only needed if dtype=object. dimension_separator : {'.', '/'}, optional Separator placed between the dimensions of a chunk. + Zarr format 2 only. Zarr format 3 arrays should use ``chunk_key_encoding`` instead. write_empty_chunks : bool, optional Deprecated in favor of the ``config`` keyword argument. Pass ``{'write_empty_chunks': }`` to ``create`` instead of using this parameter. @@ -694,14 +719,36 @@ def create( that chunk is not be stored, and the store entry for that chunk's key is deleted. zarr_format : {2, 3, None}, optional - The zarr format to use when saving. + The Zarr format to use when creating an array. The default is ``None``, + which instructs Zarr to choose the default Zarr format value defined in the + runtime configuration. meta_array : array-like, optional - An array instance to use for determining arrays to create and return - to users. Use `numpy.empty(())` by default. + Not implemented. + attributes : dict[str, JSON], optional + A dictionary of user attributes to store with the array. + chunk_shape : int or tuple of ints, optional + The shape of the Array's chunks (default is None). + 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. + 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. Zarr V3 only. + + The elements of ``codecs`` specify the transformation from array values to stored bytes. + Zarr format 3 only. Zarr format 2 arrays should use ``filters`` and ``compressor`` instead. + + If no codecs are provided, default codecs will be used based on the data type of the array. + For most data types, the default codecs are the tuple ``(BytesCodec(), ZstdCodec())``; + data types that require a special :class:`zarr.abc.codec.ArrayBytesCodec`, like variable-length strings or bytes, + will use the :class:`zarr.abc.codec.ArrayBytesCodec` required for the data type instead of :class:`zarr.codecs.BytesCodec`. + dimension_names : Iterable[str | None] | None = None + An iterable of dimension names. Zarr format 3 only. storage_options : dict If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise. - config : ArrayConfigLike, optional + config : ArrayConfig | ArrayConfigLike, optional Runtime configuration of the array. If provided, will override the default values from `zarr.config.array`. @@ -783,7 +830,7 @@ def create_array( at the root of the store. shape : ShapeLike, optional Shape of the array. Must be ``None`` if ``data`` is provided. - dtype : ZDTypeLike, optional + dtype : ZDTypeLike | None Data type of the array. Must be ``None`` if ``data`` is provided. data : np.ndarray, optional Array-like data to use for initializing the array. If this parameter is provided, the @@ -793,24 +840,25 @@ def create_array( If not specified, default are guessed based on the shape and dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. - filters : Iterable[Codec], optional + filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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`` - in :mod:`zarr.core.config`. - Use ``None`` to omit default filters. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. compressors : Iterable[Codec], optional 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. @@ -847,7 +895,7 @@ def create_array( The zarr format to use when saving. attributes : dict, optional Attributes for the array. - chunk_key_encoding : ChunkKeyEncoding, optional + chunk_key_encoding : ChunkKeyEncodingLike, optional A specification of how the chunk keys are represented in storage. For Zarr format 3, the default is ``{"name": "default", "separator": "/"}}``. For Zarr format 2, the default is ``{"name": "v2", "separator": "."}}``. @@ -968,24 +1016,27 @@ def from_array( - None: No sharding. If not specified, defaults to "keep" if data is a zarr Array, otherwise None. - filters : Iterable[Codec] or "auto" or "keep", optional + filters : Iterable[Codec] | Literal["auto", "keep"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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``. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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. - Following values are supported: - - - Iterable[Codec]: List of filters to apply to the array. - - "auto": Automatically determine the filters based on the array's dtype. - - "keep": Retain the filters of the data array if it is a zarr Array. + The default value of ``"keep"`` instructs Zarr to infer ``filters`` from ``data``. + If that inference is not possible, Zarr will fall back to the behavior specified by ``"auto"``, + which is to choose default filters based on the data type of the array and the Zarr format specified. + For all data types in Zarr V3, and most data types in Zarr V2, the default filters are the empty tuple ``()``. + The only cases where default filters are not empty is when the Zarr format is 2, and the + data type is a variable-length data type like `:class:zarr.dtype.VariableLengthUTF8` or + `:class:zarr.dtype.VariableLengthUTF8`. In these cases, the default filters is a tuple with a + single element which is a codec specific to that particular data type. - If no ``filters`` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto". + To create an array with no filters, provide an empty iterable or the value ``None``. compressors : Iterable[Codec] or "auto" or "keep", optional 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. @@ -1037,7 +1088,7 @@ def from_array( For Zarr format 2, the default is ``{"name": "v2", "separator": "."}}``. If not specified and the data array has the same zarr format as the target array, the chunk key encoding of the data array is used. - dimension_names : Iterable[str], optional + dimension_names : Iterable[str | None] | None The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter. If not specified, defaults to the dimension names of the data array. @@ -1263,6 +1314,7 @@ 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, **kwargs: Any, @@ -1274,6 +1326,8 @@ 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 Path in store to array. @@ -1281,7 +1335,8 @@ def open_array( If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise. **kwargs - Any keyword arguments to pass to ``create``. + Any keyword arguments to pass to :func:`create`. + Returns ------- diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 51e638edd8..ca25b29286 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -64,7 +64,6 @@ parse_shapelike, product, ) -from zarr.core.config import categorize_data_type from zarr.core.config import config as zarr_config from zarr.core.dtype import ( VariableLengthBytes, @@ -505,12 +504,6 @@ async def create( If no codecs are provided, default codecs will be used: - - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``. - - For Unicode strings, the default is ``VLenUTF8Codec`` and ``ZstdCodec``. - - For bytes or objects, the default is ``VLenBytesCodec`` and ``ZstdCodec``. - - These defaults can be changed by modifying the value of ``array.v3_default_filters``, - ``array.v3_default_serializer`` and ``array.v3_default_compressors`` in :mod:`zarr.core.config`. dimension_names : Iterable[str | None], optional The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter. @@ -527,11 +520,25 @@ async def create( If `zarr_format`` is 3, then this parameter is deprecated, because memory order is a runtime parameter for Zarr 3 arrays. The recommended way to specify the memory order for Zarr 3 arrays is via the ``config`` parameter, e.g. ``{'config': 'C'}``. - filters : list[dict[str, JSON]], optional - Sequence of filters to use to encode chunk data prior to compression. - Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. 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`. + filters : Iterable[Codec] | Literal["auto"], optional + Iterable of filters to apply to each chunk of the array, in order, before serializing that + chunk to bytes. + + For Zarr format 3, a "filter" is a codec that takes an array and returns an array, + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. + + 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. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. compressor : dict[str, JSON], optional The compressor used to compress the data (default is None). Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. @@ -1914,9 +1921,6 @@ def create( - For numeric arrays, the default is ``BytesCodec`` and ``ZstdCodec``. - For Unicode strings, the default is ``VLenUTF8Codec`` and ``ZstdCodec``. - For bytes or objects, the default is ``VLenBytesCodec`` and ``ZstdCodec``. - - These defaults can be changed by modifying the value of ``array.v3_default_filters``, - ``array.v3_default_serializer`` and ``array.v3_default_compressors`` in :mod:`zarr.core.config`. dimension_names : Iterable[str | None], optional The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter. @@ -1933,11 +1937,25 @@ def create( If `zarr_format`` is 3, then this parameter is deprecated, because memory order is a runtime parameter for Zarr 3 arrays. The recommended way to specify the memory order for Zarr 3 arrays is via the ``config`` parameter, e.g. ``{'order': 'C'}``. - filters : list[dict[str, JSON]], optional - Sequence of filters to use to encode chunk data prior to compression. - Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. 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`. + filters : Iterable[Codec] | Literal["auto"], optional + Iterable of filters to apply to each chunk of the array, in order, before serializing that + chunk to bytes. + + For Zarr format 3, a "filter" is a codec that takes an array and returns an array, + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. + + 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. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. compressor : dict[str, JSON], optional Primary compressor to compress chunk data. Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. @@ -3979,24 +3997,27 @@ async def from_array( - None: No sharding. If not specified, defaults to "keep" if data is a zarr Array, otherwise None. - filters : Iterable[Codec] or "auto" or "keep", optional + filters : Iterable[Codec] | Literal["auto", "keep"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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``. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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. - Following values are supported: - - - Iterable[Codec]: List of filters to apply to the array. - - "auto": Automatically determine the filters based on the array's dtype. - - "keep": Retain the filters of the data array if it is a zarr Array. + The default value of ``"keep"`` instructs Zarr to infer ``filters`` from ``data``. + If that inference is not possible, Zarr will fall back to the behavior specified by ``"auto"``, + which is to choose default filters based on the data type of the array and the Zarr format specified. + For all data types in Zarr V3, and most data types in Zarr V2, the default filters are the empty tuple ``()``. + The only cases where default filters are not empty is when the Zarr format is 2, and the + data type is a variable-length data type like `:class:zarr.dtype.VariableLengthUTF8` or + `:class:zarr.dtype.VariableLengthUTF8`. In these cases, the default filters is a tuple with a + single element which is a codec specific to that particular data type. - If no ``filters`` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto". + To create an array with no filters, provide an empty iterable or the value ``None``. compressors : Iterable[Codec] or "auto" or "keep", optional 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. @@ -4048,7 +4069,7 @@ async def from_array( For Zarr format 2, the default is ``{"name": "v2", "separator": "."}}``. If not specified and the data array has the same zarr format as the target array, the chunk key encoding of the data array is used. - dimension_names : Iterable[str | None], optional + dimension_names : Iterable[str | None] | None The names of the dimensions (default is None). Zarr format 3 only. Zarr format 2 arrays should not use this parameter. If not specified, defaults to the dimension names of the data array. @@ -4223,46 +4244,40 @@ async def init_array( If not specified, default are guessed based on the shape and dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. - filters : Iterable[Codec], optional + filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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`` - in :mod:`zarr.core.config`. - Use ``None`` to omit default filters. - compressors : Iterable[Codec], optional + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. + compressors : Iterable[Codec] | Literal["auto"], optional 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 format 3, a "compressor" is a codec that takes a bytestream, 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. + The default value of ``"auto"`` instructs Zarr to use a default of :class:`zarr.codecs.ZstdCodec`. - 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 + To create an array with no compressors, provide an empty iterable or the value ``None``. + serializer : dict[str, JSON] | ArrayBytesCodec | Literal["auto"], optional Array-to-bytes codec to use for encoding the array data. 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`. + + The default value of ``"auto"`` instructs Zarr to use a default codec based on the data type of the array. + For most data types this default codec is :class:`zarr.codecs.BytesCodec`. + For :class:`zarr.dtype.VariableLengthUTF8`, the default codec is :class:`zarr.codecs.VlenUTF8Codec`. + For :class:`zarr.dtype.VariableLengthBytes`, the default codec is :class:`zarr.codecs.VlenBytesCodec`. fill_value : Any, optional Fill value for the array. order : {"C", "F"}, optional @@ -4438,36 +4453,37 @@ async def create_array( name : str or None, optional The name of the array within the store. If ``name`` is ``None``, the array will be located at the root of the store. - shape : tuple[int, ...], optional - Shape of the array. Can be ``None`` if ``data`` is provided. + shape : ShapeLike, optional + Shape of the array. Must be ``None`` if ``data`` is provided. dtype : ZDTypeLike | None - Data type of the array. Can be ``None`` if ``data`` is provided. - data : Array-like data to use for initializing the array. If this parameter is provided, the - ``shape`` and ``dtype`` parameters must be identical to ``data.shape`` and ``data.dtype``, - or ``None``. + Data type of the array. Must be ``None`` if ``data`` is provided. + data : np.ndarray, optional + Array-like data to use for initializing the array. If this parameter is provided, the + ``shape`` and ``dtype`` parameters must be ``None``. chunks : tuple[int, ...], optional Chunk shape of the array. If not specified, default are guessed based on the shape and dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. - filters : Iterable[Codec], optional + filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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`` - in :mod:`zarr.core.config`. - Use ``None`` to omit default filters. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. compressors : Iterable[Codec], optional 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. @@ -4516,6 +4532,7 @@ async def create_array( Ignored otherwise. overwrite : bool, default False Whether to overwrite an array with the same name in the store, if one exists. + If `True`, all existing paths in the store will be deleted. config : ArrayConfigLike, optional Runtime configuration for the array. write_data : bool @@ -4709,26 +4726,6 @@ def _parse_chunk_key_encoding( return result -def _get_default_chunk_encoding_v3( - dtype: ZDType[TBaseDType, TBaseScalar], -) -> tuple[tuple[ArrayArrayCodec, ...], ArrayBytesCodec, tuple[BytesBytesCodec, ...]]: - """ - Get the default ArrayArrayCodecs, ArrayBytesCodec, and BytesBytesCodec for a given dtype. - """ - - dtype_category = categorize_data_type(dtype) - - filters = zarr_config.get("array.v3_default_filters").get(dtype_category) - compressors = zarr_config.get("array.v3_default_compressors").get(dtype_category) - serializer = zarr_config.get("array.v3_default_serializer").get(dtype_category) - - return ( - tuple(_parse_array_array_codec(f) for f in filters), - _parse_array_bytes_codec(serializer), - tuple(_parse_bytes_bytes_codec(c) for c in compressors), - ) - - def default_filters_v3(dtype: ZDType[Any, Any]) -> tuple[ArrayArrayCodec, ...]: """ Given a data type, return the default filters for that data type. diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index 4c14fb357c..3bb6d7d468 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -1052,24 +1052,25 @@ async def create_array( If not specified, default are guessed based on the shape and dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. - filters : Iterable[Codec], optional + filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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`` - in :mod:`zarr.core.config`. - Use ``None`` to omit default filters. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. compressors : Iterable[Codec], optional 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. @@ -2485,24 +2486,25 @@ def create_array( If not specified, default are guessed based on the shape and dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. - filters : Iterable[Codec], optional + filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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`` - in :mod:`zarr.core.config`. - Use ``None`` to omit default filters. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. compressors : Iterable[Codec], optional 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. @@ -2881,24 +2883,25 @@ def array( If not specified, default are guessed based on the shape and dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. - filters : Iterable[Codec], optional + filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that chunk to bytes. 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. + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. 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`` - in :mod:`zarr.core.config`. - Use ``None`` to omit default filters. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. compressors : Iterable[Codec], optional 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. From a788a7f25bc26411a4636198cde1f7b677a404a0 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Tue, 19 Aug 2025 23:02:28 +0200 Subject: [PATCH 02/23] add tests for consistent docstrings --- tests/test_api/test_synchronous.py | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) create mode 100644 tests/test_api/test_synchronous.py diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py new file mode 100644 index 0000000000..fc5bba506b --- /dev/null +++ b/tests/test_api/test_synchronous.py @@ -0,0 +1,30 @@ +from __future__ import annotations + +from typing import Final + +import pytest +from numpydoc.docscrape import NumpyDocString + +from zarr.api import asynchronous, synchronous + +MATCHED_EXPORT_NAMES: Final[tuple[str, ...]] = tuple( + sorted(set(synchronous.__all__) | set(asynchronous.__all__)) +) +MATCHED_CALLABLE_NAMES: Final[tuple[str, ...]] = tuple( + x for x in MATCHED_EXPORT_NAMES if callable(getattr(synchronous, x)) +) + + +@pytest.mark.parametrize("callable_name", MATCHED_CALLABLE_NAMES) +def test_create_docstrings(callable_name: str) -> None: + """ + Tests that the docstrings for the sync and async define identical parameters. + """ + callable_a = getattr(synchronous, callable_name) + callable_b = getattr(asynchronous, callable_name) + if callable_a.__doc__ is None: + assert callable_b.__doc__ is None + else: + params_a = NumpyDocString(callable_a.__doc__)["Parameters"] + params_b = NumpyDocString(callable_b.__doc__)["Parameters"] + assert params_a == params_b From 54158d6caca93e5c38d1f5289bfd44130af4d4f9 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Tue, 19 Aug 2025 23:40:29 +0200 Subject: [PATCH 03/23] add flagrantly failing test for consistent parameter docstrings --- tests/test_api/test_synchronous.py | 54 +++++++++++++++++++++++++++++- 1 file changed, 53 insertions(+), 1 deletion(-) diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py index fc5bba506b..53171d0776 100644 --- a/tests/test_api/test_synchronous.py +++ b/tests/test_api/test_synchronous.py @@ -1,5 +1,6 @@ from __future__ import annotations +from dataclasses import dataclass from typing import Final import pytest @@ -7,6 +8,26 @@ from zarr.api import asynchronous, synchronous + +@dataclass(frozen=True, slots=True) +class Param: + name: str + desc: tuple[str, ...] + type: str + + +all_docstrings: dict[str, NumpyDocString] = {} + +for name in asynchronous.__all__: + obj = getattr(asynchronous, name) + if callable(obj) and obj.__doc__ is not None: + all_docstrings[f"asynchronous.{name}"] = NumpyDocString(obj.__doc__) + +for name in synchronous.__all__: + obj = getattr(synchronous, name) + if callable(obj) and obj.__doc__ is not None: + all_docstrings[f"synchronous.{name}"] = NumpyDocString(obj.__doc__) + MATCHED_EXPORT_NAMES: Final[tuple[str, ...]] = tuple( sorted(set(synchronous.__all__) | set(asynchronous.__all__)) ) @@ -16,7 +37,7 @@ @pytest.mark.parametrize("callable_name", MATCHED_CALLABLE_NAMES) -def test_create_docstrings(callable_name: str) -> None: +def test_docstring_match(callable_name: str) -> None: """ Tests that the docstrings for the sync and async define identical parameters. """ @@ -28,3 +49,34 @@ def test_create_docstrings(callable_name: str) -> None: params_a = NumpyDocString(callable_a.__doc__)["Parameters"] params_b = NumpyDocString(callable_b.__doc__)["Parameters"] assert params_a == params_b + + +@pytest.mark.parametrize( + "parameter_name", + [ + "store", + "path", + "filters", + "codecs", + "compressors", + "compressor", + "chunks", + "shape", + "dtype", + "data_type", + "fill_value", + ], +) +def test_docstring_consistent_parameters(parameter_name: str) -> None: + """ + Tests that callable exports from ``zarr.api.synchronous`` and ``zarr.api.asynchronous`` + document the same parameters consistently. + """ + matches: dict[str, Param] = {} + for name in all_docstrings: + docstring = all_docstrings[name] + param_dict = {d.name: d for d in docstring["Parameters"]} + if parameter_name in param_dict: + val = param_dict[parameter_name] + matches[name] = Param(name=val.name, desc=tuple(val.desc), type=val.type) + assert len(set(matches.values())) == 1 From 120db2a55935c3ce27ae4a062b446cd0153f8ddd Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 20 Aug 2025 15:31:00 +0200 Subject: [PATCH 04/23] add test for consistent docstring usage --- src/zarr/api/asynchronous.py | 39 +++++++++-------- src/zarr/api/synchronous.py | 50 +++++++++++----------- src/zarr/core/array.py | 12 +++--- src/zarr/storage/_common.py | 2 +- tests/test_api/test_synchronous.py | 68 +++++++++++++++++------------- 5 files changed, 89 insertions(+), 82 deletions(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index 5692da2d59..3bd58ce4c9 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -271,7 +271,7 @@ async def load( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. path : str or None, optional The path within the store from which to load. @@ -315,7 +315,7 @@ async def open( Parameters ---------- - store : Store or str, optional + store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. mode : {'r', 'r+', 'a', 'w', 'w-'}, optional Persistence mode: 'r' means read only (must exist); 'r+' means @@ -399,7 +399,7 @@ async def save( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. *args : ndarray NumPy arrays with data to save. @@ -435,7 +435,7 @@ async def save_array( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. arr : ndarray NumPy array with data to save. @@ -491,7 +491,7 @@ async def save_group( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. *args : ndarray NumPy arrays with data to save. @@ -640,14 +640,13 @@ async def group( Parameters ---------- - store : Store or str, optional - Store or path to directory in file system. + store : StoreLike or None, default=None + Store or path to directory in file system or name of zip file. overwrite : bool, optional If True, delete any pre-existing data in `store` at `path` before creating the group. - chunk_store : Store, optional - Separate storage for chunks. If not provided, `store` will be used - for storage of both chunks and metadata. + chunk_store : StoreLike or None, default=None + Separate storage for chunks. Not implemented. cache_attrs : bool, optional If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior @@ -717,8 +716,8 @@ async def create_group( Parameters ---------- - store : Store or str - Store or path to directory in file system. + store : StoreLike + Store or path to directory in file system or name of zip file. path : str, optional Group path within store. overwrite : bool, optional @@ -773,7 +772,7 @@ async def open_group( Parameters ---------- - store : Store, str, or mapping, optional + store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. Strings are interpreted as paths on the local file system @@ -798,7 +797,7 @@ async def open_group( Array synchronizer. path : str, optional Group path within store. - chunk_store : Store or str, optional + chunk_store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. storage_options : dict If using an fsspec URL to create the store, these will be passed to @@ -873,7 +872,7 @@ async def create( compressor: CompressorLike = "auto", fill_value: Any | None = DEFAULT_FILL_VALUE, order: MemoryOrder | None = None, - store: str | StoreLike | None = None, + store: StoreLike | None = None, synchronizer: Any | None = None, overwrite: bool = False, path: PathLike | None = None, @@ -924,14 +923,14 @@ async def create( :class:`zarr.codecs.ZstdCodec`is used. If ``compressor`` is set to ``None``, no compression is used. - fill_value : object - Default value to use for uninitialized portions of the array. + fill_value : Any, optional + Fill value for the array. order : {'C', 'F'}, optional Deprecated in favor of the ``config`` keyword argument. Pass ``{'order': }`` to ``create`` instead of using this parameter. Memory layout to be used within each chunk. If not specified, the ``array.order`` parameter in the global config will be used. - store : Store or str + store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. synchronizer : object, optional Array synchronizer. @@ -940,7 +939,7 @@ async def create( creating the array. path : str, optional Path under which array is stored. - chunk_store : MutableMapping, optional + chunk_store : StoreLike or None, default=None Separate storage for chunks. If not provided, `store` will be used for storage of both chunks and metadata. filters : Iterable[Codec] | Literal["auto"], optional @@ -1241,7 +1240,7 @@ async def open_array( Parameters ---------- - store : Store or str + store : StoreLike 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. diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index 62e6a47147..cf5ecaf39f 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -133,7 +133,7 @@ def load( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. path : str or None, optional The path within the store from which to load. @@ -173,7 +173,7 @@ def open( Parameters ---------- - store : Store or str, optional + store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. mode : {'r', 'r+', 'a', 'w', 'w-'}, optional Persistence mode: 'r' means read only (must exist); 'r+' means @@ -235,7 +235,7 @@ def save( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. *args : ndarray NumPy arrays with data to save. @@ -269,7 +269,7 @@ def save_array( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. arr : ndarray NumPy array with data to save. @@ -312,7 +312,7 @@ def save_group( Parameters ---------- - store : Store or str + store : StoreLike Store or path to directory in file system or name of zip file. *args : ndarray NumPy arrays with data to save. @@ -403,14 +403,13 @@ def group( Parameters ---------- - store : Store or str, optional - Store or path to directory in file system. + store : StoreLike or None, default=None + Store or path to directory in file system or name of zip file. overwrite : bool, optional If True, delete any pre-existing data in `store` at `path` before creating the group. - chunk_store : Store, optional - Separate storage for chunks. If not provided, `store` will be used - for storage of both chunks and metadata. + chunk_store : StoreLike or None, default=None + Separate storage for chunks. Not implemented. cache_attrs : bool, optional If True (default), user attributes will be cached for attribute read operations. If False, user attributes are reloaded from the store prior @@ -471,7 +470,7 @@ def open_group( Parameters ---------- - store : Store, str, or mapping, optional + store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. Strings are interpreted as paths on the local file system @@ -496,7 +495,7 @@ def open_group( Array synchronizer. path : str, optional Group path within store. - chunk_store : Store or str, optional + chunk_store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. storage_options : dict If using an fsspec URL to create the store, these will be passed to @@ -561,8 +560,8 @@ def create_group( Parameters ---------- - store : Store or str - Store or path to directory in file system. + store : StoreLike + Store or path to directory in file system or name of zip file. path : str, optional Group path within store. overwrite : bool, optional @@ -605,7 +604,7 @@ def create( compressor: CompressorLike = "auto", fill_value: Any | None = DEFAULT_FILL_VALUE, # TODO: need type order: MemoryOrder | None = None, - store: str | StoreLike | None = None, + store: StoreLike | None = None, synchronizer: Any | None = None, overwrite: bool = False, path: PathLike | None = None, @@ -656,14 +655,14 @@ def create( :class:`zarr.codecs.ZstdCodec`is used. If ``compressor`` is set to ``None``, no compression is used. - fill_value : object - Default value to use for uninitialized portions of the array. + fill_value : Any, optional + Fill value for the array. order : {'C', 'F'}, optional Deprecated in favor of the ``config`` keyword argument. Pass ``{'order': }`` to ``create`` instead of using this parameter. Memory layout to be used within each chunk. If not specified, the ``array.order`` parameter in the global config will be used. - store : Store or str + store : StoreLike or None, default=None Store or path to directory in file system or name of zip file. synchronizer : object, optional Array synchronizer. @@ -672,7 +671,7 @@ def create( creating the array. path : str, optional Path under which array is stored. - chunk_store : MutableMapping, optional + chunk_store : StoreLike or None, default=None Separate storage for chunks. If not provided, `store` will be used for storage of both chunks and metadata. filters : Iterable[Codec] | Literal["auto"], optional @@ -795,7 +794,7 @@ def create( def create_array( - store: str | StoreLike, + store: StoreLike, *, name: str | None = None, shape: ShapeLike | None = None, @@ -823,7 +822,7 @@ def create_array( Parameters ---------- - store : str or Store + store : StoreLike Store or path to directory in file system or name of zip file. name : str or None, optional The name of the array within the store. If ``name`` is ``None``, the array will be located @@ -962,7 +961,7 @@ def create_array( def from_array( - store: str | StoreLike, + store: StoreLike, *, data: Array | npt.ArrayLike, write_data: bool = True, @@ -986,8 +985,8 @@ def from_array( Parameters ---------- - store : str or Store - Store or path to directory in file system or name of zip file for the new array. + store : StoreLike + Store or path to directory in file system or name of zip file. data : Array | array-like The array to copy. write_data : bool, default True @@ -1323,7 +1322,7 @@ def open_array( Parameters ---------- - store : Store or str + store : StoreLike 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. @@ -1348,6 +1347,7 @@ def open_array( async_api.open_array( store=store, zarr_version=zarr_version, + zarr_format=zarr_format, path=path, storage_options=storage_options, **kwargs, diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index ca25b29286..591ec0d950 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -2097,7 +2097,7 @@ def open( Parameters ---------- - store : Store + store : StoreLike Store containing the Array. Returns @@ -3943,7 +3943,7 @@ class ShardsConfigParam(TypedDict): async def from_array( - store: str | StoreLike, + store: StoreLike, *, data: Array | npt.ArrayLike, write_data: bool = True, @@ -3967,8 +3967,8 @@ async def from_array( Parameters ---------- - store : str or Store - Store or path to directory in file system or name of zip file for the new array. + store : StoreLike + Store or path to directory in file system or name of zip file. data : Array | array-like The array to copy. write_data : bool, default True @@ -4422,7 +4422,7 @@ async def init_array( async def create_array( - store: str | StoreLike, + store: StoreLike, *, name: str | None = None, shape: ShapeLike | None = None, @@ -4448,7 +4448,7 @@ async def create_array( Parameters ---------- - store : str or Store + store : StoreLike Store or path to directory in file system or name of zip file. name : str or None, optional The name of the array within the store. If ``name`` is ``None``, the array will be located diff --git a/src/zarr/storage/_common.py b/src/zarr/storage/_common.py index 3a63b30e9b..d4b2ef082e 100644 --- a/src/zarr/storage/_common.py +++ b/src/zarr/storage/_common.py @@ -299,7 +299,7 @@ async def make_store_path( Parameters ---------- - store_like : StoreLike | None + store_like : StoreLike, optional The object to convert to a `StorePath` object. path : str | None, optional The path to use when creating the `StorePath` object. If None, the diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py index 53171d0776..f2477fcf6b 100644 --- a/tests/test_api/test_synchronous.py +++ b/tests/test_api/test_synchronous.py @@ -1,39 +1,24 @@ from __future__ import annotations -from dataclasses import dataclass -from typing import Final +from typing import TYPE_CHECKING, Any, Final import pytest from numpydoc.docscrape import NumpyDocString from zarr.api import asynchronous, synchronous - -@dataclass(frozen=True, slots=True) -class Param: - name: str - desc: tuple[str, ...] - type: str - - -all_docstrings: dict[str, NumpyDocString] = {} - -for name in asynchronous.__all__: - obj = getattr(asynchronous, name) - if callable(obj) and obj.__doc__ is not None: - all_docstrings[f"asynchronous.{name}"] = NumpyDocString(obj.__doc__) - -for name in synchronous.__all__: - obj = getattr(synchronous, name) - if callable(obj) and obj.__doc__ is not None: - all_docstrings[f"synchronous.{name}"] = NumpyDocString(obj.__doc__) +if TYPE_CHECKING: + from collections.abc import Callable MATCHED_EXPORT_NAMES: Final[tuple[str, ...]] = tuple( sorted(set(synchronous.__all__) | set(asynchronous.__all__)) ) +"""A sorted tuple of names that are exported by both the sync and async APIs.""" + MATCHED_CALLABLE_NAMES: Final[tuple[str, ...]] = tuple( x for x in MATCHED_EXPORT_NAMES if callable(getattr(synchronous, x)) ) +"""A sorted tuple of callable names that are exported by both the sync and async APIs.""" @pytest.mark.parametrize("callable_name", MATCHED_CALLABLE_NAMES) @@ -63,20 +48,43 @@ def test_docstring_match(callable_name: str) -> None: "chunks", "shape", "dtype", - "data_type", "fill_value", ], ) -def test_docstring_consistent_parameters(parameter_name: str) -> None: +@pytest.mark.parametrize( + "array_creation_routines", + [ + ( + asynchronous.create_array, + synchronous.create_array, + asynchronous.create_group, + synchronous.create_group, + ), + (asynchronous.create, synchronous.create), + ], +) +def test_docstring_consistent_parameters( + parameter_name: str, array_creation_routines: tuple[Callable[[Any], Any], ...] +) -> None: """ - Tests that callable exports from ``zarr.api.synchronous`` and ``zarr.api.asynchronous`` - document the same parameters consistently. + Tests that array and group creation routines document the same parameters consistently. """ - matches: dict[str, Param] = {} - for name in all_docstrings: - docstring = all_docstrings[name] + descs: dict[tuple[str, ...], tuple[str, ...]] = {} + types: dict[str, tuple[str, ...]] = {} + for routine in array_creation_routines: + key = f"{routine.__module__}.{routine.__qualname__}" + docstring = NumpyDocString(routine.__doc__) param_dict = {d.name: d for d in docstring["Parameters"]} if parameter_name in param_dict: val = param_dict[parameter_name] - matches[name] = Param(name=val.name, desc=tuple(val.desc), type=val.type) - assert len(set(matches.values())) == 1 + if tuple(val.desc) in descs: + descs[tuple(val.desc)] = descs[tuple(val.desc)] + (key,) + else: + descs[tuple(val.desc)] = (key,) + if val.type in types: + types[val.type] = types[val.type] + (key,) + else: + types[val.type] = (key,) + + assert len(descs) <= 1 + assert len(types) <= 1 From 72622fdcb2f9bc5e8e0e214b3d3efcf8e658a372 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 20 Aug 2025 15:49:30 +0200 Subject: [PATCH 05/23] add missing docstring and re-parametrize test --- src/zarr/core/group.py | 146 ++++++++++++++++++++++++++++- tests/test_api/test_synchronous.py | 80 +++++++++++----- 2 files changed, 201 insertions(+), 25 deletions(-) diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index 3bb6d7d468..62b98462ee 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -2439,9 +2439,149 @@ def require_groups(self, *names: str) -> tuple[Group, ...]: """ return tuple(map(Group, self._sync(self._async_group.require_groups(*names)))) - def create(self, *args: Any, **kwargs: Any) -> Array: - # Backwards compatibility for 2.x - return self.create_array(*args, **kwargs) + def create( + self, + name: str, + *, + shape: ShapeLike | None = None, + dtype: ZDTypeLike | None = None, + data: np.ndarray[Any, np.dtype[Any]] | None = None, + chunks: tuple[int, ...] | Literal["auto"] = "auto", + shards: ShardsLike | None = None, + filters: FiltersLike = "auto", + compressors: CompressorsLike = "auto", + compressor: CompressorLike = "auto", + serializer: SerializerLike = "auto", + fill_value: Any | None = DEFAULT_FILL_VALUE, + order: MemoryOrder | None = None, + attributes: dict[str, JSON] | None = None, + chunk_key_encoding: ChunkKeyEncodingLike | None = None, + dimension_names: DimensionNames = None, + storage_options: dict[str, Any] | None = None, + overwrite: bool = False, + config: ArrayConfigLike | None = None, + write_data: bool = True, + ) -> Array: + """Create an array within this group. + + This method lightly wraps :func:`zarr.core.array.create_array`. + + Parameters + ---------- + name : str + The name of the array relative to the group. If ``path`` is ``None``, the array will be located + at the root of the store. + shape : ShapeLike, optional + Shape of the array. Must be ``None`` if ``data`` is provided. + dtype : npt.DTypeLike | None + Data type of the array. Must be ``None`` if ``data`` is provided. + data : Array-like data to use for initializing the array. If this parameter is provided, the + ``shape`` and ``dtype`` parameters must be ``None``. + chunks : tuple[int, ...], optional + Chunk shape of the array. + If not specified, default are guessed based on the shape and dtype. + shards : tuple[int, ...], optional + Shard shape of the array. The default value of ``None`` results in no sharding at all. + filters : Iterable[Codec] | Literal["auto"], optional + Iterable of filters to apply to each chunk of the array, in order, before serializing that + chunk to bytes. + + For Zarr format 3, a "filter" is a codec that takes an array and returns an array, + and these values must be instances of :class:`zarr.abc.codec.ArrayArrayCodec`, or a + dict representations of :class:`zarr.abc.codec.ArrayArrayCodec`. + + 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. + + The default value of ``"auto"`` instructs Zarr to use a default used based on the data + type of the array and the Zarr format specified. For all data types in Zarr V3, and most + data types in Zarr V2, the default filters are empty. The only cases where default filters + are not empty is when the Zarr format is 2, and the data type is a variable-length data type like + `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + the default filters contains a single element which is a codec specific to that particular data type. + + To create an array with no filters, provide an empty iterable or the value ``None``. + compressors : Iterable[Codec], optional + 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 format 3, a "compressor" is a codec that takes a bytestream, 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 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. + compressor : Codec, optional + Deprecated in favor of ``compressors``. + serializer : dict[str, JSON] | ArrayBytesCodec, optional + Array-to-bytes codec to use for encoding the array data. + 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 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`. + attributes : dict, optional + Attributes for the array. + chunk_key_encoding : ChunkKeyEncoding, optional + A specification of how the chunk keys are represented in storage. + 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 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. + overwrite : bool, default False + Whether to overwrite an array with the same name in the store, if one exists. + config : ArrayConfig or ArrayConfigLike, optional + Runtime configuration for the array. + write_data : bool + If a pre-existing array-like object was provided to this function via the ``data`` parameter + then ``write_data`` determines whether the values in that array-like object should be + written to the Zarr array created by this function. If ``write_data`` is ``False``, then the + array will be left empty. + + Returns + ------- + AsyncArray + """ + return self.create_array( + name, + shape=shape, + dtype=dtype, + data=data, + chunks=chunks, + shards=shards, + filters=filters, + compressors=compressors, + compressor=compressor, + serializer=serializer, + fill_value=fill_value, + order=order, + attributes=attributes, + chunk_key_encoding=chunk_key_encoding, + dimension_names=dimension_names, + storage_options=storage_options, + overwrite=overwrite, + config=config, + write_data=write_data, + ) def create_array( self, diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py index f2477fcf6b..ac1e3e6a14 100644 --- a/tests/test_api/test_synchronous.py +++ b/tests/test_api/test_synchronous.py @@ -5,6 +5,7 @@ import pytest from numpydoc.docscrape import NumpyDocString +import zarr from zarr.api import asynchronous, synchronous if TYPE_CHECKING: @@ -37,37 +38,73 @@ def test_docstring_match(callable_name: str) -> None: @pytest.mark.parametrize( - "parameter_name", - [ - "store", - "path", - "filters", - "codecs", - "compressors", - "compressor", - "chunks", - "shape", - "dtype", - "fill_value", - ], -) -@pytest.mark.parametrize( - "array_creation_routines", + ("parameter_name", "array_creation_routines"), [ ( - asynchronous.create_array, - synchronous.create_array, - asynchronous.create_group, - synchronous.create_group, + ("store", "path"), + ( + asynchronous.create_array, + synchronous.create_array, + asynchronous.create_group, + synchronous.create_group, + zarr.AsyncGroup.create_array, + zarr.Group.create_array, + ), + ), + ( + ( + "store", + "path", + ), + ( + asynchronous.create, + synchronous.create, + zarr.Group.create, + zarr.AsyncArray.create, + zarr.Array.create, + ), + ), + ( + ( + ( + "filters", + "codecs", + "compressors", + "compressor", + "chunks", + "shape", + "dtype", + "shardsfill_value", + ) + ), + ( + asynchronous.create, + synchronous.create, + asynchronous.create_array, + synchronous.create_array, + zarr.AsyncGroup.create_array, + zarr.Group.create_array, + zarr.AsyncGroup.create_dataset, + zarr.Group.create_dataset, + ), ), - (asynchronous.create, synchronous.create), ], + ids=str, ) def test_docstring_consistent_parameters( parameter_name: str, array_creation_routines: tuple[Callable[[Any], Any], ...] ) -> None: """ Tests that array and group creation routines document the same parameters consistently. + This test inspecs the docstrings of sets of callables and generates two dicts: + + - a dict where the keys are parameter descriptions and the values are the names of the routines with those + descriptions + - a dict where the keys are parameter types and the values are the names of the routines with those types + + If each dict has just 1 value, then the parameter description and type in the docstring must be + identical across different routines. But if these dicts have multiple values, then there must be + routines that use the same parameter but document it differently, which will trigger a test failure. """ descs: dict[tuple[str, ...], tuple[str, ...]] = {} types: dict[str, tuple[str, ...]] = {} @@ -85,6 +122,5 @@ def test_docstring_consistent_parameters( types[val.type] = types[val.type] + (key,) else: types[val.type] = (key,) - assert len(descs) <= 1 assert len(types) <= 1 From 18ff19b82433d7ff70917ab2661961fccfec4842 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 20 Aug 2025 18:02:54 +0200 Subject: [PATCH 06/23] fix rst --- src/zarr/api/asynchronous.py | 2 +- src/zarr/api/synchronous.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index 3bd58ce4c9..a7d41e4a95 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -920,7 +920,7 @@ async def create( Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. If neither ``compressor`` nor ``filters`` are provided, the default compressor - :class:`zarr.codecs.ZstdCodec`is used. + :class:`zarr.codecs.ZstdCodec` is used. If ``compressor`` is set to ``None``, no compression is used. fill_value : Any, optional diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index cf5ecaf39f..76d8b2bafe 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -652,7 +652,7 @@ def create( Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. If neither ``compressor`` nor ``filters`` are provided, the default compressor - :class:`zarr.codecs.ZstdCodec`is used. + :class:`zarr.codecs.ZstdCodec` is used. If ``compressor`` is set to ``None``, no compression is used. fill_value : Any, optional From 9cd823e083f8afd79639d9c53d837a0d981a3e3d Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 20 Aug 2025 18:29:08 +0200 Subject: [PATCH 07/23] update docstring for make_store_path --- src/zarr/storage/_common.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/storage/_common.py b/src/zarr/storage/_common.py index d4b2ef082e..4d167807c8 100644 --- a/src/zarr/storage/_common.py +++ b/src/zarr/storage/_common.py @@ -299,7 +299,7 @@ async def make_store_path( Parameters ---------- - store_like : StoreLike, optional + store_like : StoreLike or None, default=None The object to convert to a `StorePath` object. path : str | None, optional The path to use when creating the `StorePath` object. If None, the From a0c56933f6cd81f976e8f117fa76cec1962acec8 Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 20 Aug 2025 18:45:57 +0200 Subject: [PATCH 08/23] ArrayConfigLike contains ArrayConfig --- src/zarr/api/asynchronous.py | 2 +- src/zarr/api/synchronous.py | 2 +- src/zarr/core/array.py | 2 +- src/zarr/core/group.py | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index a7d41e4a95..750739c82c 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -1015,7 +1015,7 @@ async def create( storage_options : dict If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise. - config : ArrayConfig | ArrayConfigLike, optional + config : ArrayConfigLike, optional Runtime configuration of the array. If provided, will override the default values from `zarr.config.array`. diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index 76d8b2bafe..c08380542b 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -747,7 +747,7 @@ def create( storage_options : dict If using an fsspec URL to create the store, these will be passed to the backend implementation. Ignored otherwise. - config : ArrayConfig | ArrayConfigLike, optional + config : ArrayConfigLike, optional Runtime configuration of the array. If provided, will override the default values from `zarr.config.array`. diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 591ec0d950..8d2cd80382 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -3961,7 +3961,7 @@ async def from_array( dimension_names: DimensionNames = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, - config: ArrayConfig | ArrayConfigLike | None = None, + config: ArrayConfigLike | None = None, ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]: """Create an array from an existing array or array-like. diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index 62b98462ee..caae4bf370 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -73,7 +73,7 @@ ) from typing import Any - from zarr.core.array_spec import ArrayConfig, ArrayConfigLike + from zarr.core.array_spec import ArrayConfigLike from zarr.core.buffer import Buffer, BufferPrototype from zarr.core.chunk_key_encodings import ChunkKeyEncodingLike from zarr.core.common import MemoryOrder @@ -2999,7 +2999,7 @@ def array( dimension_names: DimensionNames = None, storage_options: dict[str, Any] | None = None, overwrite: bool = False, - config: ArrayConfig | ArrayConfigLike | None = None, + config: ArrayConfigLike | None = None, data: npt.ArrayLike | None = None, ) -> Array: """Create an array within this group. From 24fefeaca011115e13b91077ddbc6fe6a027757e Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 20 Aug 2025 18:51:15 +0200 Subject: [PATCH 09/23] update chunks docstrings --- src/zarr/api/synchronous.py | 4 ++-- src/zarr/core/array.py | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index c08380542b..a0e2eb70af 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -834,9 +834,9 @@ def create_array( data : np.ndarray, optional Array-like data to use for initializing the array. If this parameter is provided, the ``shape`` and ``dtype`` parameters must be ``None``. - chunks : tuple[int, ...], optional + chunks : tuple[int, ...] | Literal["auto"], default="auto" Chunk shape of the array. - If not specified, default are guessed based on the shape and dtype. + If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. filters : Iterable[Codec] | Literal["auto"], optional diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 8d2cd80382..ae31a02206 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -4460,9 +4460,9 @@ async def create_array( data : np.ndarray, optional Array-like data to use for initializing the array. If this parameter is provided, the ``shape`` and ``dtype`` parameters must be ``None``. - chunks : tuple[int, ...], optional + chunks : tuple[int, ...] | Literal["auto"], default="auto" Chunk shape of the array. - If not specified, default are guessed based on the shape and dtype. + If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype. shards : tuple[int, ...], optional Shard shape of the array. The default value of ``None`` results in no sharding at all. filters : Iterable[Codec] | Literal["auto"], optional From 184c7aa2a7b3248225899bea2abd3307c85e0c0e Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Wed, 20 Aug 2025 18:52:08 +0200 Subject: [PATCH 10/23] typo --- tests/test_api/test_synchronous.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py index ac1e3e6a14..43401e6aa3 100644 --- a/tests/test_api/test_synchronous.py +++ b/tests/test_api/test_synchronous.py @@ -96,7 +96,7 @@ def test_docstring_consistent_parameters( ) -> None: """ Tests that array and group creation routines document the same parameters consistently. - This test inspecs the docstrings of sets of callables and generates two dicts: + This test inspects the docstrings of sets of callables and generates two dicts: - a dict where the keys are parameter descriptions and the values are the names of the routines with those descriptions From e4dd7e287c3fe07bd4d45271f0ac2c25d49abfde Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Mon, 15 Sep 2025 11:58:20 +0200 Subject: [PATCH 11/23] changelog --- changes/3390.misc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 changes/3390.misc.rst diff --git a/changes/3390.misc.rst b/changes/3390.misc.rst new file mode 100644 index 0000000000..fa229a3ad8 --- /dev/null +++ b/changes/3390.misc.rst @@ -0,0 +1 @@ +Improve documentation consistency across API functions and remove outdated references to deprecated configuration values that no longer work. \ No newline at end of file From 08bfd1c42029b88c976ace8d40fba96bdadae85a Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:21:27 +0200 Subject: [PATCH 12/23] Update src/zarr/api/asynchronous.py Co-authored-by: Tom Augspurger --- src/zarr/api/asynchronous.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index f75de2fc0e..bf64357db2 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -906,10 +906,10 @@ async def create( shape : int or tuple of ints Array shape. chunks : int or tuple of ints, optional - Chunk shape. If True, will be guessed from `shape` and `dtype`. If - False, will be set to `shape`, i.e., single chunk for the whole array. + Chunk shape. If True, will be guessed from ``shape`` and ``dtype``. If + False, will be set to ``shape``, i.e., single chunk for the whole array. If an int, the chunk size in each dimension will be given by the value - of `chunks`. Default is True. + of ``chunks``. Default is True. dtype : str or dtype, optional NumPy dtype. compressor : Codec, optional From 11e44a0fea0ea000a019532f131912df37d7d83d Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:21:56 +0200 Subject: [PATCH 13/23] Update src/zarr/core/array.py Co-authored-by: Tom Augspurger --- src/zarr/core/array.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index aeefc32515..9a0c456fa5 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -4252,8 +4252,8 @@ async def from_array( which is to choose default filters based on the data type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are the empty tuple ``()``. The only cases where default filters are not empty is when the Zarr format is 2, and the - data type is a variable-length data type like `:class:zarr.dtype.VariableLengthUTF8` or - `:class:zarr.dtype.VariableLengthUTF8`. In these cases, the default filters is a tuple with a + data type is a variable-length data type like :class:`zarr.dtype.VariableLengthUTF8` or + :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters is a tuple with a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From 831f391d1f4760abc48e613ebd9667d01bef254f Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:03 +0200 Subject: [PATCH 14/23] Update src/zarr/api/asynchronous.py Co-authored-by: Tom Augspurger --- src/zarr/api/asynchronous.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index bf64357db2..cd770ffbdb 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -954,7 +954,7 @@ async def create( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From fba74415f99d5e9696b5ff132ad8f3e09e9c9e83 Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:09 +0200 Subject: [PATCH 15/23] Update src/zarr/api/synchronous.py Co-authored-by: Tom Augspurger --- src/zarr/api/synchronous.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index ac12202ac9..c9fa3a4163 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -1040,8 +1040,8 @@ def from_array( which is to choose default filters based on the data type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are the empty tuple ``()``. The only cases where default filters are not empty is when the Zarr format is 2, and the - data type is a variable-length data type like `:class:zarr.dtype.VariableLengthUTF8` or - `:class:zarr.dtype.VariableLengthUTF8`. In these cases, the default filters is a tuple with a + data type is a variable-length data type like :class:`zarr.dtype.VariableLengthUTF8` or + :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters is a tuple with a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From dc393a1fd7578b8abbc77929e917598f8b5adfd5 Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:15 +0200 Subject: [PATCH 16/23] Update src/zarr/core/array.py Co-authored-by: Tom Augspurger --- src/zarr/core/array.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 9a0c456fa5..3b508dade0 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -2105,7 +2105,7 @@ def create( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From 7216acd641ce601cb8db770e06fbaf64b6d17542 Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:21 +0200 Subject: [PATCH 17/23] Update src/zarr/core/array.py Co-authored-by: Tom Augspurger --- src/zarr/core/array.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 3b508dade0..04affab50f 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -554,7 +554,7 @@ async def create( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From b8d96487d63d73094efbf2244ecdbef2b0319803 Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:27 +0200 Subject: [PATCH 18/23] Update src/zarr/core/array.py Co-authored-by: Tom Augspurger --- src/zarr/core/array.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 04affab50f..eaddae485b 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -4498,7 +4498,7 @@ async def init_array( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From a8a30166d1e479903a1a35d33fb86ab7440f5579 Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:33 +0200 Subject: [PATCH 19/23] Update src/zarr/core/group.py Co-authored-by: Tom Augspurger --- src/zarr/core/group.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index 50d1e6cdcf..030fbc7963 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -2507,7 +2507,7 @@ def create( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From 9f0853155908f53b6c987527f71602d91a20b8aa Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:40 +0200 Subject: [PATCH 20/23] Update src/zarr/core/group.py Co-authored-by: Tom Augspurger --- src/zarr/core/group.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index 030fbc7963..e2d5339985 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -3048,7 +3048,7 @@ def array( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From d2480bc23ecf56dc3a3cb3900cc266ca5d9655be Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:46 +0200 Subject: [PATCH 21/23] Update src/zarr/core/group.py Co-authored-by: Tom Augspurger --- src/zarr/core/group.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index e2d5339985..7e1edfcb83 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -1077,7 +1077,7 @@ async def create_array( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. From 9802d1f996e22044a75d2c182da19e4d30afa486 Mon Sep 17 00:00:00 2001 From: Davis Bennett Date: Tue, 16 Sep 2025 22:22:54 +0200 Subject: [PATCH 22/23] Update src/zarr/core/array.py Co-authored-by: Tom Augspurger --- src/zarr/core/array.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index eaddae485b..5ae60162d0 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -4773,7 +4773,7 @@ async def create_array( Ignored otherwise. overwrite : bool, default False Whether to overwrite an array with the same name in the store, if one exists. - If `True`, all existing paths in the store will be deleted. + If ``True``, all existing paths in the store will be deleted. config : ArrayConfigLike, optional Runtime configuration for the array. write_data : bool From 642276152fa3d4c436bce361c90977762d66c38f Mon Sep 17 00:00:00 2001 From: Davis Vann Bennett Date: Tue, 16 Sep 2025 23:36:07 +0200 Subject: [PATCH 23/23] normalize more docstrings, and make docstring tests easier to interpret --- src/zarr/api/asynchronous.py | 4 ++-- src/zarr/api/synchronous.py | 16 ++++++++-------- src/zarr/core/array.py | 2 +- src/zarr/core/group.py | 2 +- tests/test_api/test_synchronous.py | 8 ++++++-- 5 files changed, 18 insertions(+), 14 deletions(-) diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index cd770ffbdb..dd5a162927 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -932,12 +932,12 @@ async def create( synchronizer : object, optional Array synchronizer. overwrite : bool, optional - If True, delete all pre-existing data in `store` at `path` before + If True, delete all pre-existing data in ``store`` at ``path`` before creating the array. path : str, optional Path under which array is stored. chunk_store : StoreLike or None, default=None - Separate storage for chunks. If not provided, `store` will be used + Separate storage for chunks. If not provided, ``store`` will be used for storage of both chunks and metadata. filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index c9fa3a4163..d0134a4900 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -650,10 +650,10 @@ def create( shape : int or tuple of ints Array shape. chunks : int or tuple of ints, optional - Chunk shape. If True, will be guessed from `shape` and `dtype`. If - False, will be set to `shape`, i.e., single chunk for the whole array. + Chunk shape. If True, will be guessed from ``shape`` and ``dtype``. If + False, will be set to ``shape``, i.e., single chunk for the whole array. If an int, the chunk size in each dimension will be given by the value - of `chunks`. Default is True. + of ``chunks``. Default is True. dtype : str or dtype, optional NumPy dtype. compressor : Codec, optional @@ -676,12 +676,12 @@ def create( synchronizer : object, optional Array synchronizer. overwrite : bool, optional - If True, delete all pre-existing data in `store` at `path` before + If True, delete all pre-existing data in ``store`` at ``path`` before creating the array. path : str, optional Path under which array is stored. chunk_store : StoreLike or None, default=None - Separate storage for chunks. If not provided, `store` will be used + Separate storage for chunks. If not provided, ``store`` will be used for storage of both chunks and metadata. filters : Iterable[Codec] | Literal["auto"], optional Iterable of filters to apply to each chunk of the array, in order, before serializing that @@ -698,7 +698,7 @@ def create( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. @@ -863,7 +863,7 @@ def create_array( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. @@ -915,7 +915,7 @@ def create_array( Ignored otherwise. overwrite : bool, default False Whether to overwrite an array with the same name in the store, if one exists. - If `True`, all existing paths in the store will be deleted. + If ``True``, all existing paths in the store will be deleted. config : ArrayConfigLike, optional Runtime configuration for the array. write_data : bool diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index 5ae60162d0..960b322a25 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -4721,7 +4721,7 @@ async def create_array( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. diff --git a/src/zarr/core/group.py b/src/zarr/core/group.py index 7e1edfcb83..f5bb14c48e 100644 --- a/src/zarr/core/group.py +++ b/src/zarr/core/group.py @@ -2651,7 +2651,7 @@ def create_array( type of the array and the Zarr format specified. For all data types in Zarr V3, and most data types in Zarr V2, the default filters are empty. The only cases where default filters are not empty is when the Zarr format is 2, and the data type is a variable-length data type like - `:class:zarr.dtype.VariableLengthUTF8` or `:class:zarr.dtype.VariableLengthUTF8`. In these cases, + :class:`zarr.dtype.VariableLengthUTF8` or :class:`zarr.dtype.VariableLengthUTF8`. In these cases, the default filters contains a single element which is a codec specific to that particular data type. To create an array with no filters, provide an empty iterable or the value ``None``. diff --git a/tests/test_api/test_synchronous.py b/tests/test_api/test_synchronous.py index 43401e6aa3..d6ae61f1ca 100644 --- a/tests/test_api/test_synchronous.py +++ b/tests/test_api/test_synchronous.py @@ -23,7 +23,7 @@ @pytest.mark.parametrize("callable_name", MATCHED_CALLABLE_NAMES) -def test_docstring_match(callable_name: str) -> None: +def test_docstrings_match(callable_name: str) -> None: """ Tests that the docstrings for the sync and async define identical parameters. """ @@ -34,7 +34,11 @@ def test_docstring_match(callable_name: str) -> None: else: params_a = NumpyDocString(callable_a.__doc__)["Parameters"] params_b = NumpyDocString(callable_b.__doc__)["Parameters"] - assert params_a == params_b + mismatch = [] + for idx, (a, b) in enumerate(zip(params_a, params_b, strict=False)): + if a != b: + mismatch.append((idx, (a, b))) + assert mismatch == [] @pytest.mark.parametrize(