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,13 +545,16 @@ 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)
 
     # setup dtype
     kw_dtype = kwargs.get("dtype")
-    if kw_dtype is None:
+    if kw_dtype is None and hasattr(data, "dtype"):
         kwargs["dtype"] = data.dtype
     else:
         kwargs["dtype"] = kw_dtype

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 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 zarr_format == 3 and serializer == "auto":
+        serializer = cast(SerializerLike, data.serializer)
+    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,
     *,