diff --git a/changes/4193.doc.md b/changes/4193.doc.md new file mode 100644 index 0000000000..0972e8be2c --- /dev/null +++ b/changes/4193.doc.md @@ -0,0 +1,4 @@ +Converted remaining reStructuredText-style double-backtick markup to Markdown +single backticks in the docstrings of `zarr.api.asynchronous`, +`zarr.api.synchronous`, `zarr.core.array`, `zarr.registry`, and +`zarr.storage._common`. No functional changes. diff --git a/src/zarr/api/asynchronous.py b/src/zarr/api/asynchronous.py index f5e614a051..3bdc254ea5 100644 --- a/src/zarr/api/asynchronous.py +++ b/src/zarr/api/asynchronous.py @@ -103,7 +103,7 @@ def _infer_overwrite(mode: AccessModeLiteral) -> bool: """ - Check that an ``AccessModeLiteral`` is compatible with overwriting an existing Zarr node. + Check that an `AccessModeLiteral` is compatible with overwriting an existing Zarr node. """ return mode in _OVERWRITE_MODES @@ -112,9 +112,9 @@ def _warn_unimplemented_kwargs(kwargs: dict[str, Any]) -> None: """ Emit a "not yet implemented" warning for each provided keyword argument that is not None. - ``kwargs`` maps a keyword argument name to its supplied value. The ``stacklevel`` is chosen + `kwargs` maps a keyword argument name to its supplied value. The `stacklevel` is chosen so the warning points at the caller of the public API function (the same location as an - inline ``warnings.warn(..., stacklevel=2)`` would). + inline `warnings.warn(..., stacklevel=2)` would). """ for name, value in kwargs.items(): if value is not None: @@ -194,7 +194,7 @@ async def consolidate_metadata( Upon completion, the metadata of the root node in the Zarr hierarchy will be updated to include all the metadata of child nodes. For Stores that do - not support consolidated metadata, this operation raises a ``TypeError``. + not support consolidated metadata, this operation raises a `TypeError`. Parameters ---------- @@ -215,10 +215,10 @@ async def consolidate_metadata( Returns ------- group: AsyncGroup - The group, with the ``consolidated_metadata`` field set to include + The group, with the `consolidated_metadata` field set to include the metadata of each child node. If the Store doesn't support consolidated metadata, this function raises a `TypeError`. - See ``Store.supports_consolidated_metadata``. + See `Store.supports_consolidated_metadata`. """ store_path = await make_store_path(store, path=path) @@ -420,7 +420,7 @@ async def open_consolidated( *args: Any, use_consolidated: Literal[True] = True, **kwargs: Any ) -> AsyncGroup: """ - Alias for [`open_group`][zarr.api.asynchronous.open_group] with ``use_consolidated=True``. + Alias for [`open_group`][zarr.api.asynchronous.open_group] with `use_consolidated=True`. """ if use_consolidated is not True: raise TypeError( @@ -484,7 +484,7 @@ 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. The default is ``None``, which will + 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. @@ -745,12 +745,12 @@ async def create_group( path : str, optional Group path within store. overwrite : bool, optional - If True, pre-existing data at ``path`` will be deleted before + If True, pre-existing data at `path` will be deleted before creating the group. zarr_format : {2, 3, None}, optional The zarr format to use when saving. - If no ``zarr_format`` is provided, the default format will be used. - This default can be changed by modifying the value of ``default_zarr_format`` + If no `zarr_format` is provided, the default format will be used. + This default can be changed by modifying the value of `default_zarr_format` in [`zarr.config`][zarr.config]. storage_options : dict If using an fsspec URL to create the store, these will be passed to @@ -828,17 +828,17 @@ async def open_group( Whether to use consolidated metadata. By default, consolidated metadata is used if it's present in the - store (in the ``zarr.json`` for Zarr format 3 and in the ``.zmetadata`` file + store (in the `zarr.json` for Zarr format 3 and in the `.zmetadata` file for Zarr format 2). - To explicitly require consolidated metadata, set ``use_consolidated=True``, + To explicitly require consolidated metadata, set `use_consolidated=True`, which will raise an exception if consolidated metadata is not found. - To explicitly *not* use consolidated metadata, set ``use_consolidated=False``, + To explicitly *not* use consolidated metadata, set `use_consolidated=False`, which will fall back to using the regular, non consolidated metadata. Zarr format 2 allowed configuring the key storing the consolidated metadata - (``.zmetadata`` by default). Specify the custom key as ``use_consolidated`` + (`.zmetadata` by default). Specify the custom key as `use_consolidated` to load consolidated metadata from a non-default key. Returns @@ -924,27 +924,27 @@ 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 Primary compressor to compress chunk data. - Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. + Zarr format 2 only. Zarr format 3 arrays should use `codecs` instead. - If neither ``compressor`` nor ``filters`` are provided, the default compressor + If neither `compressor` nor `filters` are provided, the default compressor [`zarr.codecs.ZstdCodec`][] is used. - If ``compressor`` is set to ``None``, no compression is used. + If `compressor` is set to `None`, no compression is used. 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. + 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. + If not specified, the `array.order` parameter in the global config will be used. store : StoreLike or None, default=None StoreLike object to open. See the [storage documentation in the user guide][user-guide-store-like] @@ -952,12 +952,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 @@ -970,14 +970,14 @@ async def create( For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter. - The default value of ``"auto"`` instructs Zarr to use a default based on the data + The default value of `"auto"` instructs Zarr to use a default 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 [`zarr.dtype.VariableLengthUTF8`][] or [`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``. + 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 @@ -993,17 +993,17 @@ async def create( A codec to encode object arrays, only needed if dtype=object. dimension_separator : {'.', '/'}, optional Separator placed between the dimensions of a chunk. - Zarr format 2 only. Zarr format 3 arrays should use ``chunk_key_encoding`` instead. + 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. + Deprecated in favor of the `config` keyword argument. + Pass `{'write_empty_chunks': }` to `create` instead of using this parameter. If True, all chunks will be stored regardless of their contents. If False, each chunk is compared to the array's fill value prior to storing. If a chunk is uniformly equal to the fill value, then 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 creating an array. The default is ``None``, + 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 @@ -1016,15 +1016,15 @@ async def create( 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", "/")``. + 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. + 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())``; + For most data types, the default codecs are the tuple `(BytesCodec(), ZstdCodec())`; data types that require a special [`zarr.abc.codec.ArrayBytesCodec`][], like variable-length strings or bytes, will use the [`zarr.abc.codec.ArrayBytesCodec`][] required for the data type instead of [`zarr.codecs.BytesCodec`][]. dimension_names : Iterable[str | None] | None = None diff --git a/src/zarr/api/synchronous.py b/src/zarr/api/synchronous.py index dc12d5f7af..ebf42dca37 100644 --- a/src/zarr/api/synchronous.py +++ b/src/zarr/api/synchronous.py @@ -106,10 +106,10 @@ def consolidate_metadata( Returns ------- group: Group - The group, with the ``consolidated_metadata`` field set to include + The group, with the `consolidated_metadata` field set to include the metadata of each child node. If the Store doesn't support consolidated metadata, this function raises a `TypeError`. - See ``Store.supports_consolidated_metadata``. + See `Store.supports_consolidated_metadata`. """ return Group(sync(async_api.consolidate_metadata(store, path=path, zarr_format=zarr_format))) @@ -247,7 +247,7 @@ def open( def open_consolidated(*args: Any, use_consolidated: Literal[True] = True, **kwargs: Any) -> Group: """ - Alias for [`open_group`][zarr.api.synchronous.open_group] with ``use_consolidated=True``. + Alias for [`open_group`][zarr.api.synchronous.open_group] with `use_consolidated=True`. """ return Group( sync(async_api.open_consolidated(*args, use_consolidated=use_consolidated, **kwargs)) @@ -303,7 +303,7 @@ 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 default is ``None``, which will + 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. @@ -530,17 +530,17 @@ def open_group( Whether to use consolidated metadata. By default, consolidated metadata is used if it's present in the - store (in the ``zarr.json`` for Zarr format 3 and in the ``.zmetadata`` file + store (in the `zarr.json` for Zarr format 3 and in the `.zmetadata` file for Zarr format 2). - To explicitly require consolidated metadata, set ``use_consolidated=True``, + To explicitly require consolidated metadata, set `use_consolidated=True`, which will raise an exception if consolidated metadata is not found. - To explicitly *not* use consolidated metadata, set ``use_consolidated=False``, + To explicitly *not* use consolidated metadata, set `use_consolidated=False`, which will fall back to using the regular, non consolidated metadata. Zarr format 2 allowed configuring the key storing the consolidated metadata - (``.zmetadata`` by default). Specify the custom key as ``use_consolidated`` + (`.zmetadata` by default). Specify the custom key as `use_consolidated` to load consolidated metadata from a non-default key. Returns @@ -587,12 +587,12 @@ def create_group( path : str, optional Group path within store. overwrite : bool, optional - If True, pre-existing data at ``path`` will be deleted before + If True, pre-existing data at `path` will be deleted before creating the group. zarr_format : {2, 3, None}, optional The zarr format to use when saving. - If no ``zarr_format`` is provided, the default format will be used. - This default can be changed by modifying the value of ``default_zarr_format`` + If no `zarr_format` is provided, the default format will be used. + This default can be changed by modifying the value of `default_zarr_format` in [`zarr.config`][zarr.config]. storage_options : dict If using an fsspec URL to create the store, these will be passed to @@ -662,27 +662,27 @@ 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 Primary compressor to compress chunk data. - Zarr format 2 only. Zarr format 3 arrays should use ``codecs`` instead. + Zarr format 2 only. Zarr format 3 arrays should use `codecs` instead. - If neither ``compressor`` nor ``filters`` are provided, the default compressor + If neither `compressor` nor `filters` are provided, the default compressor [`zarr.codecs.ZstdCodec`][] is used. - If ``compressor`` is set to ``None``, no compression is used. + If `compressor` is set to `None`, no compression is used. 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. + 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. + If not specified, the `array.order` parameter in the global config will be used. store : StoreLike or None, default=None StoreLike object to open. See the [storage documentation in the user guide][user-guide-store-like] @@ -690,12 +690,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 @@ -708,14 +708,14 @@ def create( For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter. - The default value of ``"auto"`` instructs Zarr to use a default based on the data + The default value of `"auto"` instructs Zarr to use a default 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 [`zarr.dtype.VariableLengthUTF8`][] or [`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``. + 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 @@ -731,17 +731,17 @@ 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. + 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. + Deprecated in favor of the `config` keyword argument. + Pass `{'write_empty_chunks': }` to `create` instead of using this parameter. If True, all chunks will be stored regardless of their contents. If False, each chunk is compared to the array's fill value prior to storing. If a chunk is uniformly equal to the fill value, then 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 creating an array. The default is ``None``, + 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 @@ -754,15 +754,15 @@ def create( 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", "/")``. + 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. + 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())``; + For most data types, the default codecs are the tuple `(BytesCodec(), ZstdCodec())`; data types that require a special [`zarr.abc.codec.ArrayBytesCodec`][], like variable-length strings or bytes, will use the [`zarr.abc.codec.ArrayBytesCodec`][] required for the data type instead of [`zarr.codecs.BytesCodec`][]. dimension_names : Iterable[str | None] | None = None @@ -849,24 +849,24 @@ def create_array( [storage documentation in the user guide][user-guide-store-like] for a description of all valid StoreLike values. name : str or None, optional - The name of the array within the store. If ``name`` is ``None``, the array will be located + The name of the array within the store. If `name` 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. + Shape of the array. Must be `None` if `data` is provided. dtype : ZDTypeLike | None - Data type of the array. Must be ``None`` if ``data`` is provided. + 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``. + `shape` and `dtype` parameters must be `None`. chunks : tuple[int, ...] | Sequence[Sequence[int]] | Literal["auto"], default="auto" Chunk shape of the array. If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype. A nested list of per-dimension edge sizes creates a rectilinear grid. Rectilinear chunk grids are experimental and must be explicitly enabled - with ``zarr.config.set({'array.rectilinear_chunks': True})`` while the + with `zarr.config.set({'array.rectilinear_chunks': True})` while the feature is stabilizing. shards : tuple[int, ...], optional - Shard shape of the array. The default value of ``None`` results in no sharding at all. + 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. @@ -879,35 +879,35 @@ def create_array( For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter. - The default value of ``"auto"`` instructs Zarr to use a default based on the data + The default value of `"auto"` instructs Zarr to use a default 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 [`zarr.dtype.VariableLengthUTF8`][] or [`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``. + 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 may 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`` + 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 [`zarr.config`][zarr.config]. - Use ``None`` to omit default compressors. + 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. + If no `compressor` is provided, a default compressor will be used. in [`zarr.config`][zarr.config]. - Use ``None`` to omit the default compressor. + Use `None` to omit the default compressor. serializer : dict[str, JSON] | ArrayBytesCodec, optional Array-to-bytes codec to use for encoding the array data. Zarr 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`` + 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 [`zarr.config`][zarr.config]. fill_value : Any, optional Fill value for the array. @@ -916,17 +916,17 @@ def create_array( 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 [`zarr.config`][zarr.config]. + 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 [`zarr.config`][zarr.config]. zarr_format : {2, 3}, optional The zarr format to use when saving. attributes : dict, optional Attributes for the array. 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": "."}}``. + 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. @@ -935,13 +935,13 @@ 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 - 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 + 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 @@ -1024,10 +1024,10 @@ def from_array( The array to copy. write_data : bool, default True Whether to copy the data from the input array to the new array. - If ``write_data`` is ``False``, the new array will be created with the same metadata as the + If `write_data` is `False`, the new array will be created with the same metadata as the input array, but without any data. name : str or None, optional - The name of the array within the store. If ``name`` is ``None``, the array will be located + The name of the array within the store. If `name` is `None`, the array will be located at the root of the store. chunks : tuple[int, ...] or Sequence[Sequence[int]] or "auto" or "keep", optional Chunk shape of the array. @@ -1038,7 +1038,7 @@ def from_array( - tuple[int, ...]: A tuple of integers representing the chunk shape (regular grid). - Sequence[Sequence[int]]: Per-dimension chunk edge lists (rectilinear grid). Rectilinear chunk grids are experimental and must be explicitly enabled - with ``zarr.config.set({'array.rectilinear_chunks': True})`` while the + with `zarr.config.set({'array.rectilinear_chunks': True})` while the feature is stabilizing. If not specified, defaults to "keep" if data is a zarr Array, otherwise "auto". @@ -1063,16 +1063,16 @@ def from_array( For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter. - 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"``, + 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 ``()``. + 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 [`zarr.dtype.VariableLengthUTF8`][] or [`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``. + 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. @@ -1089,17 +1089,17 @@ def from_array( - "auto": Automatically determine the compressors based on the array's dtype. - "keep": Retain the compressors of the input array if it is a zarr Array. - If no ``compressors`` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto". + If no `compressors` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto". serializer : dict[str, JSON] | ArrayBytesCodec or "auto" or "keep", 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. Following values are supported: - - dict[str, JSON]: A dict representation of an ``ArrayBytesCodec``. - - ArrayBytesCodec: An instance of ``ArrayBytesCodec``. + - dict[str, JSON]: A dict representation of an `ArrayBytesCodec`. + - ArrayBytesCodec: An instance of `ArrayBytesCodec`. - "auto": a default serializer will be used. These defaults can be changed by modifying the value of - ``array.v3_default_serializer`` in [`zarr.config`][zarr.config]. + `array.v3_default_serializer` in [`zarr.config`][zarr.config]. - "keep": Retain the serializer of the input array if it is a zarr Array. fill_value : Any, optional @@ -1110,7 +1110,7 @@ def from_array( 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'}``. + order for Zarr format 3 arrays is via the `config` parameter, e.g. `{'config': 'C'}`. If not specified, defaults to the memory order of the data array. zarr_format : {2, 3}, optional The zarr format to use when saving. @@ -1120,8 +1120,8 @@ def from_array( If not specified, defaults to the attributes of the data 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": "."}}``. + For Zarr format 3, the default is `{"name": "default", "separator": "/"}}`. + 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] | None diff --git a/src/zarr/core/array.py b/src/zarr/core/array.py index f75ef72415..4abf46f9dc 100644 --- a/src/zarr/core/array.py +++ b/src/zarr/core/array.py @@ -160,7 +160,7 @@ from zarr.types import AnyArray, AnyAsyncArray, ArrayV2, ArrayV3, AsyncArrayV2, AsyncArrayV3 -# Array and AsyncArray are defined in the base ``zarr`` namespace +# Array and AsyncArray are defined in the base `zarr` namespace __all__ = [ "DEFAULT_FILL_VALUE", "create_codec_pipeline", @@ -330,8 +330,8 @@ async def _prepare_overwrite( """ Prepare a store path for writing a new node. - If ``overwrite`` is true and the store supports deletes, any existing node at - ``store_path`` is deleted. Otherwise, the absence of an existing node is enforced + If `overwrite` is true and the store supports deletes, any existing node at + `store_path` is deleted. Otherwise, the absence of an existing node is enforced (raising if one is present). """ if overwrite and store_path.store.supports_deletes: @@ -861,10 +861,10 @@ def read_chunk_sizes(self) -> tuple[tuple[int, ...], ...]: Boundary chunks that extend past the array shape are clipped, so the last size along a dimension may be smaller than the declared - chunk size. This matches the dask ``Array.chunks`` convention. + chunk size. This matches the dask `Array.chunks` convention. When sharding is used, returns the inner chunk sizes. - Otherwise, returns the outer chunk sizes (same as ``write_chunk_sizes``). + Otherwise, returns the outer chunk sizes (same as `write_chunk_sizes`). Returns ------- @@ -894,7 +894,7 @@ def write_chunk_sizes(self) -> tuple[tuple[int, ...], ...]: Always returns the outer chunk sizes, regardless of sharding. Boundary chunks that extend past the array shape are clipped, so the last size along a dimension may be smaller than the declared - chunk size. This matches the dask ``Array.chunks`` convention. + chunk size. This matches the dask `Array.chunks` convention. Returns ------- @@ -1433,7 +1433,7 @@ def nbytes(self) -> int: ----- This value is calculated by multiplying the number of elements in the array and the size of each element, the latter of which is determined by the dtype of the array. - For this reason, ``nbytes`` will likely be inaccurate for arrays with variable-length + For this reason, `nbytes` will likely be inaccurate for arrays with variable-length dtypes. It is not possible to determine the size of an array with variable-length elements from the shape and dtype alone. """ @@ -2035,10 +2035,10 @@ def read_chunk_sizes(self) -> tuple[tuple[int, ...], ...]: Boundary chunks that extend past the array shape are clipped, so the last size along a dimension may be smaller than the declared - chunk size. This matches the dask ``Array.chunks`` convention. + chunk size. This matches the dask `Array.chunks` convention. When sharding is used, returns the inner chunk sizes. - Otherwise, returns the outer chunk sizes (same as ``write_chunk_sizes``). + Otherwise, returns the outer chunk sizes (same as `write_chunk_sizes`). Returns ------- @@ -2062,7 +2062,7 @@ def write_chunk_sizes(self) -> tuple[tuple[int, ...], ...]: Always returns the outer chunk sizes, regardless of sharding. Boundary chunks that extend past the array shape are clipped, so the last size along a dimension may be smaller than the declared - chunk size. This matches the dask ``Array.chunks`` convention. + chunk size. This matches the dask `Array.chunks` convention. Returns ------- @@ -2280,7 +2280,7 @@ def nbytes(self) -> int: ----- This value is calculated by multiplying the number of elements in the array and the size of each element, the latter of which is determined by the dtype of the array. - For this reason, ``nbytes`` will likely be inaccurate for arrays with variable-length + For this reason, `nbytes` will likely be inaccurate for arrays with variable-length dtypes. It is not possible to determine the size of an array with variable-length elements from the shape and dtype alone. """ @@ -2294,7 +2294,7 @@ def nchunks_initialized(self) -> int: This value is calculated as the product of the number of initialized shards and the number of chunks per shard. For arrays that do not use sharding, the number of chunks per shard is effectively 1, and in that case the number of chunks initialized is the same as the number of stored objects associated with an - array. For a direct count of the number of initialized stored objects, see ``nshards_initialized``. + array. For a direct count of the number of initialized stored objects, see `nshards_initialized`. Returns ------- @@ -3974,7 +3974,7 @@ def info_complete(self) -> Any: """ Returns all the information about an array, including information from the Store. - In addition to the statically known information like ``name`` and ``zarr_format``, + In addition to the statically known information like `name` and `zarr_format`, this includes additional information like the size of the array in bytes and the number of chunks written. @@ -4092,10 +4092,10 @@ async def from_array( The array to copy. write_data : bool, default True Whether to copy the data from the input array to the new array. - If ``write_data`` is ``False``, the new array will be created with the same metadata as the + If `write_data` is `False`, the new array will be created with the same metadata as the input array, but without any data. name : str or None, optional - The name of the array within the store. If ``name`` is ``None``, the array will be located + The name of the array within the store. If `name` is `None`, the array will be located at the root of the store. chunks : tuple[int, ...] or Sequence[Sequence[int]] or "auto" or "keep", optional Chunk shape of the array. @@ -4106,7 +4106,7 @@ async def from_array( - tuple[int, ...]: A tuple of integers representing the chunk shape (regular grid). - Sequence[Sequence[int]]: Per-dimension chunk edge lists (rectilinear grid). Rectilinear chunk grids are experimental and must be explicitly enabled - with ``zarr.config.set({'array.rectilinear_chunks': True})`` while the + with `zarr.config.set({'array.rectilinear_chunks': True})` while the feature is stabilizing. If not specified, defaults to "keep" if data is a zarr Array, otherwise "auto". @@ -4131,16 +4131,16 @@ async def from_array( For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter. - 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"``, + 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 ``()``. + 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 [`zarr.dtype.VariableLengthUTF8`][] or [`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``. + 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. @@ -4157,17 +4157,17 @@ async def from_array( - "auto": Automatically determine the compressors based on the array's dtype. - "keep": Retain the compressors of the input array if it is a zarr Array. - If no ``compressors`` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto". + If no `compressors` are provided, defaults to "keep" if data is a zarr Array, otherwise "auto". serializer : dict[str, JSON] | ArrayBytesCodec or "auto" or "keep", 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. Following values are supported: - - dict[str, JSON]: A dict representation of an ``ArrayBytesCodec``. - - ArrayBytesCodec: An instance of ``ArrayBytesCodec``. + - dict[str, JSON]: A dict representation of an `ArrayBytesCodec`. + - ArrayBytesCodec: An instance of `ArrayBytesCodec`. - "auto": a default serializer will be used. These defaults can be changed by modifying the value of - ``array.v3_default_serializer`` in [`zarr.config`][zarr.config]. + `array.v3_default_serializer` in [`zarr.config`][zarr.config]. - "keep": Retain the serializer of the input array if it is a zarr Array. fill_value : Any, optional @@ -4178,7 +4178,7 @@ async def from_array( 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'}``. + order for Zarr format 3 arrays is via the `config` parameter, e.g. `{'config': 'C'}`. If not specified, defaults to the memory order of the data array. zarr_format : {2, 3}, optional The zarr format to use when saving. @@ -4188,8 +4188,8 @@ async def from_array( If not specified, defaults to the attributes of the data 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": "."}}``. + For Zarr format 3, the default is `{"name": "default", "separator": "/"}}`. + 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] | None @@ -4367,7 +4367,7 @@ async def init_array( 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. + 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. @@ -4379,26 +4379,26 @@ async def init_array( For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter. - The default value of ``"auto"`` instructs Zarr to use a default based on the data + The default value of `"auto"` instructs Zarr to use a default 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 [`zarr.dtype.VariableLengthUTF8`][] or [`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``. + 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. - The default value of ``"auto"`` instructs Zarr to use a default of [`zarr.codecs.ZstdCodec`][]. + The default value of `"auto"` instructs Zarr to use a default of [`zarr.codecs.ZstdCodec`][]. - To create an array with no compressors, provide an empty iterable or the value ``None``. + 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. - The default value of ``"auto"`` instructs Zarr to use a default codec based on the data type of the array. + 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 [`zarr.codecs.BytesCodec`][]. For [`zarr.dtype.VariableLengthUTF8`][], the default codec is [`zarr.codecs.VlenUTF8Codec`][]. For [`zarr.dtype.VariableLengthBytes`][], the default codec is [`zarr.codecs.VlenBytesCodec`][]. @@ -4409,17 +4409,17 @@ async def init_array( 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 [`zarr.config`][zarr.config]. + 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 [`zarr.config`][zarr.config]. zarr_format : {2, 3}, optional The zarr format to use when saving. attributes : dict, optional Attributes for the array. 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": "."}}``. + 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. @@ -4427,7 +4427,7 @@ async def init_array( Whether to overwrite an array with the same name in the store, if one exists. config : ArrayConfigLike or None, default=None Configuration for this array. - If ``None``, the default array runtime configuration will be used. This default + If `None`, the default array runtime configuration will be used. This default is stored in the global configuration object. Returns @@ -4589,24 +4589,24 @@ async def create_array( [storage documentation in the user guide][user-guide-store-like] for a description of all valid StoreLike values. name : str or None, optional - The name of the array within the store. If ``name`` is ``None``, the array will be located + The name of the array within the store. If `name` 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. + Shape of the array. Must be `None` if `data` is provided. dtype : ZDTypeLike | None - Data type of the array. Must be ``None`` if ``data`` is provided. + 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``. + `shape` and `dtype` parameters must be `None`. chunks : tuple[int, ...] | Sequence[Sequence[int]] | Literal["auto"], default="auto" Chunk shape of the array. If chunks is "auto", a chunk shape is guessed based on the shape of the array and the dtype. A nested list of per-dimension edge sizes creates a rectilinear grid. Rectilinear chunk grids are experimental and must be explicitly enabled - with ``zarr.config.set({'array.rectilinear_chunks': True})`` while the + with `zarr.config.set({'array.rectilinear_chunks': True})` while the feature is stabilizing. shards : tuple[int, ...], optional - Shard shape of the array. The default value of ``None`` results in no sharding at all. + 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. @@ -4619,35 +4619,35 @@ async def create_array( For Zarr format 2, a "filter" can be any numcodecs codec; you should ensure that the order of your filters is consistent with the behavior of each filter. - The default value of ``"auto"`` instructs Zarr to use a default based on the data + The default value of `"auto"` instructs Zarr to use a default 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 [`zarr.dtype.VariableLengthUTF8`][] or [`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``. + 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 may 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`` + 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 [`zarr.config`][zarr.config]. - Use ``None`` to omit default compressors. + 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. + If no `compressor` is provided, a default compressor will be used. in [`zarr.config`][zarr.config]. - Use ``None`` to omit the default compressor. + Use `None` to omit the default compressor. serializer : dict[str, JSON] | ArrayBytesCodec, optional Array-to-bytes codec to use for encoding the array data. Zarr 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`` + 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 [`zarr.config`][zarr.config]. fill_value : Any, optional Fill value for the array. @@ -4656,17 +4656,17 @@ async def create_array( 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 [`zarr.config`][zarr.config]. + 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 [`zarr.config`][zarr.config]. zarr_format : {2, 3}, optional The zarr format to use when saving. attributes : dict, optional Attributes for the array. 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": "."}}``. + 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. @@ -4675,13 +4675,13 @@ 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 - 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 + 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 @@ -4879,7 +4879,7 @@ def default_compressors_v3(dtype: ZDType[Any, Any]) -> tuple[BytesBytesCodec, .. """ Given a data type, return the default compressors for that data type. - This is just a tuple containing ``ZstdCodec`` + This is just a tuple containing `ZstdCodec` """ return (ZstdCodec(),) @@ -4888,12 +4888,12 @@ def default_serializer_v3(dtype: ZDType[Any, Any]) -> ArrayBytesCodec: """ Given a data type, return the default serializer for that data type. - The default serializer for most data types is the ``BytesCodec``, which may or may not be + The default serializer for most data types is the `BytesCodec`, which may or may not be parameterized with an endianness, depending on whether the data type has endianness. Variable - length strings and variable length bytes have hard-coded serializers -- ``VLenUTF8Codec`` and - ``VLenBytesCodec``, respectively. + length strings and variable length bytes have hard-coded serializers -- `VLenUTF8Codec` and + `VLenBytesCodec`, respectively. - Structured data types with multi-byte fields use ``BytesCodec`` with little-endian encoding. + Structured data types with multi-byte fields use `BytesCodec` with little-endian encoding. """ serializer: ArrayBytesCodec = BytesCodec(endian=None) @@ -4917,7 +4917,7 @@ def default_filters_v2(dtype: ZDType[Any, Any]) -> tuple[Numcodec] | None: Given a data type, return the default filters for that data type. For data types that require an object codec, namely variable length data types, - this is a tuple containing the object codec. Otherwise it's ``None``. + this is a tuple containing the object codec. Otherwise it's `None`. """ if isinstance(dtype, HasObjectCodec): if dtype.object_codec_id == "vlen-bytes": @@ -4938,7 +4938,7 @@ def default_compressor_v2(dtype: ZDType[Any, Any]) -> Numcodec: """ Given a data type, return the default compressors for that data type. - This is just the numcodecs ``Zstd`` codec. + This is just the numcodecs `Zstd` codec. """ from numcodecs import Zstd @@ -5095,7 +5095,7 @@ def _parse_data_params( dtype: ZDTypeLike | None, ) -> tuple[np.ndarray[Any, np.dtype[Any]] | None, ShapeLike, ZDTypeLike]: """ - Ensure an array-like ``data`` parameter is consistent with the ``dtype`` and ``shape`` + Ensure an array-like `data` parameter is consistent with the `dtype` and `shape` parameters. """ if data is None: diff --git a/src/zarr/registry.py b/src/zarr/registry.py index 48f60fabd7..c2c0eb2921 100644 --- a/src/zarr/registry.py +++ b/src/zarr/registry.py @@ -196,9 +196,9 @@ def _resolve_codec(data: dict[str, JSON]) -> Codec: def _parse_bytes_bytes_codec(data: dict[str, JSON] | Codec) -> BytesBytesCodec: """ - Normalize the input to a ``BytesBytesCodec`` instance. - If the input is already a ``BytesBytesCodec``, it is returned as is. If the input is a dict, it - is converted to a ``BytesBytesCodec`` instance via the ``_resolve_codec`` function. + Normalize the input to a `BytesBytesCodec` instance. + If the input is already a `BytesBytesCodec`, it is returned as is. If the input is a dict, it + is converted to a `BytesBytesCodec` instance via the `_resolve_codec` function. """ from zarr.abc.codec import BytesBytesCodec @@ -216,9 +216,9 @@ def _parse_bytes_bytes_codec(data: dict[str, JSON] | Codec) -> BytesBytesCodec: def _parse_array_bytes_codec(data: dict[str, JSON] | Codec) -> ArrayBytesCodec: """ - Normalize the input to a ``ArrayBytesCodec`` instance. - If the input is already a ``ArrayBytesCodec``, it is returned as is. If the input is a dict, it - is converted to a ``ArrayBytesCodec`` instance via the ``_resolve_codec`` function. + Normalize the input to a `ArrayBytesCodec` instance. + If the input is already a `ArrayBytesCodec`, it is returned as is. If the input is a dict, it + is converted to a `ArrayBytesCodec` instance via the `_resolve_codec` function. """ from zarr.abc.codec import ArrayBytesCodec @@ -236,9 +236,9 @@ def _parse_array_bytes_codec(data: dict[str, JSON] | Codec) -> ArrayBytesCodec: def _parse_array_array_codec(data: dict[str, JSON] | Codec) -> ArrayArrayCodec: """ - Normalize the input to a ``ArrayArrayCodec`` instance. - If the input is already a ``ArrayArrayCodec``, it is returned as is. If the input is a dict, it - is converted to a ``ArrayArrayCodec`` instance via the ``_resolve_codec`` function. + Normalize the input to a `ArrayArrayCodec` instance. + If the input is already a `ArrayArrayCodec`, it is returned as is. If the input is a dict, it + is converted to a `ArrayArrayCodec` instance via the `_resolve_codec` function. """ from zarr.abc.codec import ArrayArrayCodec diff --git a/src/zarr/storage/_common.py b/src/zarr/storage/_common.py index 7e9c035c69..ed554327cd 100644 --- a/src/zarr/storage/_common.py +++ b/src/zarr/storage/_common.py @@ -84,11 +84,11 @@ async def open(cls, store: Store, path: str, mode: AccessModeLiteral | None = No The accepted values are: - - ``'r'``: read only (must exist) - - ``'r+'``: read/write (must exist) - - ``'a'``: read/write (create if doesn't exist) - - ``'w'``: read/write (overwrite if exists) - - ``'w-'``: read/write (create if doesn't exist). + - `'r'`: read only (must exist) + - `'r+'`: read/write (must exist) + - `'a'`: read/write (create if doesn't exist) + - `'w'`: read/write (overwrite if exists) + - `'w-'`: read/write (create if doesn't exist). Raises ------ @@ -209,7 +209,7 @@ async def delete_dir(self) -> None: async def set_if_not_exists(self, default: Buffer) -> None: """ - Store a key to ``value`` if the key is not already present. + Store a key to `value` if the key is not already present. Parameters ---------- @@ -250,7 +250,7 @@ def get_sync( prototype: BufferPrototype | None = None, byte_range: ByteRequest | None = None, ) -> Buffer | None: - """Synchronous read — delegates to ``self.store.get_sync(self.path, ...)``.""" + """Synchronous read — delegates to `self.store.get_sync(self.path, ...)`.""" if not isinstance(self.store, SupportsGetSync): raise TypeError(f"Store {type(self.store).__name__} does not support synchronous get.") if prototype is None: @@ -258,13 +258,13 @@ def get_sync( return self.store.get_sync(self.path, prototype=prototype, byte_range=byte_range) def set_sync(self, value: Buffer) -> None: - """Synchronous write — delegates to ``self.store.set_sync(self.path, value)``.""" + """Synchronous write — delegates to `self.store.set_sync(self.path, value)`.""" if not isinstance(self.store, SupportsSetSync): raise TypeError(f"Store {type(self.store).__name__} does not support synchronous set.") self.store.set_sync(self.path, value) def delete_sync(self) -> None: - """Synchronous delete — delegates to ``self.store.delete_sync(self.path)``.""" + """Synchronous delete — delegates to `self.store.delete_sync(self.path)`.""" if not isinstance(self.store, SupportsDeleteSync): raise TypeError( f"Store {type(self.store).__name__} does not support synchronous delete."