v3

NodeSpec

Bases: StrictBase

The base class for V3 ArraySpec and GroupSpec.

Attributes:

Name	Type	Description
zarr_format	Literal[3]	The Zarr version represented by this node. Must be 3.

ArraySpec

Bases: NodeSpec, Generic[TAttr]

A model of a Zarr Version 3 Array.

Attributes:

Name	Type	Description
node_type	Literal['array']	The node type. Must be the string 'array'.
attributes	TAttr	User-defined metadata associated with this array.
shape	Sequence[int]	The shape of this array.
data_type	str	The data type of this array.
chunk_grid	NamedConfig	A NamedConfig object defining the chunk shape of this array.
chunk_key_encoding	NamedConfig	A NamedConfig object defining the chunk_key_encoding for the array.
fill_value	FillValue	The fill value for this array.
codecs	Sequence[NamedConfig]	The sequence of codices for this array.
storage_transformers	Optional[Sequence[NamedConfig]]	An optional sequence of NamedConfig objects that define the storage transformers for this array.
dimension_names	Optional[Sequence[str]]	An optional sequence of strings that gives names to each axis of the array.

from_array classmethod

from_array(array, **kwargs)

Create an ArraySpec from a numpy array-like object.

Parameters:

Name	Type	Description	Default
array	object that conforms to the numpy array API.	The shape and dtype of this object will be used to construct an ArraySpec. If the chunks keyword argument is not given, the shape of the array will be used for the chunks.	required
**kwargs	keyword arguments to the ArraySpec class constructor.		{}

Returns:

Type	Description
An instance of ArraySpec with properties derived from the provided array.

Source code in src/pydantic_zarr/v3.py

@classmethod
def from_array(cls, array: npt.NDArray[Any], **kwargs):
    """
    Create an ArraySpec from a numpy array-like object.

    Parameters
    ----------
    array : object that conforms to the numpy array API.
        The shape and dtype of this object will be used to construct an ArraySpec.
        If the `chunks` keyword argument is not given, the shape of the array will
        be used for the chunks.
    **kwargs : keyword arguments to the ArraySpec class constructor.

    Returns
    -------
    An instance of ArraySpec with properties derived from the provided array.

    """
    default_chunks = RegularChunking(
        configuration=RegularChunkingConfig(chunk_shape=list(array.shape))
    )
    return cls(
        shape=array.shape,
        data_type=str(array.dtype),
        chunk_grid=kwargs.pop("chunks", default_chunks),
        attributes=kwargs.pop("attributes", {}),
        **kwargs,
    )

from_zarr classmethod

from_zarr(zarray)

Create an ArraySpec from a zarr array.

Parameters:

Name	Type	Description	Default
zarray	zarr array		required

Returns:

Type	Description
An instance of ArraySpec with properties derived from the provided zarr
array.

Source code in src/pydantic_zarr/v3.py

@classmethod
def from_zarr(cls, zarray: zarr.Array):
    """
    Create an ArraySpec from a zarr array.

    Parameters
    ----------
    zarray : zarr array

    Returns
    -------
    An instance of ArraySpec with properties derived from the provided zarr
    array.

    """
    raise NotImplementedError

to_zarr

to_zarr(store, path, overwrite=False)

Serialize an ArraySpec to a zarr array at a specific path in a zarr store.

Parameters:

Name	Type	Description	Default
store	instance of zarr.BaseStore	The storage backend that will manifest the array.	required
path	str	The location of the array inside the store.	required
overwrite	bool	Whether to overwrite an existing array or group at the path. If overwrite is False and an array or group already exists at the path, an exception will be raised. Defaults to False.	False

Returns:

Type	Description
A zarr array that is structurally identical to the ArraySpec.
This operation will create metadata documents in the store.

Source code in src/pydantic_zarr/v3.py

def to_zarr(
    self, store: BaseStore, path: str, overwrite: bool = False
) -> zarr.Array:
    """
    Serialize an ArraySpec to a zarr array at a specific path in a zarr store.

    Parameters
    ----------
    store : instance of zarr.BaseStore
        The storage backend that will manifest the array.
    path : str
        The location of the array inside the store.
    overwrite : bool
        Whether to overwrite an existing array or group at the path. If overwrite is
        False and an array or group already exists at the path, an exception will be
        raised. Defaults to False.

    Returns
    -------
    A zarr array that is structurally identical to the ArraySpec.
    This operation will create metadata documents in the store.
    """
    raise NotImplementedError

GroupSpec

Bases: NodeSpec, Generic[TAttr, TItem]

A model of a Zarr Version 3 Group.

Attributes:

Name	Type	Description
node_type	Literal['group']	The type of this node. Must be the string "group".
attributes	TAttr	The user-defined attributes of this group.
members	dict[str, TItem]	The members of this group. members is a dict with string keys and values that must inherit from either ArraySpec or GroupSpec.

from_zarr classmethod

from_zarr(group)

Create a GroupSpec from a zarr group. Subgroups and arrays contained in the zarr group will be converted to instances of GroupSpec and ArraySpec, respectively, and these spec instances will be stored in the .members attribute of the parent GroupSpec. This occurs recursively, so the entire zarr hierarchy below a given group can be represented as a GroupSpec.

Parameters:

Name	Type	Description	Default
group	zarr group		required

Returns:

Type	Description
An instance of GroupSpec that represents the structure of the zarr hierarchy.

Source code in src/pydantic_zarr/v3.py

@classmethod
def from_zarr(cls, group: zarr.Group) -> GroupSpec[TAttr, TItem]:
    """
    Create a GroupSpec from a zarr group. Subgroups and arrays contained in the zarr
    group will be converted to instances of GroupSpec and ArraySpec, respectively,
    and these spec instances will be stored in the .members attribute of the parent
    GroupSpec. This occurs recursively, so the entire zarr hierarchy below a given
    group can be represented as a GroupSpec.

    Parameters
    ----------
    group : zarr group

    Returns
    -------
    An instance of GroupSpec that represents the structure of the zarr hierarchy.
    """

    raise NotImplementedError

to_zarr

to_zarr(store, path, overwrite=False)

Serialize a GroupSpec to a zarr group at a specific path in a zarr store.

Parameters:

Name	Type	Description	Default
store	instance of zarr.BaseStore	The storage backend that will manifest the group and its contents.	required
path	str	The location of the group inside the store.	required
overwrite	bool	Whether to overwrite an existing array or group at the path. If overwrite is False and an array or group already exists at the path, an exception will be raised. Defaults to False.	False

Returns:

Type	Description
A zarr group that is structurally identical to the GroupSpec.
This operation will create metadata documents in the store.

Source code in src/pydantic_zarr/v3.py

def to_zarr(self, store: BaseStore, path: str, overwrite: bool = False):
    """
    Serialize a GroupSpec to a zarr group at a specific path in a zarr store.

    Parameters
    ----------
    store : instance of zarr.BaseStore
        The storage backend that will manifest the group and its contents.
    path : str
        The location of the group inside the store.
    overwrite : bool
        Whether to overwrite an existing array or group at the path. If overwrite is
        False and an array or group already exists at the path, an exception will be
        raised. Defaults to False.

    Returns
    -------
    A zarr group that is structurally identical to the GroupSpec.
    This operation will create metadata documents in the store.
    """
    raise NotImplementedError

from_zarr

from_zarr(element)

Recursively parse a Zarr group or Zarr array into an ArraySpec or GroupSpec.

Parameters:

Name	Type	Description	Default
element	a zarr Array or zarr Group		required

Returns:

Type	Description
An instance of GroupSpec or ArraySpec that represents the
structure of the zarr group or array.

Source code in src/pydantic_zarr/v3.py

def from_zarr(element: Union[zarr.Array, zarr.Group]) -> Union[ArraySpec, GroupSpec]:
    """
    Recursively parse a Zarr group or Zarr array into an ArraySpec or GroupSpec.

    Parameters
    ---------
    element : a zarr Array or zarr Group

    Returns
    -------
    An instance of GroupSpec or ArraySpec that represents the
    structure of the zarr group or array.
    """

    raise NotImplementedError

to_zarr

to_zarr(spec, store, path, overwrite=False)

Serialize a GroupSpec or ArraySpec to a zarr group or array at a specific path in a zarr store.

Parameters:

Name	Type	Description	Default
spec	GroupSpec or ArraySpec	The GroupSpec or ArraySpec that will be serialized to storage.	required
store	instance of zarr.BaseStore	The storage backend that will manifest the group or array.	required
path	str	The location of the group or array inside the store.	required
overwrite	bool	Whether to overwrite an existing array or group at the path. If overwrite is False and an array or group already exists at the path, an exception will be raised. Defaults to False.	False

Returns:

Type	Description
A zarr Group or Array that is structurally equivalent to the spec object.
This operation will create metadata documents in the store.

Source code in src/pydantic_zarr/v3.py

def to_zarr(
    spec: Union[ArraySpec, GroupSpec],
    store: BaseStore,
    path: str,
    overwrite: bool = False,
) -> Union[zarr.Array, zarr.Group]:
    """
    Serialize a GroupSpec or ArraySpec to a zarr group or array at a specific path in
    a zarr store.

    Parameters
    ----------
    spec : GroupSpec or ArraySpec
        The GroupSpec or ArraySpec that will be serialized to storage.
    store : instance of zarr.BaseStore
        The storage backend that will manifest the group or array.
    path : str
        The location of the group or array inside the store.
    overwrite : bool
        Whether to overwrite an existing array or group at the path. If overwrite is
        False and an array or group already exists at the path, an exception will be
        raised. Defaults to False.

    Returns
    -------
    A zarr Group or Array that is structurally equivalent to the spec object.
    This operation will create metadata documents in the store.

    """
    if isinstance(spec, ArraySpec):
        result = spec.to_zarr(store, path, overwrite=overwrite)
    elif isinstance(spec, GroupSpec):
        result = spec.to_zarr(store, path, overwrite=overwrite)
    else:
        msg = ("Invalid argument for spec. Expected an instance of GroupSpec or ",)
        f"ArraySpec, got {type(spec)} instead."
        raise ValueError(msg)

    return result