zarr.dtype#

Attributes#

data_type_registry

Exceptions#

DataTypeValidationError

Inappropriate argument value (of correct type).

Classes#

`Bool`	A Zarr data type for arrays containing booleans.
`Complex128`	A Zarr data type for arrays containing 64 bit complex floats.
`Complex64`	A Zarr data type for arrays containing 64 bit complex floats.
`DateTime64`	A Zarr data type for arrays containing NumPy Datetime64 data.
`DateTime64JSON_V2`	A wrapper around the JSON representation of the `DateTime64` data type in Zarr V2.
`DateTime64JSON_V3`	The JSON representation of the `numpy.datetime64` data type in Zarr V3.
`FixedLengthUTF32`	A Zarr data type for arrays containing fixed-length UTF-32 strings.
`FixedLengthUTF32JSON_V2`	A wrapper around the JSON representation of the `FixedLengthUTF32` data type in Zarr V2.
`FixedLengthUTF32JSON_V3`	The JSON representation of the `FixedLengthUTF32` data type in Zarr V3.
`Float16`	A Zarr data type for arrays containing 16-bit floating point numbers.
`Float32`	A Zarr data type for arrays containing 32-bit floating point numbers.
`Float64`	A Zarr data type for arrays containing 64-bit floating point numbers.
`Int16`	A Zarr data type for arrays containing 16-bit signed integers.
`Int32`	A Zarr data type for arrays containing 32-bit signed integers.
`Int64`	A Zarr data type for arrays containing 64-bit signed integers.
`Int8`	A Zarr data type for arrays containing 8-bit signed integers.
`NullTerminatedBytes`	A Zarr data type for arrays containing fixed-length null-terminated byte sequences.
`NullTerminatedBytesJSON_V3`	The JSON representation of the `NullTerminatedBytes` data type in Zarr V3.
`NullterminatedBytesJSON_V2`	A wrapper around the JSON representation of the `NullTerminatedBytes` data type in Zarr V2.
`RawBytes`	A Zarr data type for arrays containing fixed-length sequences of raw bytes.
`RawBytesJSON_V2`	A wrapper around the JSON representation of the `RawBytes` data type in Zarr V2.
`RawBytesJSON_V3`	The JSON representation of the `RawBytes` data type in Zarr V3.
`Structured`	A Zarr data type for arrays containing structured scalars, AKA "record arrays".
`StructuredJSON_V2`	A wrapper around the JSON representation of the `Structured` data type in Zarr V2.
`StructuredJSON_V3`	A JSON representation of a structured data type in Zarr V3.
`TimeDelta64`	A Zarr data type for arrays containing NumPy TimeDelta64 data.
`TimeDelta64JSON_V2`	A wrapper around the JSON representation of the `TimeDelta64` data type in Zarr V2.
`TimeDelta64JSON_V3`	The JSON representation of the `TimeDelta64` data type in Zarr V3.
`UInt16`	A Zarr data type for arrays containing 16-bit unsigned integers.
`UInt32`	A Zarr data type for arrays containing 32-bit unsigned integers.
`UInt64`	A Zarr data type for arrays containing 64-bit unsigned integers.
`UInt8`	A Zarr data type for arrays containing 8-bit unsigned integers.
`VariableLengthBytes`	A Zarr data type for arrays containing variable-length sequences of bytes.
`VariableLengthBytesJSON_V2`	A wrapper around the JSON representation of the `VariableLengthBytes` data type in Zarr V2.
`VariableLengthUTF8`	A Zarr data type for arrays containing variable-length UTF-8 strings.
`VariableLengthUTF8JSON_V2`	A wrapper around the JSON representation of the `VariableLengthUTF8` data type in Zarr V2.
`ZDType`	Abstract base class for wrapping native array data types, e.g. numpy dtypes

Functions#

parse_dtype(→ wrapper.ZDType[wrapper.TBaseDType, ...)

Convert the input as a ZDType.

Module Contents#

exception zarr.dtype.DataTypeValidationError[source]#

Bases: ValueError

Inappropriate argument value (of correct type).

class zarr.dtype.Bool[source]#

Bases: zarr.core.dtype.wrapper.ZDType[numpy.dtypes.BoolDType, numpy.bool_], zarr.core.dtype.common.HasItemSize

A Zarr data type for arrays containing booleans.

Wraps the np.dtypes.BoolDType data type. Scalars for this data type are instances of np.bool_.

Attributes:

_zarr_v3_nameLiteral[“bool”] = “bool”: The Zarr v3 name of the dtype.
_zarr_v2_nameLiteral["|b1"] = "|b1": The Zarr v2 name of the dtype, which is also a string representation of the boolean dtype used by NumPy.
dtype_clsClassVar[type[np.dtypes.BoolDType]] = np.dtypes.BoolDType: The NumPy dtype class.

References

This class implements the boolean data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → numpy.bool_[source]#

Cast the input to a numpy boolean scalar.

Parameters:

dataobject: The data to cast.

Returns:

np.bool_: The numpy boolean scalar.

Raises:

TypeError: If the input cannot be converted to a numpy boolean.

default_scalar() → numpy.bool_[source]#

Get the default value for the boolean dtype.

Returns:

np.bool_: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → numpy.bool_[source]#

Read a JSON-serializable value as a numpy boolean scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

np.bool_: The numpy boolean scalar.

Raises:

TypeError: If the input is not a valid boolean type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an instance of Bool from an instance of np.dtypes.BoolDType.

Parameters:

dtypeTBaseDType: The NumPy boolean dtype instance to convert.

Returns:

Bool: An instance of Bool.

Raises:

DataTypeValidationError: If the provided dtype is not compatible with this ZDType.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['|b1'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['bool']

Serialize this Bool instance to JSON.

Parameters:

zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

DTypeConfig_V2[Literal["|b1"], None] | Literal["bool"]: The JSON representation of the Bool instance.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar( data: object, *, zarr_format: zarr.core.common.ZarrFormat, ) → bool[source]#

Convert a scalar to a python bool.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

bool: The JSON-serializable format.

to_native_dtype() → numpy.dtypes.BoolDType[source]#

Create a NumPy boolean dtype instance from this ZDType.

Returns:

np.dtypes.BoolDType: The NumPy boolean dtype.

dtype_cls#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Complex128[source]#

Bases: BaseComplex[numpy.dtypes.Complex128DType, numpy.complex128], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing 64 bit complex floats.

Wraps the np.dtypes.Complex128DType data type. Scalars for this data type are instances of np.complex128.

Attributes:

dtype_clsType[np.dtypes.Complex128DType]: The numpy dtype class for this data type.
_zarr_v3_nameClassVar[Literal[“complex128”]]: The name of this data type in Zarr V3.
_zarr_v2_namesClassVar[tuple[Literal[“>c16”], Literal[“<c16”]]]: The names of this data type in Zarr V2.

cast_scalar(data: object) → zarr.core.dtype.npy.common.TComplexScalar_co#

Attempt to cast a given object to a numpy complex scalar.

Parameters:

dataobject: The data to be cast to a numpy complex scalar.

Returns:

TComplexScalar_co: The data cast as a numpy complex scalar.

Raises:

TypeError: If the data cannot be converted to a numpy complex scalar.

default_scalar() → zarr.core.dtype.npy.common.TComplexScalar_co#

Get the default value, which is 0 cast to this dtype

Returns:

Int scalar: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.dtype.npy.common.TComplexScalar_co#

Read a JSON-serializable value as a numpy float.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

TScalar_co: The numpy float.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self#

Create an instance of this data type from a NumPy complex dtype.

Parameters:

dtypeTBaseDType: The native dtype to convert.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the dtype is not compatible with this data type.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[str, None]#

to_json(zarr_format: Literal[3]) → str

Serialize this object to a JSON-serializable representation.

Parameters:

zarr_formatZarrFormat: The Zarr format version. Supported values are 2 and 3.

Returns:

DTypeConfig_V2[str, None] | str: If zarr_format is 2, a dictionary with "name" and "object_codec_id" keys is returned. If zarr_format is 3, a string representation of the complex data type is returned.

Raises:

ValueError: If zarr_format is not 2 or 3.

to_json_scalar( data: object, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.common.JSON#

Convert an object to a JSON-serializable float.

Parameters:

data_BaseScalar: The value to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

JSON: The JSON-serializable form of the complex number, which is a list of two floats, each of which is encoding according to a zarr-format-specific encoding.

to_native_dtype() → zarr.core.dtype.npy.common.TComplexDType_co#

Convert this class to a NumPy complex dtype with the appropriate byte order.

Returns:

TComplexDType_co: A NumPy data type object representing the complex data type with the specified byte order.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Complex64[source]#

Bases: BaseComplex[numpy.dtypes.Complex64DType, numpy.complex64]

A Zarr data type for arrays containing 64 bit complex floats.

Wraps the np.dtypes.Complex64DType data type. Scalars for this data type are instances of np.complex64.

Attributes:

dtype_clsType[np.dtypes.Complex64DType]: The numpy dtype class for this data type.
_zarr_v3_nameClassVar[Literal[“complex64”]]: The name of this data type in Zarr V3.
_zarr_v2_namesClassVar[tuple[Literal[“>c8”], Literal[“<c8”]]]: The names of this data type in Zarr V2.

cast_scalar(data: object) → zarr.core.dtype.npy.common.TComplexScalar_co#

Attempt to cast a given object to a numpy complex scalar.

Parameters:

dataobject: The data to be cast to a numpy complex scalar.

Returns:

TComplexScalar_co: The data cast as a numpy complex scalar.

Raises:

TypeError: If the data cannot be converted to a numpy complex scalar.

default_scalar() → zarr.core.dtype.npy.common.TComplexScalar_co#

Get the default value, which is 0 cast to this dtype

Returns:

Int scalar: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.dtype.npy.common.TComplexScalar_co#

Read a JSON-serializable value as a numpy float.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

TScalar_co: The numpy float.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self#

Create an instance of this data type from a NumPy complex dtype.

Parameters:

dtypeTBaseDType: The native dtype to convert.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the dtype is not compatible with this data type.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[str, None]#

to_json(zarr_format: Literal[3]) → str

Serialize this object to a JSON-serializable representation.

Parameters:

zarr_formatZarrFormat: The Zarr format version. Supported values are 2 and 3.

Returns:

DTypeConfig_V2[str, None] | str: If zarr_format is 2, a dictionary with "name" and "object_codec_id" keys is returned. If zarr_format is 3, a string representation of the complex data type is returned.

Raises:

ValueError: If zarr_format is not 2 or 3.

to_json_scalar( data: object, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.common.JSON#

Convert an object to a JSON-serializable float.

Parameters:

data_BaseScalar: The value to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

JSON: The JSON-serializable form of the complex number, which is a list of two floats, each of which is encoding according to a zarr-format-specific encoding.

to_native_dtype() → zarr.core.dtype.npy.common.TComplexDType_co#

Convert this class to a NumPy complex dtype with the appropriate byte order.

Returns:

TComplexDType_co: A NumPy data type object representing the complex data type with the specified byte order.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.DateTime64[source]#

Bases: TimeDTypeBase[numpy.dtypes.DateTime64DType, numpy.datetime64], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing NumPy Datetime64 data.

Wraps the np.dtypes.TimeDelta64DType data type. Scalars for this data type are instances of np.datetime64.

Attributes:

dtype_clsType[np.dtypesTimeDelta64DType]: The numpy dtype class for this data type.
unitDateTimeUnit: The unit of time for this data type.
scale_factorint: The scale factor for the time unit.

References

The Zarr V2 representation of this data type is defined in the Zarr V2 specification document.

The Zarr V3 representation of this data type is defined in the numpy.datetime64 specification document

cast_scalar(data: object) → numpy.datetime64[source]#

Cast the input to a scalar of this data type after a type check.

Parameters:

dataobject: The scalar value to cast.

Returns:

numpy.datetime64: The input cast to a NumPy datetime scalar.

Raises:

TypeError: If the data cannot be converted to a numpy datetime scalar.

default_scalar() → numpy.datetime64[source]#

Return the default scalar value for this data type.

Returns:

numpy.datetime64: The default scalar value, which is a ‘Not-a-Time’ (NaT) value

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → numpy.datetime64[source]#

Read a JSON-serializable value as a scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

numpy.datetime64: The numpy datetime scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self#

Create an instance of this class from a native NumPy data type.

Parameters:

dtypeTBaseDType: The native NumPy dtype to convert.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the dtype is not a valid representation of this class.

to_json(zarr_format: Literal[2]) → DateTime64JSON_V2[source]#

to_json(zarr_format: Literal[3]) → DateTime64JSON_V3

Serialize this data type to JSON.

Parameters:

zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

DateTime64JSON_V2 | DateTime64JSON_V3: The JSON representation of the data type.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert a python object to a JSON representation of a datetime64 or timedelta64 scalar.

Parameters:

dataobject: The python object to convert.
zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

int: The JSON representation of the scalar.

to_native_dtype() → BaseTimeDType_co#

Convert this data type to a NumPy temporal data type with the appropriate unit and scale factor.

Returns:

BaseTimeDType_co: A NumPy data type object representing the time data type with the specified unit, scale factor, and byte order.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

scale_factor: int = 1#

unit: zarr.core.dtype.npy.common.DateTimeUnit = 'generic'#

class zarr.dtype.DateTime64JSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[str, None]

A wrapper around the JSON representation of the DateTime64 data type in Zarr V2.

The name field of this class contains the value that would appear under the dtype field in Zarr V2 array metadata.

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": "<M8[10s]",
    "object_codec_id": None
}

name: typing_extensions.ReadOnly[TDTypeNameV2_co]#

object_codec_id: typing_extensions.ReadOnly[TObjectCodecID_co]#

class zarr.dtype.DateTime64JSON_V3[source]#

Bases: zarr.core.common.NamedConfig[Literal['numpy.datetime64'], TimeConfig]

The JSON representation of the numpy.datetime64 data type in Zarr V3.

References

This representation is defined in the numpy.datetime64 specification document.

Examples

{
    "name": "numpy.datetime64",
    "configuration": {
        "unit": "ms",
        "scale_factor": 1
        }
}

class zarr.dtype.FixedLengthUTF32[source]#

Bases: zarr.core.dtype.wrapper.ZDType[numpy.dtypes.StrDType[int], numpy.str_], zarr.core.dtype.common.HasEndianness, zarr.core.dtype.common.HasLength, zarr.core.dtype.common.HasItemSize

A Zarr data type for arrays containing fixed-length UTF-32 strings.

Wraps the np.dtypes.StrDType data type. Scalars for this data type are instances of np.str_.

Attributes:

dtype_clsType[np.dtypes.StrDType]: The NumPy dtype class for this data type.
_zarr_v3_nameClassVar[Literal[“fixed_length_utf32”]]: The name of this data type in Zarr V3.
code_point_bytesClassVar[int] = 4: The number of bytes per code point in UTF-32, which is 4.

cast_scalar(data: object) → numpy.str_[source]#

Cast the scalar value to the native scalar value.

Parameters:

dataobject: The scalar value.

Returns:

np.str_: The native scalar value.

default_scalar() → numpy.str_[source]#

Return the default scalar value for this data type.

Returns:

np.str_: The default scalar value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → numpy.str_[source]#

Convert the JSON representation of a scalar value to the native scalar value.

Parameters:

dataJSON: The JSON data.
zarr_formatZarrFormat: The Zarr format to use.

Returns:

np.str_: The native scalar value.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create a FixedLengthUTF32 from a NumPy data type.

Parameters:

dtypeTBaseDType: The NumPy data type.

Returns:

Self: An instance of this data type.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[str, None][source]#

to_json(zarr_format: Literal[3]) → FixedLengthUTF32JSON_V3

Convert the FixedLengthUTF32 instance to a JSON representation.

Parameters:

zarr_formatZarrFormat: The Zarr format to use.

Returns:

DTypeConfig_V2[str, None] | FixedLengthUTF32JSON_V3: The JSON representation of the data type.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → str[source]#

Convert the scalar value to a JSON representation.

Parameters:

dataobject: The scalar value.
zarr_formatZarrFormat: The Zarr format to use.

Returns:

str: The JSON representation of the scalar value.

to_native_dtype() → numpy.dtypes.StrDType[int][source]#

Convert the FixedLengthUTF32 instance to a NumPy data type.

Returns:

np.dtypes.StrDType[int]: The NumPy data type.

code_point_bytes: ClassVar[int] = 4#

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

length: int#

class zarr.dtype.FixedLengthUTF32JSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[str, None]

A wrapper around the JSON representation of the FixedLengthUTF32 data type in Zarr V2.

The name field of this class contains the value that would appear under the dtype field in Zarr V2 array metadata.

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": "<U12",
    "object_codec_id": None
}

class zarr.dtype.FixedLengthUTF32JSON_V3[source]#

Bases: zarr.core.common.NamedConfig[Literal['fixed_length_utf32'], LengthBytesConfig]

The JSON representation of the FixedLengthUTF32 data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

{
    "name": "fixed_length_utf32",
    "configuration": {
        "length_bytes": 12
}

configuration: typing_extensions.ReadOnly[TConfig]#: The configuration of the object.

name: typing_extensions.ReadOnly[TName]#: The name of the object.

class zarr.dtype.Float16[source]#

Bases: BaseFloat[numpy.dtypes.Float16DType, numpy.float16]

A Zarr data type for arrays containing 16-bit floating point numbers.

Wraps the np.dtypes.Float16DType data type. Scalars for this data type are instances of np.float16.

Attributes:

dtype_clsType[np.dtypes.Float16DType]: The NumPy dtype class for this data type.

References

This class implements the float16 data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → zarr.core.dtype.npy.common.TFloatScalar_co#

Cast a scalar value to a NumPy float scalar.

Parameters:

dataobject: The scalar value to cast.

Returns:

TFloatScalar_co: The NumPy float scalar.

default_scalar() → zarr.core.dtype.npy.common.TFloatScalar_co#

Get the default value, which is 0 cast to this zdtype.

Returns:

TFloatScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.dtype.npy.common.TFloatScalar_co#

Read a JSON-serializable value as a NumPy float scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

TFloatScalar_co: The NumPy float scalar.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self#

Create an instance of this ZDType from a NumPy data type.

Parameters:

dtypeTBaseDType: The NumPy data type.

Returns:

Self: An instance of this data type.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[str, None]#

to_json(zarr_format: Literal[3]) → str

Convert the wrapped data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The zarr format version.

Returns:

DTypeConfig_V2[str, None] or str: The JSON-serializable representation of the wrapped data type.

Raises:

ValueError: If zarr_format is not 2 or 3.

to_json_scalar( data: object, *, zarr_format: zarr.core.common.ZarrFormat, ) → float | str#

Convert an object to a JSON-serializable float.

Parameters:

data_BaseScalar: The value to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

JSON: The JSON-serializable form of the float, which is potentially a number or a string. See the zarr specifications for details on the JSON encoding for floats.

to_native_dtype() → zarr.core.dtype.npy.common.TFloatDType_co#

Convert the wrapped data type to a NumPy data type.

Returns:

TFloatDType_co: The NumPy data type.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Float32[source]#

Bases: BaseFloat[numpy.dtypes.Float32DType, numpy.float32]

A Zarr data type for arrays containing 32-bit floating point numbers.

Wraps the np.dtypes.Float32DType data type. Scalars for this data type are instances of np.float32.

Attributes:

dtype_clsType[np.dtypes.Float32DType]: The NumPy dtype class for this data type.

References

This class implements the float32 data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → zarr.core.dtype.npy.common.TFloatScalar_co#

Cast a scalar value to a NumPy float scalar.

Parameters:

dataobject: The scalar value to cast.

Returns:

TFloatScalar_co: The NumPy float scalar.

default_scalar() → zarr.core.dtype.npy.common.TFloatScalar_co#

Get the default value, which is 0 cast to this zdtype.

Returns:

TFloatScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.dtype.npy.common.TFloatScalar_co#

Read a JSON-serializable value as a NumPy float scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

TFloatScalar_co: The NumPy float scalar.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self#

Create an instance of this ZDType from a NumPy data type.

Parameters:

dtypeTBaseDType: The NumPy data type.

Returns:

Self: An instance of this data type.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[str, None]#

to_json(zarr_format: Literal[3]) → str

Convert the wrapped data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The zarr format version.

Returns:

DTypeConfig_V2[str, None] or str: The JSON-serializable representation of the wrapped data type.

Raises:

ValueError: If zarr_format is not 2 or 3.

to_json_scalar( data: object, *, zarr_format: zarr.core.common.ZarrFormat, ) → float | str#

Convert an object to a JSON-serializable float.

Parameters:

data_BaseScalar: The value to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

JSON: The JSON-serializable form of the float, which is potentially a number or a string. See the zarr specifications for details on the JSON encoding for floats.

to_native_dtype() → zarr.core.dtype.npy.common.TFloatDType_co#

Convert the wrapped data type to a NumPy data type.

Returns:

TFloatDType_co: The NumPy data type.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Float64[source]#

Bases: BaseFloat[numpy.dtypes.Float64DType, numpy.float64]

A Zarr data type for arrays containing 64-bit floating point numbers.

Wraps the np.dtypes.Float64DType data type. Scalars for this data type are instances of np.float64.

Attributes:

dtype_clsType[np.dtypes.Float64DType]: The NumPy dtype class for this data type.

References

This class implements the float64 data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → zarr.core.dtype.npy.common.TFloatScalar_co#

Cast a scalar value to a NumPy float scalar.

Parameters:

dataobject: The scalar value to cast.

Returns:

TFloatScalar_co: The NumPy float scalar.

default_scalar() → zarr.core.dtype.npy.common.TFloatScalar_co#

Get the default value, which is 0 cast to this zdtype.

Returns:

TFloatScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.dtype.npy.common.TFloatScalar_co#

Read a JSON-serializable value as a NumPy float scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

TFloatScalar_co: The NumPy float scalar.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self#

Create an instance of this ZDType from a NumPy data type.

Parameters:

dtypeTBaseDType: The NumPy data type.

Returns:

Self: An instance of this data type.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[str, None]#

to_json(zarr_format: Literal[3]) → str

Convert the wrapped data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The zarr format version.

Returns:

DTypeConfig_V2[str, None] or str: The JSON-serializable representation of the wrapped data type.

Raises:

ValueError: If zarr_format is not 2 or 3.

to_json_scalar( data: object, *, zarr_format: zarr.core.common.ZarrFormat, ) → float | str#

Convert an object to a JSON-serializable float.

Parameters:

data_BaseScalar: The value to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

JSON: The JSON-serializable form of the float, which is potentially a number or a string. See the zarr specifications for details on the JSON encoding for floats.

to_native_dtype() → zarr.core.dtype.npy.common.TFloatDType_co#

Convert the wrapped data type to a NumPy data type.

Returns:

TFloatDType_co: The NumPy data type.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Int16[source]#

Bases: BaseInt[numpy.dtypes.Int16DType, numpy.int16], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing 16-bit signed integers.

Wraps the np.dtypes.Int16DType data type. Scalars for this data type are instances of np.int16.

Attributes:

dtype_clsnp.dtypes.Int16DType: The class of the underlying NumPy dtype.

References

This class implements the 16-bit signed integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an instance of this data type from a np.dtype(‘int16’) instance.

Parameters:

dtypenp.dtype: The instance of np.dtype(‘int16’) to create from.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input data type is not an instance of np.dtype(‘int16’).

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['>i2', '<i2'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['int16']

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

DTypeConfig_V2[Literal[“>i2”, “<i2”], None] or Literal[“int16”]: The JSON representation of the Int16 instance.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.Int16DType[source]#

Convert the data type to a np.dtype(‘int16’) instance.

Returns:

np.dtype: The np.dtype(‘int16’) instance.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Int32[source]#

Bases: BaseInt[numpy.dtypes.Int32DType, numpy.int32], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing 32-bit signed integers.

Wraps the np.dtypes.Int32DType data type. Scalars for this data type are instances of np.int32.

Attributes:

dtype_clsnp.dtypes.Int32DType: The class of the underlying NumPy dtype.

References

This class implements the 32-bit signed integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an Int32 from a np.dtype(‘int32’) instance.

Parameters:

dtypeTBaseDType: The np.dtype(‘int32’) instance.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input JSON is not a valid representation of this class Int32.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['>i4', '<i4'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['int32']

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

DTypeConfig_V2[Literal[“>i4”, “<i4”], None] or Literal[“int32”]: The JSON representation of the Int32 instance.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.Int32DType[source]#

Convert the Int32 instance to a np.dtype(‘int32’) instance.

Returns:

np.dtypes.Int32DType: The np.dtype(‘int32’) instance.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Int64[source]#

Bases: BaseInt[numpy.dtypes.Int64DType, numpy.int64], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing 64-bit signed integers.

Wraps the np.dtypes.Int64DType data type. Scalars for this data type are instances of np.int64.

Attributes:

dtype_clsnp.dtypes.Int64DType: The class of the underlying NumPy dtype.

References

This class implements the 64-bit signed integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an Int64 from a np.dtype(‘int64’) instance.

Parameters:

dtypeTBaseDType: The NumPy data type.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input data type is not a valid representation of this class 64-bit signed integer.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['>i8', '<i8'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['int64']

Convert the data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The Zarr format version.

Returns:

DTypeConfig_V2[Literal[“>i8”, “<i8”], None] | Literal[“int64”]: The JSON-serializable representation of the data type.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.Int64DType[source]#

Create a NumPy signed 64-bit integer dtype instance from this Int64 ZDType.

Returns:

np.dtypes.Int64DType: The NumPy signed 64-bit integer dtype.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.Int8[source]#

Bases: BaseInt[numpy.dtypes.Int8DType, numpy.int8]

A Zarr data type for arrays containing 8-bit signed integers.

Wraps the np.dtypes.Int8DType data type. Scalars for this data type are instances of np.int8.

Attributes:

dtype_clsnp.dtypes.Int8DType: The class of the underlying NumPy dtype.

References

This class implements the 8-bit signed integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an Int8 from a np.dtype(‘int8’) instance.

Parameters:

dtypeTBaseDType: The np.dtype(‘int8’) instance.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input data type is not a valid representation of this class Int8.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['|i1'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['int8']

Convert the data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The Zarr format version.

Returns:

DTypeConfig_V2[Literal["|i1"], None] | Literal["int8"]: The JSON-serializable representation of the data type.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.Int8DType[source]#

Convert the Int8 instance to a np.dtype(‘int8’) instance.

Returns:

np.dtypes.Int8DType: The np.dtype(‘int8’) instance.

dtype_cls#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.NullTerminatedBytes[source]#

Bases: zarr.core.dtype.wrapper.ZDType[numpy.dtypes.BytesDType[int], numpy.bytes_], zarr.core.dtype.common.HasLength, zarr.core.dtype.common.HasItemSize

A Zarr data type for arrays containing fixed-length null-terminated byte sequences.

Wraps the np.dtypes.BytesDType data type. Scalars for this data type are instances of np.bytes_.

This data type is parametrized by an integral length which specifies size in bytes of each scalar. Because this data type uses null-terminated semantics, indexing into NumPy arrays with this data type may return fewer than length bytes.

Attributes:

dtype_cls: ClassVar[type[np.dtypes.BytesDType[int]]] = np.dtypes.BytesDType: The NumPy data type wrapped by this ZDType.
_zarr_v3_nameClassVar[Literal[“null_terminated_bytes”]]
lengthint: The length of the bytes.

Notes

This data type is designed for compatibility with NumPy arrays that use the NumPy bytes data type. It may not be desirable for usage outside of that context. If compatibility with the NumPy bytes data type is not essential, consider using the RawBytes or VariableLengthBytes data types instead.

cast_scalar(data: object) → numpy.bytes_[source]#

Attempt to cast a given object to a NumPy bytes scalar.

This method first checks if the provided data is a valid scalar that can be converted to a NumPy bytes scalar. If the check succeeds, the unchecked casting operation is performed. If the data is not valid, a TypeError is raised.

Parameters:

dataobject: The data to be cast to a NumPy bytes scalar.

Returns:

np.bytes_: The data cast as a NumPy bytes scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy bytes scalar.

default_scalar() → numpy.bytes_[source]#

Return a default scalar value, which for this data type is an empty byte string.

Returns:

np.bytes_: The default scalar value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → numpy.bytes_[source]#

Read a JSON-serializable value as np.bytes_.

Parameters:

dataJSON: The JSON-serializable base64-encoded string.
zarr_formatZarrFormat: The zarr format version.

Returns:

np.bytes_: The NumPy bytes scalar obtained from decoding the base64 string.

Raises:

TypeError: If the input data is not a base64-encoded string.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an instance of NullTerminatedBytes from an instance of np.dtypes.BytesDType.

This method checks if the provided data type is an instance of np.dtypes.BytesDType. If so, it returns a new instance of NullTerminatedBytes with a length equal to the length of input data type.

Parameters:

dtypeTBaseDType: The native dtype to convert.

Returns:

NullTerminatedBytes: An instance of NullTerminatedBytes with the specified length.

Raises:

DataTypeValidationError: If the dtype is not compatible with NullTerminatedBytes.

to_json(zarr_format: Literal[2]) → NullterminatedBytesJSON_V2[source]#

to_json(zarr_format: Literal[3]) → NullTerminatedBytesJSON_V3

Generate a JSON representation of this data type.

Parameters:

zarr_formatZarrFormat: The zarr format version.

Returns:

NullterminatedBytesJSON_V2 | NullTerminatedBytesJSON_V3: The JSON-serializable representation of the data type

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → str[source]#

Convert a scalar to a JSON-serializable string representation.

This method encodes the given scalar as a NumPy bytes scalar and then encodes the bytes as a base64-encoded string.

Parameters:

dataobject: The scalar to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

str: A string representation of the scalar.

to_native_dtype() → numpy.dtypes.BytesDType[int][source]#

Create a NumPy bytes dtype from this NullTerminatedBytes ZDType.

Returns:

np.dtypes.BytesDType[int]: A NumPy data type object representing null-terminated bytes with a specified length.

dtype_cls#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

length: int#

class zarr.dtype.NullTerminatedBytesJSON_V3[source]#

Bases: zarr.core.common.NamedConfig[Literal['null_terminated_bytes'], FixedLengthBytesConfig]

The JSON representation of the NullTerminatedBytes data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

{
    "name": "null_terminated_bytes",
    "configuration": {
        "length_bytes": 12
    }
}

class zarr.dtype.NullterminatedBytesJSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[str, None]

A wrapper around the JSON representation of the NullTerminatedBytes data type in Zarr V2.

The name field of this class contains the value that would appear under the dtype field in Zarr V2 array metadata.

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": "|S10",
    "object_codec_id": None
}

class zarr.dtype.RawBytes[source]#

Bases: zarr.core.dtype.wrapper.ZDType[numpy.dtypes.VoidDType[int], numpy.void], zarr.core.dtype.common.HasLength, zarr.core.dtype.common.HasItemSize

A Zarr data type for arrays containing fixed-length sequences of raw bytes.

Wraps the NumPy void data type. Scalars for this data type are instances of np.void.

This data type is parametrized by an integral length which specifies size in bytes of each scalar belonging to this data type.

Attributes:

dtype_cls: ClassVar[type[np.dtypes.VoidDType[int]]] = np.dtypes.VoidDtype: The NumPy data type wrapped by this ZDType.
_zarr_v3_nameClassVar[Literal[“raw_bytes”]]
lengthint: The length of the bytes.

Notes

Although the NumPy “Void” data type is used to create “structured” data types in NumPy, this class does not support structured data types.

See the Structured data type for this functionality.

cast_scalar(data: object) → numpy.void[source]#

Attempt to cast a given object to a NumPy void scalar.

This method first checks if the provided data is a valid scalar that can be converted to a NumPy void scalar. If the check succeeds, the unchecked casting operation is performed. If the data is not valid, a TypeError is raised.

Parameters:

dataobject: The data to be cast to a NumPy void scalar.

Returns:

np.void: The data cast as a NumPy void scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy void scalar.

default_scalar() → numpy.void[source]#

Return the default scalar value for this data type.

The default scalar is a NumPy void scalar of the same length as the data type, filled with zero bytes.

Returns:

np.void: The default scalar value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → numpy.void[source]#

Read a JSON-serializable value as a np.void.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

np.void: The NumPy void scalar.

Raises:

TypeError: If the data is not a string, or if the string is not a valid base64 encoding.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an instance of RawBytes from an instance of np.dtypes.VoidDType.

This method checks if the provided data type is compatible with RawBytes. The input must be an instance of np.dtypes.VoidDType, and have no fields. If the input is compatible, this method returns an instance of RawBytes with the specified length.

Parameters:

dtypeTBaseDType: The native dtype to convert.

Returns:

RawBytes: An instance of RawBytes with the specified length.

Raises:

DataTypeValidationError: If the dtype is not compatible with RawBytes.

to_json(zarr_format: Literal[2]) → RawBytesJSON_V2[source]#

to_json(zarr_format: Literal[3]) → RawBytesJSON_V3

Generate a JSON representation of this data type.

Parameters:

zarr_formatZarrFormat: The zarr format version.

Returns:

RawBytesJSON_V2 | RawBytesJSON_V3: The JSON-serializable representation of the data type.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → str[source]#

Convert a scalar to a JSON-serializable string representation.

This method converts the given scalar to bytes and then encodes the bytes as a base64-encoded string.

Parameters:

dataobject: The scalar to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

str: A string representation of the scalar.

to_native_dtype() → numpy.dtypes.VoidDType[int][source]#

Create a NumPy void dtype from this RawBytes ZDType.

Returns:

np.dtypes.VoidDType[int]: A NumPy data type object representing raw bytes with a specified length.

dtype_cls#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

length: int#

class zarr.dtype.RawBytesJSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[str, None]

A wrapper around the JSON representation of the RawBytes data type in Zarr V2.

The name field of this class contains the value that would appear under the dtype field in Zarr V2 array metadata.

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": "|V10",
    "object_codec_id": None
}

name: typing_extensions.ReadOnly[TDTypeNameV2_co]#

object_codec_id: typing_extensions.ReadOnly[TObjectCodecID_co]#

class zarr.dtype.RawBytesJSON_V3[source]#

Bases: zarr.core.common.NamedConfig[Literal['raw_bytes'], FixedLengthBytesConfig]

The JSON representation of the RawBytes data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

{
    "name": "raw_bytes",
    "configuration": {
        "length_bytes": 12

configuration: typing_extensions.ReadOnly[TConfig]#: The configuration of the object.

name: typing_extensions.ReadOnly[TName]#: The name of the object.

class zarr.dtype.Structured[source]#

Bases: zarr.core.dtype.wrapper.ZDType[numpy.dtypes.VoidDType[int], numpy.void], zarr.core.dtype.common.HasItemSize

A Zarr data type for arrays containing structured scalars, AKA “record arrays”.

Wraps the NumPy np.dtypes.VoidDType if the data type has fields. Scalars for this data type are instances of np.void, with a fields attribute.

Attributes:

fieldsSequence[tuple[str, ZDType]]: The fields of the structured dtype.

References

This data type does not have a Zarr V3 specification.

The Zarr V2 data type specification can be found here.

cast_scalar(data: object) → numpy.void[source]#

Cast a Python object to a NumPy structured scalar.

This function attempts to cast the provided data to a NumPy structured scalar. If the data is compatible with the structured scalar type, it is cast without type checking. Otherwise, a TypeError is raised.

Parameters:

dataobject: The data to be cast to a NumPy structured scalar.

Returns:

np.void: The data cast as a NumPy structured scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy structured scalar.

default_scalar() → numpy.void[source]#

Get the default scalar value for this structured data type.

Returns:

np.void: The default scalar value, which is the scalar representation of 0 cast to this structured data type.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → numpy.void[source]#

Read a JSON-serializable value as a NumPy structured scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The zarr format version.

Returns:

np.void: The NumPy structured scalar.

Raises:

TypeError: If the input is not a base64-encoded string.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create a Structured ZDType from a native NumPy data type.

Parameters:

dtypeTBaseDType: The native data type.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input data type is not an instance of np.dtypes.VoidDType with a non-null fields attribute.

Notes

This method attempts to resolve the fields of the structured dtype using the data type registry.

to_json(zarr_format: Literal[2]) → StructuredJSON_V2[source]#

to_json(zarr_format: Literal[3]) → StructuredJSON_V3

Convert the structured data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The Zarr format version. Accepted values are 2 and 3.

Returns:

StructuredJSON_V2 | StructuredJSON_V3: The JSON representation of the structured data type.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → str[source]#

Convert a scalar to a JSON-serializable string representation.

Parameters:

dataobject: The scalar to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

str: A string representation of the scalar, which is a base64-encoded string of the bytes that make up the scalar.

to_native_dtype() → numpy.dtypes.VoidDType[int][source]#

Convert the structured Zarr data type to a native NumPy void dtype.

This method constructs a NumPy dtype with fields corresponding to the fields of the structured Zarr data type, by converting each field’s data type to its native dtype representation.

Returns:

np.dtypes.VoidDType[int]: The native NumPy void dtype representing the structured data type.

dtype_cls#

fields: tuple[tuple[str, zarr.core.dtype.wrapper.ZDType[zarr.core.dtype.wrapper.TBaseDType, zarr.core.dtype.wrapper.TBaseScalar]], Ellipsis]#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.StructuredJSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[zarr.core.dtype.common.StructuredName_V2, None]

A wrapper around the JSON representation of the Structured data type in Zarr V2.

The name field is a sequence of sequences, where each inner sequence has two values: the field name and the data type name for that field (which could be another sequence). The data type names are strings, and the object codec ID is always None.

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": [
        ["f0", "<m8[10s]"],
        ["f1", "<m8[10s]"],
    ],
    "object_codec_id": None
}

class zarr.dtype.StructuredJSON_V3[source]#

Bases: zarr.core.common.NamedConfig[Literal['structured'], dict[str, collections.abc.Sequence[collections.abc.Sequence[str | zarr.core.dtype.common.DTypeJSON]]]]

A JSON representation of a structured data type in Zarr V3.

References

This representation is not currently defined in an external specification.

Examples

{
    "name": "structured",
    "configuration": {
        "fields": [
            ["f0", "int32],
            ["f1", "float64"],
        ]
    }
}

class zarr.dtype.TimeDelta64[source]#

Bases: TimeDTypeBase[numpy.dtypes.TimeDelta64DType, numpy.timedelta64], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing NumPy TimeDelta64 data.

Wraps the np.dtypesTimeDelta64DType data type. Scalars for this data type are instances of np.timedelta64.

Attributes:

dtype_clsType[np.dtypesTimeDelta64DType]: The NumPy dtype class for this data type.
scale_factorint: The scale factor for this data type.
unitDateTimeUnit: The unit for this data type.

References

The Zarr V2 representation of this data type is defined in the Zarr V2 specification document.

The Zarr V3 representation of this data type is defined in the numpy.timedelta64 specification document

cast_scalar(data: object) → numpy.timedelta64[source]#: Cast the input to a numpy timedelta64 scalar. If the input is not a scalar of this data type, raise a TypeError.

default_scalar() → numpy.timedelta64[source]#

Return a default scalar of this data type.

This method provides a default value for the timedelta64 scalar, which is a ‘Not-a-Time’ (NaT) value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → numpy.timedelta64[source]#

Create a scalar of this data type from JSON input.

Parameters:

dataJSON: The JSON representation of the scalar value.
zarr_formatint: The zarr format to use for the JSON representation.

Returns:

numpy.timedelta64: The scalar value of this data type.

Raises:

TypeError: If the input JSON is not a valid representation of a scalar for this data type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self#

Create an instance of this class from a native NumPy data type.

Parameters:

dtypeTBaseDType: The native NumPy dtype to convert.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the dtype is not a valid representation of this class.

to_json(zarr_format: Literal[2]) → TimeDelta64JSON_V2[source]#

to_json(zarr_format: Literal[3]) → TimeDelta64JSON_V3

Serialize this data type to JSON.

Parameters:

zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

TimeDelta64JSON_V2 | TimeDelta64JSON_V3: The JSON representation of the data type.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert a python object to a JSON representation of a datetime64 or timedelta64 scalar.

Parameters:

dataobject: The python object to convert.
zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

int: The JSON representation of the scalar.

to_native_dtype() → BaseTimeDType_co#

Convert this data type to a NumPy temporal data type with the appropriate unit and scale factor.

Returns:

BaseTimeDType_co: A NumPy data type object representing the time data type with the specified unit, scale factor, and byte order.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

scale_factor: int = 1#

unit: zarr.core.dtype.npy.common.DateTimeUnit = 'generic'#

class zarr.dtype.TimeDelta64JSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[str, None]

A wrapper around the JSON representation of the TimeDelta64 data type in Zarr V2.

The name field of this class contains the value that would appear under the dtype field in Zarr V2 array metadata.

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": "<m8[1s]",
    "object_codec_id": None
}

class zarr.dtype.TimeDelta64JSON_V3[source]#

Bases: zarr.core.common.NamedConfig[Literal['numpy.timedelta64'], TimeConfig]

The JSON representation of the TimeDelta64 data type in Zarr V3.

References

This representation is defined in the numpy.timedelta64 specification document.

Examples

{
    "name": "numpy.timedelta64",
    "configuration": {
        "unit": "ms",
        "scale_factor": 1
        }
}

configuration: typing_extensions.ReadOnly[TConfig]#: The configuration of the object.

name: typing_extensions.ReadOnly[TName]#: The name of the object.

class zarr.dtype.UInt16[source]#

Bases: BaseInt[numpy.dtypes.UInt16DType, numpy.uint16], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing 16-bit unsigned integers.

Wraps the np.dtypes.UInt16DType data type. Scalars for this data type are instances of np.uint16.

Attributes:

dtype_clsnp.dtypes.UInt16DType: The class of the underlying NumPy dtype.

References

This class implements the unsigned 16-bit unsigned integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an instance of this data type from a np.dtype(‘uint16’) instance.

Parameters:

dtypenp.dtype: The NumPy data type.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input data type is not an instance of np.dtype(‘uint16’).

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['>u2', '<u2'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['uint16']

Serialize this ZDType to v2- or v3-flavored JSON

Parameters:

zarr_formatZarrFormat: The Zarr format version (2 or 3).

Returns:

DTypeConfig_V2[Literal[“>u2”, “<u2”], None] or Literal[“uint16”]: The JSON representation of the UInt16 instance.

Raises:

ValueError: If the zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.UInt16DType[source]#

Convert the data type to a np.dtype(‘uint16’) instance.

Returns:

np.dtype: The np.dtype(‘uint16’) instance.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.UInt32[source]#

Bases: BaseInt[numpy.dtypes.UInt32DType, numpy.uint32], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing 32-bit unsigned integers.

Wraps the np.dtypes.UInt32DType data type. Scalars for this data type are instances of np.uint32.

Attributes:

dtype_clsnp.dtypes.UInt32DType: The class of the underlying NumPy dtype.

References

This class implements the 32-bit unsigned integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create a UInt32 from a np.dtype(‘uint32’) instance.

Parameters:

dtypeTBaseDType: The NumPy data type.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input data type is not a valid representation of this class 32-bit unsigned integer.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['>u4', '<u4'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['uint32']

Convert the data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The Zarr format version.

Returns:

DTypeConfig_V2[Literal[“>u4”, “<u4”], None] | Literal[“uint32”]: The JSON-serializable representation of the data type

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.UInt32DType[source]#

Create a NumPy unsigned 32-bit integer dtype instance from this UInt32 ZDType.

Returns:

np.dtypes.UInt32DType: The NumPy unsigned 32-bit integer dtype.

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.UInt64[source]#

Bases: BaseInt[numpy.dtypes.UInt64DType, numpy.uint64], zarr.core.dtype.common.HasEndianness

A Zarr data type for arrays containing 64-bit unsigned integers.

Wraps the np.dtypes.UInt64DType data type. Scalars for this data type are instances of np.uint64.

Attributes:

dtype_cls: np.dtypes.UInt64DType: The class of the underlying NumPy dtype.

References

This class implements the unsigned 64-bit integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an instance of this data type from a native NumPy dtype.

Parameters:

dtypeTBaseDType: The native NumPy dtype.

Returns:

Self: An instance of this data type.

Raises:

DataTypeValidationError: If the input dtype is not a valid representation of this class unsigned 64-bit integer.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['>u8', '<u8'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['uint64']

Convert the data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The Zarr format version.

Returns:

DTypeConfig_V2[Literal[“>u8”, “<u8”], None] | Literal[“uint64”]: The JSON-serializable representation of the data type.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.UInt64DType[source]#

Convert the data type to a native NumPy dtype.

Returns:

np.dtypes.UInt64DType: The native NumPy dtype.eeeeeeeeeeeeeeeee

dtype_cls#

endianness: EndiannessStr = 'little'#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.UInt8[source]#

Bases: BaseInt[numpy.dtypes.UInt8DType, numpy.uint8]

A Zarr data type for arrays containing 8-bit unsigned integers.

Wraps the np.dtypes.UInt8DType data type. Scalars for this data type are instances of np.uint8.

Attributes:

dtype_clsnp.dtypes.UInt8DType: The class of the underlying NumPy dtype.

References

This class implements the 8-bit unsigned integer data type defined in Zarr V2 and V3.

See the Zarr V2 and Zarr V3 specification documents for details.

cast_scalar(data: object) → TIntScalar_co#

Attempt to cast a given object to a NumPy integer scalar.

Parameters:

dataobject: The data to be cast to a NumPy integer scalar.

Returns:

TIntScalar_co: The data cast as a NumPy integer scalar.

Raises:

TypeError: If the data cannot be converted to a NumPy integer scalar.

default_scalar() → TIntScalar_co#

Get the default value, which is 0 cast to this dtype.

Returns:

TIntScalar_co: The default value.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TIntScalar_co#

Read a JSON-serializable value as a NumPy int scalar.

Parameters:

dataJSON: The JSON-serializable value.
zarr_formatZarrFormat: The Zarr format version.

Returns:

TIntScalar_co: The NumPy int scalar.

Raises:

TypeError: If the input is not a valid integer type.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#: Create a UInt8 from a np.dtype(‘uint8’) instance.

to_json( zarr_format: Literal[2], ) → zarr.core.dtype.common.DTypeConfig_V2[Literal['|u1'], None][source]#

to_json(zarr_format: Literal[3]) → Literal['uint8']

Convert the data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The Zarr format version. Supported values are 2 and 3.

Returns:

DTypeConfig_V2[Literal["|u1"], None] | Literal["uint8"]: The JSON-serializable representation of the data type.

Raises:

ValueError: If zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → int#

Convert an object to a JSON serializable scalar. For the integer data types, the JSON form is a plain integer.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The Zarr format version.

Returns:

int: The JSON-serializable form of the scalar.

to_native_dtype() → numpy.dtypes.UInt8DType[source]#

Create a NumPy unsigned 8-bit integer dtype instance from this UInt8 ZDType.

Returns:

np.dtypes.UInt8DType: The NumPy unsigned 8-bit integer dtype.

dtype_cls#

property item_size: int#

The size of a single scalar in bytes.

Returns:

int: The size of a single scalar in bytes.

class zarr.dtype.VariableLengthBytes[source]#

Bases: zarr.core.dtype.wrapper.ZDType[numpy.dtypes.ObjectDType, bytes], zarr.core.dtype.common.HasObjectCodec

A Zarr data type for arrays containing variable-length sequences of bytes.

Wraps the NumPy “object” data type. Scalars for this data type are instances of bytes.

Attributes:

dtype_cls: ClassVar[type[np.dtypes.ObjectDType]] = np.dtypes.ObjectDType: The NumPy data type wrapped by this ZDType.
_zarr_v3_name: ClassVar[Literal[“variable_length_bytes”]] = “variable_length_bytes”: The name of this data type in Zarr V3.
object_codec_id: ClassVar[Literal[“vlen-bytes”]] = “vlen-bytes”: The object codec ID for this data type.

Notes

Because this data type uses the NumPy “object” data type, it does not guarantee a compact memory representation of array data. Therefore a “vlen-bytes” codec is needed to ensure that the array data can be persisted to storage.

cast_scalar(data: object) → bytes[source]#

Attempt to cast a given object to a bytes scalar.

This method first checks if the provided data is a valid scalar that can be converted to a bytes scalar. If the check succeeds, the unchecked casting operation is performed. If the data is not valid, a TypeError is raised.

Parameters:

dataobject: The data to be cast to a bytes scalar.

Returns:

bytes: The data cast as a bytes scalar.

Raises:

TypeError: If the data cannot be converted to a bytes scalar.

default_scalar() → bytes[source]#

Return the default scalar value for the variable-length bytes data type.

Returns:

bytes: The default scalar value, which is an empty byte string.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → bytes[source]#

Decode a base64-encoded JSON string to bytes.

Parameters:

dataJSON: The JSON-serializable base64-encoded string.
zarr_formatZarrFormat: The zarr format version.

Returns:

bytes: The decoded bytes from the base64 string.

Raises:

TypeError: If the input data is not a base64-encoded string.

classmethod from_native_dtype(dtype: zarr.core.dtype.wrapper.TBaseDType) → Self[source]#

Create an instance of VariableLengthBytes from an instance of np.dtypes.ObjectDType.

This method checks if the provided data type is an instance of np.dtypes.ObjectDType. If so, it returns an instance of VariableLengthBytes.

Parameters:

dtypeTBaseDType: The native dtype to convert.

Returns:

VariableLengthBytes: An instance of VariableLengthBytes.

Raises:

DataTypeValidationError: If the dtype is not compatible with VariableLengthBytes.

to_json(zarr_format: Literal[2]) → VariableLengthBytesJSON_V2[source]#

to_json(zarr_format: Literal[3]) → Literal['variable_length_bytes']

Convert the variable-length bytes data type to a JSON-serializable form.

Parameters:

zarr_formatZarrFormat: The zarr format version. Accepted values are 2 and 3.

Returns:

DTypeConfig_V2[Literal["|O"], Literal["vlen-bytes"]] | Literal["variable_length_bytes"]: The JSON-serializable representation of the variable-length bytes data type. For zarr_format 2, returns a dictionary with “name” and “object_codec_id”. For zarr_format 3, returns a string identifier “variable_length_bytes”.

Raises:

ValueError: If zarr_format is not 2 or 3.

to_json_scalar(data: object, *, zarr_format: zarr.core.common.ZarrFormat) → str[source]#

Convert a scalar to a JSON-serializable string representation.

This method encodes the given scalar as bytes and then encodes the bytes as a base64-encoded string.

Parameters:

dataobject: The scalar to convert.
zarr_formatZarrFormat: The zarr format version.

Returns:

str: A string representation of the scalar.

to_native_dtype() → numpy.dtypes.ObjectDType[source]#

Create a NumPy object dtype from this VariableLengthBytes ZDType.

Returns:

np.dtypes.ObjectDType: A NumPy data type object representing variable-length bytes.

dtype_cls#

object_codec_id: ClassVar[Literal['vlen-bytes']] = 'vlen-bytes'#

class zarr.dtype.VariableLengthBytesJSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[Literal['|O'], Literal['vlen-bytes']]

A wrapper around the JSON representation of the VariableLengthBytes data type in Zarr V2.

The name field of this class contains the value that would appear under the dtype field in Zarr V2 array metadata. The object_codec_id field is always "vlen-bytes"

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": "|O",
    "object_codec_id": "vlen-bytes"
}

name: typing_extensions.ReadOnly[TDTypeNameV2_co]#

object_codec_id: typing_extensions.ReadOnly[TObjectCodecID_co]#

class zarr.dtype.VariableLengthUTF8[source]#

Bases: UTF8Base[numpy.dtypes.StringDType]

A Zarr data type for arrays containing variable-length UTF-8 strings.

Wraps the np.dtypes.StringDType data type. Scalars for this data type are instances of str.

Attributes:

dtype_clsType[np.dtypes.StringDType]: The NumPy dtype class for this data type.
_zarr_v3_nameClassVar[Literal[“variable_length_utf8”]] = “variable_length_utf8”: The name of this data type in Zarr V3.
object_codec_idClassVar[Literal[“vlen-utf8”]] = “vlen-utf8”: The object codec ID for this data type.

to_native_dtype() → numpy.dtypes.StringDType[source]#

Create a NumPy string dtype from this VariableLengthUTF8 ZDType.

Returns:

np.dtypes.StringDType: The NumPy string dtype.

dtype_cls#

class zarr.dtype.VariableLengthUTF8JSON_V2[source]#

Bases: zarr.core.dtype.common.DTypeConfig_V2[Literal['|O'], Literal['vlen-utf8']]

A wrapper around the JSON representation of the VariableLengthUTF8 data type in Zarr V2.

The name field of this class contains the value that would appear under the dtype field in Zarr V2 array metadata. The object_codec_id field is always "vlen-utf8".

References

The structure of the name field is defined in the Zarr V2 specification document.

Examples

{
    "name": "|O",
    "object_codec_id": "vlen-utf8"
}

name: typing_extensions.ReadOnly[TDTypeNameV2_co]#

object_codec_id: typing_extensions.ReadOnly[TObjectCodecID_co]#

class zarr.dtype.ZDType[source]#

Bases: abc.ABC, Generic[TDType_co, TScalar_co]

Abstract base class for wrapping native array data types, e.g. numpy dtypes

Attributes:

dtype_clsClassVar[type[TDType]]: The wrapped dtype class. This is a class variable.
_zarr_v3_nameClassVar[str]: The name given to the data type by a Zarr v3 data type specification. This is a class variable, and it should generally be unique across different data types.

abstract cast_scalar(data: object) → TScalar_co[source]#

Cast a python object to the wrapped scalar type.

The type of the provided scalar is first checked for compatibility. If it’s incompatible with the associated scalar type, a TypeError will be raised.

Parameters:

dataobject: The python object to cast.

Returns:

TScalar: The cast value.

abstract default_scalar() → TScalar_co[source]#

Get the default scalar value for the wrapped data type.

This is a method, rather than an attribute, because the default value for some data types depends on parameters that are not known until a concrete data type is wrapped. For example, data types parametrized by a length like fixed-length strings or bytes will generate scalars consistent with that length.

Returns:

TScalar: The default value for this data type.

classmethod from_json( data: zarr.core.dtype.common.DTypeJSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → Self[source]#

Create an instance of this ZDType from JSON data.

Parameters:

dataDTypeJSON: The JSON representation of the data type.
zarr_formatZarrFormat: The zarr format version.

Returns:

Self: An instance of this data type.

abstract from_json_scalar( data: zarr.core.common.JSON, *, zarr_format: zarr.core.common.ZarrFormat, ) → TScalar_co[source]#

Read a JSON-serializable value as a scalar.

Parameters:

dataJSON: A JSON representation of a scalar value.
zarr_formatZarrFormat: The zarr format version. This is specified because the JSON serialization of scalars differs between Zarr V2 and Zarr V3.

Returns:

TScalar: The deserialized scalar value.

classmethod from_native_dtype(dtype: TBaseDType) → Self[source]#

Abstractmethod:

Create a ZDType instance from a native data type.

This method is used when taking a user-provided native data type, like a NumPy data type, and creating the corresponding ZDType instance from them.

Parameters:

dtypeTDType: The native data type object to wrap.

Returns:

Self: The ZDType that wraps the native data type.

Raises:

TypeError: If the native data type is not consistent with the wrapped data type.

to_json(zarr_format: Literal[2]) → zarr.core.dtype.common.DTypeSpec_V2[source]#

to_json(zarr_format: Literal[3]) → zarr.core.dtype.common.DTypeSpec_V3

Serialize this ZDType to JSON.

Parameters:

zarr_formatZarrFormat: The zarr format version.

Returns:

DTypeJSON_V2 | DTypeJSON_V3: The JSON-serializable representation of the wrapped data type

abstract to_json_scalar( data: object, *, zarr_format: zarr.core.common.ZarrFormat, ) → zarr.core.common.JSON[source]#

Serialize a python object to the JSON representation of a scalar.

The value will first be cast to the scalar type associated with this ZDType, then serialized to JSON.

Parameters:

dataobject: The value to convert.
zarr_formatZarrFormat: The zarr format version. This is specified because the JSON serialization of scalars differs between Zarr V2 and Zarr V3.

Returns:

JSON: The JSON-serialized scalar.

abstract to_native_dtype() → TDType_co[source]#

Return an instance of the wrapped data type. This operation inverts from_native_dtype.

Returns:

TDType: The native data type wrapped by this ZDType.

dtype_cls: ClassVar[type[TDType_co]]#

zarr.dtype.parse_dtype( dtype_spec: ZDTypeLike, *, zarr_format: zarr.core.common.ZarrFormat, ) → wrapper.ZDType[wrapper.TBaseDType, wrapper.TBaseScalar][source]#

Convert the input as a ZDType.

Parameters:

dtype_specZDTypeLike: The input to be converted to a ZDType. This could be a ZDType, which will be returned directly, or a JSON representation of a ZDType, or a numpy dtype, or a python object that can be converted into a native dtype.
zarr_formatZarrFormat: The Zarr format version. This parameter is required because this function will attempt to parse the JSON representation of a data type, and the JSON representation of data types varies between Zarr 2 and Zarr 3.

Returns:

ZDType[TBaseDType, TBaseScalar]: The ZDType corresponding to the input.

Examples

>>> from zarr.dtype import parse_dtype
>>> import numpy as np
>>> parse_dtype("int32", zarr_format=2)
Int32(endianness='little')
>>> parse_dtype(np.dtype('S10'), zarr_format=2)
NullTerminatedBytes(length=10)
>>> parse_dtype({"name": "numpy.datetime64", "configuration": {"unit": "s", "scale_factor": 10}}, zarr_format=3)
DateTime64(endianness='little', scale_factor=10, unit='s')

zarr.dtype.data_type_registry#

zarr.dtype#

Attributes#

Exceptions#

Classes#

Functions#

Module Contents#

This Page