zarr.array from from an existing zarr.Array

src/zarr/__init__.py

@@ -10,6 +10,7 @@
  create_group,
  empty,
  empty_like,
+ from_array,
  full,
  full_like,
  group,
@@ -52,6 +53,7 @@
  "create_group",
  "empty",
  "empty_like",
+ "from_array",
  "full",
  "full_like",
  "group",

src/zarr/api/asynchronous.py

@@ -9,7 +9,7 @@
 import numpy.typing as npt
 from typing_extensions import deprecated
 
-from zarr.core.array import Array, AsyncArray, create_array, get_array_metadata
+from zarr.core.array import Array, AsyncArray, create_array, from_array, get_array_metadata
 from zarr.core.array_spec import ArrayConfig, ArrayConfigLike
 from zarr.core.buffer import NDArrayLike
 from zarr.core.common import (
@@ -50,6 +50,7 @@
  "create_array",
  "empty",
  "empty_like",
+ "from_array",
  "full",
  "full_like",
  "group",
@@ -527,7 +528,7 @@ async def tree(grp: AsyncGroup, expand: bool | None = None, level: int | None =
 
 
 async def array(
- data: npt.ArrayLike, **kwargs: Any
+ data: npt.ArrayLike | Array, **kwargs: Any
 ) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
  """Create an array filled with `data`.
 
@@ -544,6 +545,9 @@ async def array(
  The new array.
  """
 
+ if isinstance(data, Array):
+ return await from_array(data, **kwargs)
+
  # ensure data is array-like
  if not hasattr(data, "shape") or not hasattr(data, "dtype"):
  data = np.asanyarray(data)

src/zarr/api/synchronous.py

@@ -47,6 +47,7 @@
  "create_array",
  "empty",
  "empty_like",
+ "from_array",
  "full",
  "full_like",
  "group",
@@ -356,7 +357,7 @@ def tree(grp: Group, expand: bool | None = None, level: int | None = None) -> An
 
 
 # TODO: add type annotations for kwargs
-def array(data: npt.ArrayLike, **kwargs: Any) -> Array:
+def array(data: npt.ArrayLike | Array, **kwargs: Any) -> Array:
  """Create an array filled with `data`.
 
  Parameters
@@ -893,6 +894,138 @@ def create_array(
  )
 
 
+def from_array(
+ data: Array,
+ store: str | StoreLike,
+ *,
+ name: str | None = None,
+ chunks: ChunkCoords | Literal["auto"] = "auto",
+ shards: ShardsLike | None = None,
+ filters: FiltersLike = "auto",
+ compressors: CompressorsLike = "auto",
+ serializer: SerializerLike = "auto",
+ fill_value: Any | None = None,
+ order: MemoryOrder | None = None,
+ zarr_format: ZarrFormat | None = 3,
+ attributes: dict[str, JSON] | None = None,
+ chunk_key_encoding: ChunkKeyEncoding | ChunkKeyEncodingLike | None = None,
+ dimension_names: Iterable[str] | None = None,
+ storage_options: dict[str, Any] | None = None,
+ overwrite: bool = False,
+ config: ArrayConfig | ArrayConfigLike | None = None,
+) -> Array:
+ """Create an array from an existing array.
+
+ Parameters
+ ----------
+ data : Array
+ The array to copy.
+ store : str or Store
+ Store or path to directory in file system or name of zip file for the new 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.
+ chunks : ChunkCoords, optional
+ Chunk shape of the array.
+ If not specified, defaults to the chunk shape of the data array.
+ shards : ChunkCoords, optional
+ Shard shape of the array. The default value of ``None`` results in no sharding at all.
+ filters : Iterable[Codec], 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``.
+
+ 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, defaults to the filters of the data array.
+ 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.
+
+ For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
+ be provided for Zarr format 2.
+
+ If no ``compressors`` are provided, defaults to the compressors of the data array.
+ 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, defaults to the serializer of the input array.
+ fill_value : Any, optional
+ Fill value for the array.
+ If not specified, defaults to the fill value of the data 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 not specified, defaults to the memory order of the data array.
+ zarr_format : {2, 3}, optional
+ The zarr format to use when saving.
+ If not specified, defaults to the zarr format of the data array.
+ attributes : dict, optional
+ Attributes for the 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": "."}}``.
+ 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
+ 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.
+ 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.
+
+ Returns
+ -------
+ AsyncArray
+ The array.
+
+ Examples
+ --------
+ #TODO
+ """
+ return Array(
+ sync(
+ zarr.core.array.from_array(
+ data,
+ store,
+ name=name,
+ chunks=chunks,
+ shards=shards,
+ filters=filters,
+ compressors=compressors,
+ serializer=serializer,
+ fill_value=fill_value,
+ order=order,
+ zarr_format=zarr_format,
+ attributes=attributes,
+ chunk_key_encoding=chunk_key_encoding,
+ dimension_names=dimension_names,
+ storage_options=storage_options,
+ overwrite=overwrite,
+ config=config,
+ )
+ )
+ )
+
+
 # TODO: add type annotations for kwargs
 def empty(shape: ChunkCoords, **kwargs: Any) -> Array:
  """Create an empty array.

src/zarr/core/array.py

@@ -25,6 +25,7 @@
 import numpy.typing as npt
 from typing_extensions import deprecated
 
+import zarr
 from zarr._compat import _deprecate_positional_args
 from zarr.abc.codec import ArrayArrayCodec, ArrayBytesCodec, BytesBytesCodec, Codec
 from zarr.abc.store import Store, set_or_delete
@@ -3734,6 +3735,174 @@ class ShardsConfigParam(TypedDict):
 ShardsLike: TypeAlias = ChunkCoords | ShardsConfigParam | Literal["auto"]
 
 
+async def from_array(
+ data: Array,
+ store: str | StoreLike,
+ *,
+ name: str | None = None,
+ chunks: ChunkCoords | Literal["auto"] = "auto",
+ shards: ShardsLike | None = None,
+ filters: FiltersLike = "auto",
+ compressors: CompressorsLike = "auto",
+ serializer: SerializerLike = "auto",
+ fill_value: Any | None = None,
+ order: MemoryOrder | None = None,
+ zarr_format: ZarrFormat | None = 3,
+ attributes: dict[str, JSON] | None = None,
+ chunk_key_encoding: ChunkKeyEncoding | ChunkKeyEncodingLike | None = None,
+ dimension_names: Iterable[str] | None = None,
+ storage_options: dict[str, Any] | None = None,
+ overwrite: bool = False,
+ config: ArrayConfig | ArrayConfigLike | None = None,
+) -> AsyncArray[ArrayV2Metadata] | AsyncArray[ArrayV3Metadata]:
+ """Create an array from an existing array.
+
+ Parameters
+ ----------
+ data : Array
+ The array to copy.
+ store : str or Store
+ Store or path to directory in file system or name of zip file for the new 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.
+ chunks : ChunkCoords, optional
+ Chunk shape of the array.
+ If not specified, defaults to the chunk shape of the data array.
+ shards : ChunkCoords, optional
+ Shard shape of the array. The default value of ``None`` results in no sharding at all.
+ filters : Iterable[Codec], 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``.
+
+ 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, defaults to the filters of the data array.
+ 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.
+
+ For Zarr format 2, a "compressor" can be any numcodecs codec. Only a single compressor may
+ be provided for Zarr format 2.
+
+ If no ``compressors`` are provided, defaults to the compressors of the data array.
+ 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, defaults to the serializer of the input array.
+ fill_value : Any, optional
+ Fill value for the array.
+ If not specified, defaults to the fill value of the data 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 not specified, defaults to the memory order of the data array.
+ zarr_format : {2, 3}, optional
+ The zarr format to use when saving.
+ If not specified, defaults to the zarr format of the data array.
+ attributes : dict, optional
+ Attributes for the 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": "."}}``.
+ 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
+ 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.
+ 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.
+
+ Returns
+ -------
+ AsyncArray
+ The array.
+
+ Examples
+ --------
+ #TODO
+ """
+
+ # fill missing arguments with metadata of data Array
+ if chunks == "auto":
+ chunks = data.chunks
+ if filters is None:
+ filters = data.filters
+ if compressors is None:
+ compressors = data.compressors
+ if serializer is None:
+ serializer = data.serializer
+ if fill_value is None:
+ fill_value = data.fill_value
+ if order is None:
+ order = data.order
+ if zarr_format is None:
+ zarr_format = data.metadata.zarr_format
+ if chunk_key_encoding is None and zarr_format == data.metadata.zarr_format:
+ if data.metadata.zarr_format == 2:
+ chunk_key_encoding = {"name": "v2", "separator": data.metadata.dimension_separator}
+ else:
+ chunk_key_encoding = data.metadata.chunk_key_encoding
+ if dimension_names is None and data.metadata.zarr_format == 3:
+ dimension_names = data.metadata.dimension_names
+
+ new_array = await create_array(
+ store,
+ name=name,
+ shape=data.shape,
+ dtype=data.dtype,
+ chunks=chunks,
+ shards=shards,
+ filters=filters,
+ compressors=compressors,
+ serializer=(serializer or "auto"),
+ fill_value=fill_value,
+ order=order,
+ zarr_format=zarr_format,
+ attributes=attributes,
+ chunk_key_encoding=chunk_key_encoding,
+ dimension_names=dimension_names,
+ storage_options=storage_options,
+ overwrite=overwrite,
+ config=config,
+ )
+
+ async def _copy_region(chunk_coords: ChunkCoords | slice, _data: Array) -> None:
+ arr = await _data._async_array.getitem(chunk_coords)
+ await new_array.setitem(chunk_coords, arr)
+
+ if new_array.chunks == data.chunks:
+ # Stream data from the source array to the new array
+ await concurrent_map(
+ [(region, data) for region in data._iter_chunk_regions()],
+ _copy_region,
+ zarr.core.config.config.get("async.concurrency"),
+ )
+ else:
+ await _copy_region(slice(None), data)
+ return new_array
+
+
 async def create_array(
  store: str | StoreLike,
  *,